Cargo 工作区项目复盘：多 crate 管理的得与失的经验总结

Cargo 工作区项目复盘：多 crate 管理的得与失的经验总结

一、workspace 的起点：8 个 crate 是怎么长出来的

项目一开始只有 3 个 crate：pipeline-core、shared-types、api-server。但随着功能叠加，三个月后变成了 8 个：

最后一个shared-utils是一个教训。它的诞生过程是：我和另一位同事都在各自的 crate 里写了一个retry_with_backoff函数，功能几乎一样。我们觉得"应该抽公共模块"，于是创建了shared-utils。但这个 crate 逐渐变成了一个"垃圾桶"——任何两个人觉得"以后可能会用到"的东西都往里塞。

二、Cargo.toml 的 features 设计 —— 对一个关键决策的复盘

pipeline-core有一个features配置，它控制着不同能力模块的编译开关：

# ============================================================ # pipeline-core/Cargo.toml — features 设计复盘 # ============================================================ [features] # 默认激活所有功能，方便开发测试 # 反思：默认全开违背了 features 按需编译的初衷！ default = ["parser", "filter", "output", "cdc"] # 各子功能对应可选编译开关 parser = ["dep:pipeline-parser"] filter = ["dep:pipeline-filter"] output = ["dep:pipeline-output-sink"] cdc = ["dep:pipeline-cdc"] [dependencies] pipeline-parser = { path = "../pipeline-parser", optional = true } pipeline-filter = { path = "../pipeline-filter", optional = true } pipeline-output-sink = { path = "../pipeline-output-sink", optional = true } pipeline-cdc = { path = "../pipeline-cdc", optional = true }

教训：default = ["parser", "filter", "output", "cdc"]看起来方便，但完全失去了 features 按需编译的意义。我们现在正在考虑把default改成空数组，让下游 crate 显式声明需要哪些功能。但修改会带来大量上下游适配工作——这就是设计决策"先易后难"的代价。

三、构建时间的演变数据

做了三个月，我拉了一份每次 CI 构建的耗时记录，发现一个规律：

如果重来一次，我会在第二周就开始做 sccache。我们到第八周才引入 sccache，如果早点做，至少能省掉一半的 CI 时间。

// ============================================================ // CI 脚本中引入 sccache 的配置（现在后悔没早点加） // ============================================================ // .github/workflows/ci.yml 关键配置： // // - name: Setup sccache // uses: mozilla-actions/sccache-action@v0.0.3 // // - name: Build // env: // RUSTC_WRAPPER: sccache // 让 rustc 通过 sccache 编译 // SCCACHE_GHA_ENABLED: "true" // run: cargo build --release

四、版本号同步的坑

workspace 里所有 crate 共享同一个版本号（通过 workspace 级别的[workspace.package]定义）。这在早期非常方便，但到第七周时出了一个严重的问题：

我们发了一个新版本的pipeline-core，改了一个公共 trait 的方法签名。但由于所有 crate 版本号相同，api-server依赖了pipeline-core = "0.3.0"，它拿到了新版本，但pipeline-cdc还是用的旧版本缓存。结果生产环境里序列化格式不匹配，线上炸了 20 分钟。

教训：workspace 内部 crate 之间应该用path = "..."依赖，永远不要对 workspace 内的 crate 用 version 依赖。但对外发布的 crate 版本号管理是一个需要更细策略的问题。

# ============================================================ # 正确的做法：workspace 内永远用 path 依赖 # ============================================================ [dependencies] # 对了：用 path，确保始终编译同一份源码 pipeline-core = { path = "../pipeline-core" } # 错了：用 version 可能导致版本不一致 # pipeline-core = { version = "0.3.0" }

这件事还催生了一个额外措施：我们在 CI 里加了cargo tree -d检查，一旦发现同一个 crate 被解析出了两个版本就报警。比如serde 1.0.190和serde 1.0.210同时出现在依赖树里，说明有 crate 没有及时更新，潜在的不兼容风险就藏在版本号差里。这个检查挡掉了至少三次可能导致线上序列化不匹配的问题。

还有一个推荐的习惯：每个 crate 加一个CHANGELOG.md，哪怕只记一行变更说明。等三个月后回看 workspace 历史时，这些笔记能省掉无数 git blame 的时间。

五、总结

三个月 workspace 项目的得与失：

做得对的：

1. 按功能边界拆分 crate（pipeline-parser、pipeline-filter 等）是正确的。
2. features 机制设计方向对，启发了编译隔离的思想。
3. path 依赖保证了内部一致性。

做得不好的：

1. shared-utils是过度设计——不如直接复制 15 行代码。
2. defaultfeatures 全开违背了按需编译初衷。
3. sccache 引入太晚，浪费了大量 CI 时间。
4. 没有做内部 crate 的 semver 检查工具（建议用cargo-semver-checks）。

如果现在让我重新设计一个 workspace，我会遵守一个极简原则：超过 5 个 crate 时要问自己三次"这个拆分真的有必要吗？"多数时候，答案是否定的。