Cargo 工作区项目复盘多 crate 管理的得与失的经验总结一、workspace 的起点8 个 crate 是怎么长出来的项目一开始只有 3 个 cratepipeline-core、shared-types、api-server。但随着功能叠加三个月后变成了 8 个新增 Crate触发原因是否合理pipeline-parser日志格式解析逻辑膨胀到 3000 行合理pipeline-filter过滤规则复杂化需要独立测试合理pipeline-output-sink输出目标多变文件/数据库/Kafka合理pipeline-cdc新增增量同步功能逻辑独立合理shared-utils提取公共工具函数过度设计最后一个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-actionv0.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 项目的得与失做得对的按功能边界拆分 cratepipeline-parser、pipeline-filter 等是正确的。features 机制设计方向对启发了编译隔离的思想。path 依赖保证了内部一致性。做得不好的shared-utils是过度设计——不如直接复制 15 行代码。defaultfeatures 全开违背了按需编译初衷。sccache 引入太晚浪费了大量 CI 时间。没有做内部 crate 的 semver 检查工具建议用cargo-semver-checks。如果现在让我重新设计一个 workspace我会遵守一个极简原则超过 5 个 crate 时要问自己三次这个拆分真的有必要吗多数时候答案是否定的。