ofdsdk

ofdsdk 是一个面向 Rust 的 OFD SDK。

项目目标：

基于 OFD XSD 生成强类型 Rust 结构
提供稳定的 XML 反序列化与序列化能力
在启用 parts 特性后，提供 OFD 包级别的读取与保存能力
将现实世界中的兼容性差异收敛到生成数据，而不是在运行时散落特判

当前版本为 0.1.0。

当前能力

已提供：

基于 schemas/ 生成的 Rust schema 类型
XML 字符串与 Reader 的反序列化
XML 序列化输出
parts 特性下的 OFD 压缩包读取与保存
基于样例文件的 OFD 包级测试覆盖

当前仓库包含三个 crate：

crates/ofdsdk：运行时库，对外使用
crates/ofdsdk-build：代码生成器
crates/ofdsdk-test：集成测试与样例验证

安装

如果只需要 XML schema 类型：

[dependencies]
ofdsdk = "0.1.0"

如果还需要读取 .ofd 压缩包：

[dependencies]
ofdsdk = { version = "0.1.0", features = ["parts"] }

当前最低 Rust 版本为 1.88。

快速开始

1. 解析和写回 OFD XML

use ofdsdk::schemas::ofd::Ofd;

fn main() -> Result<(), ofdsdk::common::SdkError> {
  let xml = r#"<ofd:OFD xmlns:ofd="http://www.ofdspec.org/2016" DocType="OFD" Version="1.0">
<ofd:DocBody>
<ofd:DocInfo>
<ofd:DocID>doc-id</ofd:DocID>
</ofd:DocInfo>
<ofd:DocRoot>Doc_0/Document.xml</ofd:DocRoot>
</ofd:DocBody>
</ofd:OFD>"#;

  let ofd: Ofd = xml.parse()?;
  let out = ofd.to_xml().unwrap();

  assert!(out.contains("Doc_0/Document.xml"));
  Ok(())
}

2. 读取 OFD 包

use ofdsdk::parts::ofd_package::OfdPackage;

fn main() -> Result<(), ofdsdk::common::SdkError> {
  let package = OfdPackage::new_from_file("example.ofd")?;

  assert_eq!(package.documents.len(), 1);

  let document = &package.documents[0];
  println!("pages = {}", document.pages.len());
  println!("public_res = {}", document.public_res.len());

  Ok(())
}

API 概览

常用入口：

ofdsdk::schemas::*
ofdsdk::deserializers::*
ofdsdk::serializers::*
ofdsdk::parts::*（需要启用 parts）

其中：

schemas 提供生成出的结构定义
deserializers 提供 XML 读入逻辑
serializers 提供 XML 输出逻辑
parts 提供 OFD 包内部部件的装配读取

设计说明

1. `schemas/` 是真源

仓库中的 schemas/*.xsd 是模型来源。

生成流程大致为：

读取 XSD
生成 sdk_data/schemas/*.json
生成 crates/ofdsdk/src/schemas/
生成对应的反序列化、序列化和 parts 代码

2. compatibility 不是运行时特判集合

兼容策略集中放在：

sdk_data/compatibility.json

它的目标不是无限制放宽输入，而是将已确认的现实差异显式记录，并在生成阶段统一吸收。

3. `parts` 是包装配模型

parts 相关定义位于：

sdk_data/parts/*.json

它描述的是：

一个 part 的根类型是什么
路径如何取得
子 part 如何递归装配
哪些 part 之间存在上下文关联

当前状态

0.1.0 已经可以用于：

OFD schema 结构映射
XML round-trip
一批真实样例的 OFD 包读取验证

但仍然建议把它看作一个偏底层、偏工程化的 SDK，而不是“拿来即读一切 OFD”的通用阅读器。

开发

常用命令：

cargo test -p ofdsdk-build test_gen -- --ignored --nocapture
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
cargo test -p ofdsdk-test
cargo test --workspace

如果修改了：

schemas/*.xsd
sdk_data/compatibility.json
sdk_data/parts/*.json
crates/ofdsdk-build

建议重新执行生成测试并检查生成结果。

许可证

本项目使用双许可证：

MIT
Apache-2.0

你可以任选其一使用。

ofdsdk 0.1.0