Specta 工作区架构与发布机制揭秘:16 个 crate 如何协同构建 Rust 类型导出与 crates.io 可信发布
Specta 工作区架构与发布机制揭秘:16 个 crate 如何协同构建 Rust 类型导出与 crates.io 可信发布
📦 Specta 是一个帮你"把 Rust 类型轻松导出到其他语言"的开源工具:你在 Rust 里定义好 struct 和 enum,它就能生成 TypeScript、Swift、OpenAPI、Go、Kotlin 等 12+ 种语言的类型定义。今天不写代码,带你钻进源码仓库,看看这个由 16 个 crate 组成的 Cargo 工作区是如何协同构建的,以及它如何通过 crates.io 可信发布(Trusted Publishing) 做到仓库里一个长期令牌都不存。
一、工作区总览:一行通配符拉起 20+ 个 crate
打开根目录的 Cargo.toml,第一行就是整个仓库的组织方式:
[workspace]
members = ["specta", "specta-*", "tests", "examples/*"]
resolver = "2"
一行 members 配置拆解开来其实是四类成员:
| 成员 | 数量 | 角色 |
|---|---|---|
specta |
1 | 核心 crate,类型收集与导出 API |
specta-* |
16 | 宏、Serde 解析、工具库和 12 个语言导出器 |
tests |
1 | 集成测试与快照测试(specta-tests) |
examples/* |
5 | 可直接运行的示例工程 |
这种"通配符纳管"的方式意味着:新增一个语言导出器只需要建一个 specta-xxx 目录,就会被工作区自动收编,共享统一的依赖解析(resolver = "2")和质量标准。
统一的质量底线:workspace lints
根 Cargo.toml 通过 [workspace.lints] 给所有成员 crate 统一了"代码纪律",子 crate 只需声明 [lints] workspace = true 即可继承:
unsafe_code、missing_docs为warn级别;- Clippy 开启
all、cargo、unwrap_used、panic等严格检查; - 同时把
too_many_arguments、type_complexity等"过于唠叨"的规则设为allow,注释里还有一句开发者心声:"I hate these. For internal code I don't care." 😄
这套机制让 16 个 crate 的代码风格、文档要求完全一致,不用在每个子 crate 里重复配置。
二、16 个 crate 的分层架构:谁依赖谁?
Specta 的 crate 划分非常清晰,按职责可以分为四层:
┌─ 应用层 ─────────────────────────────────────┐
│ specta-typescript / swift / openapi / go ... │ ← 12 个语言导出器
├─ 支撑层 ─────────────────────────────────────┤
│ specta-util(高层工具) │
├─ 基础层 ─────────────────────────────────────┤
│ specta-serde(Serde 语义解析/校验) │
│ specta-macros(derive 宏,生成代码) │
├─ 核心层 ─────────────────────────────────────┤
│ specta(类型模型 + 类型注册表 Types) │
└──────────────────────────────────────────────┘
各层 crate 一览
| Crate | 当前版本 | 职责 |
|---|---|---|
| specta | 2.0.0-rc.28 |
核心:Type trait、Types 注册表,支持 40+ 常见生态类型的 feature 开关 |
| specta-macros | 2.0.0-rc.28 |
处理 #[derive(Type)] 的过程宏(描述写着 "Don't use directly!") |
| specta-serde | 0.0.15 |
解析 #[serde(...)] 属性,保证导出结构与 Serde 序列化完全一致 |
| specta-util | 0.0.15 |
高层工具,如类型选择与重映射(selection/remapper) |
12 个 specta-<lang> |
0.0.3~0.0.15 |
TypeScript、Swift(✅ 稳定),OpenAPI、JSON Schema、Go、Kotlin、Python、C#、Java、Zod、Valibot、Rust 等 |
几个值得注意的细节:
- 每个导出器都把
specta钉死在精确版本。例如 specta-typescript/Cargo.toml 里是specta = { version = "=2.0.0-rc.28", path = "../specta" }。=号意味着"只认这一个版本",这样语言导出器永远不会误用旧版核心。 path依赖 + 精确版本的组合,让本地开发用源码路径、发布到 crates.io 后仍按精确版本解析,两边行为一致。- 核心 crate 的 40 多个 feature(
uuid、chrono、tokio、bevy_ecs……)全部默认关闭,specta/Cargo.toml 中每个 feature 还带着##注释——这些注释会被同步渲染到文档站的 feature 列表里。
三、版本协同:整个工作区"锁步"升版本 📦
多 crate 工作区发布最大的痛点是版本错位——A 升了 2.0、B 还停在 1.9,用户装下来直接编译失败。Specta 的答案是"锁步发布(lockstep release)":
- 所有 crate 的版本号一起 bump(发布前把每个
Cargo.toml的version统一改好); - 发布 tag 的名字就是核心
specta的版本号,例如v2.0.0-rc.28; - 因为导出器用
=精确版本依赖specta,所以specta一变,所有导出器都必须跟着重新发布。
这个约定在 README.md 的 Releasing 一节写得很直白:"Cargo refuses to publish a version that already exists on crates.io"——crates.io 的版本不可覆盖,所以每次发布都是一次全新的版本号。
四、发布流水线:从一个 tag 到 16 个 crate 上架 🚀
整个发布流程由 .github/workflows/release.yml 驱动,推一个 v* 开头的 tag 即触发,分为两阶段:
第 1 阶段:Verify(验证)
release.yml 的 verify job 会依次做四件事:
- tag 与版本号对账:用
cargo metadata读出specta的version,与 tag 名比对,不一致直接报错退出; cargo build --all-features全特性构建;cargo test --all-features全特性测试(并通过SPECTA_REQUIRE_NODE=1把"缺 Node 就跳过"变成"缺 Node 就失败");cargo build --all --no-default-features验证无默认特性的最小构建。
第 2 阶段:Publish(发布)——可信发布的精髓 🔒
publish job 的设计是本文最值得学习的地方:
- 零长期令牌:它没有在任何 secrets 里存
CARGO_REGISTRY_TOKEN,而是通过permissions: id-token: write向 GitHub 申请 OIDC 身份令牌,再由rust-lang/crates-io-auth-action用它换取一个短时效的 crates.io 令牌。文件头部注释原话:"no long-livedCARGO_REGISTRY_TOKENis stored in this repository or in Actions secrets"。 - 四字段必须严丝合缝:crates.io 上配置的 trusted publisher 的 Owner(
specta-rs)、Repository(specta)、Workflow(release.yml)、Environment(release)四项必须与工作流完全一致,否则令牌交换会被拒绝。16 个可发布 crate 每个都要单独配置一次。 - 人工审批闸门:publish job 声明了
environment: release,在 GitHub 环境里配置 required reviewers 后,任何 tag 推送都不会自动上架,必须有人点"批准"。 - 按依赖顺序整仓发布:核心命令是
cargo publish --workspace --locked。--locked强制使用已提交的Cargo.lock,保证发布的版本组合与 CI 测过的完全一致;--workspace则让 Cargo 自动按依赖顺序(先发核心,再发导出器)逐个上架。 - 最后用
gh release create自动生成 GitHub Release 说明,收尾。
💡 这套"OIDC 换短令牌 + 环境审批 +
--locked"的组合,是目前 Rust 多 crate 工作区发布到 crates.io 的高可信范本。
五、CI 质量门:发布之前还要过多少关?
.github/workflows/ci.yml 在每次 push / PR 时构建了比发布更宽的防线:
- 三平台矩阵:ubuntu / macOS / Windows 上分别执行
cargo build --all-features、cargo test --all-features和无默认特性构建; - Clippy 检查:单独 job 跑
--all-features的 clippy; - 生成代码的语言侧验证:这是最有趣的部分——Specta 导出的是"代码",光靠 Rust 测试不够,CI 会为每种语言真的跑一遍类型检查:
- zod job:在 tests/zod-typecheck 里用 bun 装依赖并
bun run test; - typescript job:对生成的 TS 绑定做 typecheck;
- valibot 与 rescript job 同理;
typescript-precedencejob 额外安装tsc并固定SPECTA_TSC,验证生成类型之间的可赋值性。
- zod job:在 tests/zod-typecheck 里用 bun 装依赖并
也就是说,一个"Rust 类型 → 12 种语言类型"的转换,在合入前会经历 Rust 侧快照测试(tests/tests/snapshots 下有数百个 .snap 文件)+ 语言侧真实编译器验证 双重把关。
六、新手可以借鉴的 5 个实践 ✅
| 实践 | 出处 | 收益 |
|---|---|---|
通配符管理成员 specta-* |
Cargo.toml | 新增 crate 零配置,自动纳入统一 lint |
[workspace.lints] 集中定义代码规范 |
Cargo.toml | 16 个 crate 风格一致 |
导出器用 =精确版本 锁定核心依赖 |
specta-typescript/Cargo.toml | 杜绝版本漂移 |
| tag 名 = 核心 crate 版本号 + 自动对账 | release.yml | 发布即校验,出错即阻断 |
| crates.io 可信发布 + release 环境审批 | release.yml | 仓库零长期令牌,发布需人工批准 |
总结
Specta 工作区的巧妙之处在于:用极简的结构承载极宽的生态——一个核心 specta、16 个 specta-* 协同 crate、1 个测试 crate、5 个示例,靠通配符成员 + 锁步版本 + 统一 lint 拧成一股绳;发布侧则用 OIDC 短令牌、环境审批和 --locked 全仓发布,把"16 个 crate 同时上架"这件容易出错的事,做成了"推一个 tag、点一次批准"的可信自动化。
想动手体验的话,可以从 examples/basic-ts 跑起,或深入 specta/src 看看类型模型是如何把 Rust 的 struct / enum 抽象成跨语言通用的 datatype 树的。
