Specta 工作区架构与发布机制揭秘:16 个 crate 如何协同构建 Rust 类型导出与 crates.io 可信发布

原创2026-11-07 19:56:152,175 阅读

Specta 工作区架构与发布机制揭秘:16 个 crate 如何协同构建 Rust 类型导出与 crates.io 可信发布

📦 Specta 是一个帮你"把 Rust 类型轻松导出到其他语言"的开源工具:你在 Rust 里定义好 struct 和 enum,它就能生成 TypeScript、Swift、OpenAPI、Go、Kotlin 等 12+ 种语言的类型定义。今天不写代码,带你钻进源码仓库,看看这个由 16 个 crate 组成的 Cargo 工作区是如何协同构建的,以及它如何通过 crates.io 可信发布(Trusted Publishing) 做到仓库里一个长期令牌都不存。

Specta 项目 Logo——Rust 类型导出工具的工作区吉祥物

一、工作区总览:一行通配符拉起 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 等

几个值得注意的细节:

  1. 每个导出器都把 specta 钉死在精确版本。例如 specta-typescript/Cargo.toml 里是 specta = { version = "=2.0.0-rc.28", path = "../specta" }。= 号意味着"只认这一个版本",这样语言导出器永远不会误用旧版核心。
  2. path 依赖 + 精确版本的组合,让本地开发用源码路径、发布到 crates.io 后仍按精确版本解析,两边行为一致。
  3. 核心 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 会依次做四件事:

  1. tag 与版本号对账:用 cargo metadata 读出 specta 的 version,与 tag 名比对,不一致直接报错退出;
  2. cargo build --all-features 全特性构建;
  3. cargo test --all-features 全特性测试(并通过 SPECTA_REQUIRE_NODE=1 把"缺 Node 就跳过"变成"缺 Node 就失败");
  4. 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-lived CARGO_REGISTRY_TOKEN is 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-precedence job 额外安装 tsc 并固定 SPECTA_TSC,验证生成类型之间的可赋值性。

也就是说,一个"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 树的。

登录后查看全文
specta