Rust workspace 依赖集中配置记录

日期：2026-05-07

1. 背景

server-rs workspace 已经包含 api-server、spacetime-module、spacetime-client、多个 module-* 领域 crate、platform-* 适配 crate 和共享 crate。随着 DDD 收口推进，成员 Cargo.toml 中重复散写了第三方 crate 版本和本地 path 依赖，后续升级 serde、reqwest、tokio、time、SpacetimeDB SDK 或内部 crate 路径时容易出现漂移。

本次只做 Cargo 配置收敛，不改变业务代码、表结构、reducer/procedure 签名、HTTP contract 或前端绑定。

2. 配置规则

共享第三方依赖版本统一维护在 server-rs/Cargo.toml 的 [workspace.dependencies]。
workspace 内部 crate 的 path 也统一维护在根 server-rs/Cargo.toml。
成员 crate 默认使用 { workspace = true } 继承依赖。
成员 crate 只保留自身需要表达的差异，例如 features、optional = true 或 target-specific dependency。
需要关闭 default features 的依赖，应优先在 workspace 根依赖中声明；成员 crate 不再重复覆盖同一项。
module-assets 这类有默认服务端 feature 的领域 crate，在 workspace 根内按 default-features = false 维护；需要服务端 OSS/HTTP 能力的 adapter crate 显式启用 features = ["server-service"]。
shared-contracts 只能承载前后端公开 DTO 和轻量枚举，禁止直接依赖 platform-* 服务实现 crate；需要把平台实现响应转换为公开 DTO 时，转换函数放在 api-server 等 adapter 层。
面向 SpacetimeDB WASM 的依赖链不得隐式启用原生 HTTP / OSS / Web 平台依赖；例如 shared-contracts 的 assets 模块通过不依赖 platform-oss 的 oss-contracts feature 暴露给 api-server，spacetime-module 路径只消费关闭默认 feature 后的纯 DTO 子集。
spacetime-module 的传递依赖不能包含 reqwest、web-sys、js-sys、wasm-bindgen 等 Web/HTTP 客户端链路；发布前可用 cargo tree -i wasm-bindgen --manifest-path server-rs/Cargo.toml -p spacetime-module --target wasm32-unknown-unknown 排查。

3. 本次收敛范围

已上提到 workspace 根的依赖包括：

本地路径依赖：module-*、platform-*、shared-*、spacetime-client。
常用第三方依赖：serde、serde_json、serde_urlencoded、reqwest、tokio、time、tracing、base64、hmac、sha2、uuid、url 等。
SpacetimeDB 相关依赖：spacetimedb、spacetimedb-sdk、spacetimedb-lib。

spacetimedb-lib 在 workspace 根统一关闭 default features，spacetime-module 只继承并补充 features = ["serde"]。这样避免成员 crate 尝试覆盖 workspace default-feature 设定导致 manifest 解析失败。

阿里云 OSS 相关签名不再依赖不推荐的 sha1 crate，统一使用 sha2::Sha256：

浏览器直传 ticket 使用 OSS V4 表单签名字段：x-oss-signature-version=OSS4-HMAC-SHA256、x-oss-credential、x-oss-date、x-oss-signature。
服务端 OSS 读写请求和测试辅助签名统一使用 OSS4-HMAC-SHA256 Authorization。
阿里云短信 OpenAPI 请求统一使用 ACS3-HMAC-SHA256 请求头签名，不再在表单中传旧 SignatureMethod=HMAC-SHA1 / SignatureVersion=1.0。

4. 不在本次范围

不新增或删除 crate。
不修改 server-rs workspace members / default-members 语义。
不修改 SpacetimeDB 表、reducer、procedure、migration 白名单或生成绑定。
不改变 module-* 的 DDD 依赖方向。

5. 验收口径

配置改动后至少执行：

cargo metadata --manifest-path server-rs\Cargo.toml --format-version 1 --no-deps
cargo check -p api-server --manifest-path server-rs\Cargo.toml
cargo check -p spacetime-module --manifest-path server-rs\Cargo.toml
npm.cmd run check:server-rs-ddd
npm.cmd run check:encoding -- docs/technical/RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md docs/technical/README.md server-rs/README.md .hermes/shared-memory/decision-log.md .hermes/shared-memory/project-overview.md

若仅改 Cargo 依赖配置且未触碰 API smoke 相关代码，不强制启动 npm run api-server；若后续改动同时涉及 API 路由、SpacetimeDB facade 或运行时行为，仍按 AGENTS.md 和 DDD 文档执行后端 smoke。

6. SpacetimeDB WASM 依赖边界

2026-05-11 本地重置 SpacetimeDB 并重新发布 xushi-p4wfr 时，spacetime publish 在 Rust 编译成功后报 wasm-bindgen detected。排查命令显示链路为：

spacetime-module -> module-runtime -> shared-contracts -> platform-oss -> reqwest -> wasm-bindgen

根因是 shared-contracts 为了复用 OSS 直传/读签名返回类型，直接依赖了 platform-oss。这违反 DDD 分层边界：契约 crate 不能依赖平台副作用实现，否则所有引用契约的纯领域和 SpacetimeDB 模块都会被迫拉入 HTTP client。

spacetime publish 会构建 spacetime-module 的 wasm32-unknown-unknown 目标。这个目标不能包含 wasm-bindgen，也不应通过 DTO crate 间接拉入 reqwest、web-sys 或浏览器 WebAssembly 平台依赖。

修正口径：

shared-contracts::assets 定义独立的公开 DTO 和 DirectUploadObjectAccess 轻量枚举。
platform-oss 保持 OSS 签名、读写请求和错误分类实现，不被契约层引用。
api-server::assets 负责把 platform_oss::OssPostObjectResponse / OssSignedGetObjectUrlResponse 转成 shared-contracts DTO。
后续新增外部平台能力时，重复使用这个边界：平台 crate 不得被 shared-contracts、module-* 或 spacetime-module 反向依赖。

已验证的排查命令：

cargo tree -i wasm-bindgen --manifest-path server-rs\Cargo.toml -p spacetime-module --target wasm32-unknown-unknown
cargo tree -i wasm-bindgen --manifest-path server-rs\crates\spacetime-module\Cargo.toml --target wasm32-unknown-unknown
cargo tree --manifest-path server-rs\crates\spacetime-module\Cargo.toml --target wasm32-unknown-unknown | Select-String -Pattern 'wasm-bindgen|platform-oss|reqwest'
cargo check -p spacetime-module --manifest-path server-rs\Cargo.toml --target wasm32-unknown-unknown
cargo check -p shared-contracts --manifest-path server-rs\Cargo.toml
cargo check -p api-server --manifest-path server-rs\Cargo.toml
spacetime publish xushi-p4wfr --server local --module-path server-rs\crates\spacetime-module --build-options="--debug" -c=on-conflict --yes

若反向树显示 reqwest -> platform-oss -> shared-contracts -> module-* -> spacetime-module，优先检查新增的 shared-contracts 或领域 crate 依赖是否忘记关闭默认 feature，或 shared-contracts feature 是否错误依赖了平台实现 crate。原生 api-server 需要资产上传契约时，应在自身 Cargo.toml 显式启用 shared-contracts 的 oss-contracts feature，而不是让 workspace 根依赖默认启用。

6.9 KiB Raw Permalink Blame History Unescape Escape