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. default features 全开违背了按需编译初衷。
3. sccache 引入太晚，浪费了大量 CI 时间。
4. 没有做内部 crate 的 semver 检查工具（建议用 cargo-semver-checks）。

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