Cargo 工作区依赖治理版本统一不是复制粘贴一、多包项目最怕依赖漂移Rust 项目从单包变成工作区后依赖管理会变复杂。多个 crate 各自声明 tokio、serde、anyhow 版本时间久了就可能出现版本漂移、feature 不一致和编译时间上升。Cargo 工作区依赖治理的目标是让公共依赖集中声明让每个 crate 只声明自己需要什么。版本统一不是复制粘贴而是减少重复决策。我之前维护过一个 4 个 crate 的工作区。core 用 tokio 1.30cli 用 tokio 1.28plugin 还停在 1.25。三个不同版本同时编译binary 里带了三份 tokio体积多了 8MB。更麻烦的是 feature 也不一致cli 开了fullcore 只开了rt-multi-thread。明明是同一套异步运行时却因为版本不一致调出来的行为都不一样。二、依赖可以放到 workspaceflowchart TD A[workspace Cargo.toml] -- B[crate cli] A -- C[crate core] A -- D[crate plugin] B -- E[统一依赖版本]工作区根目录可以声明 workspace dependencies。子 crate 使用 workspace 版本避免每个包单独写一遍。这样升级 serde 或 tokio 时只改一个地方。feature 也要治理。某个 crate 需要 tokio full另一个只需要 sync如果全部默认 full会增加编译和二进制体积。feature 应按实际需要开启。三、配置示例要清楚[workspace.dependencies] serde { version 1, features [derive] } tokio { version 1, features [rt-multi-thread, macros] } [dependencies] serde { workspace true } tokio { workspace true }子 crate 引用 workspace 依赖后版本由根配置统一管理。这样不会出现 core 用一个版本、cli 用另一个版本的情况。[features] default [] ai [dep:reqwest]可选能力用 feature 管理但不要默认打开所有能力。AI 工具里网络请求、WASM、向量库客户端都可以按需启用。生产环境实战经验用workspace.dependencies最容易被忽略的是版本号的写法。version 1表示接受 1.x 任意版本每次 lock 文件更新都可能拉到新版本。version 1.30精确控制到小版本。团队项目建议写精确版本避免某天 CI 突然挂掉结果是 tokio 1.31 改了某个行为。但精确版本要定期批量升级否则半年后还在用旧版本安全更新也落下了。四、依赖治理要有检查可以定期运行cargo tree查看重复依赖和 feature。编译慢、二进制大、依赖冲突很多都能从依赖树看到线索。还要注意公共 crate 边界。core crate 不应依赖 CLI 输出库协议 crate 不应依赖重型运行时。依赖方向清楚工作区才不会变成一团线。工作区还要统一 lint 和格式化。根目录配置 clippy、rustfmt 和测试命令避免每个 crate 风格不同。系统工具链项目通常会越拆越多早期统一规范很省心。发布版本也要规划。多个 crate 是一起发版还是独立发版取决于 API 边界。如果内部 crate 不对外暴露可以跟随主包版本公共协议 crate 则要更谨慎避免破坏下游。feature 组合要测试。默认 feature、最小 feature、全部 feature 都可能编译不同代码路径。CI 至少覆盖常用组合否则某个可选能力可能长期坏掉。依赖漂移导致的一次线上故障团队有个插件系统用serde_json序列化通信协议。生产环境插件用的是 workspace 版本 1.0.105开发环境某次cargo update后自动升到了 1.0.108。新版本对 JSON 某些边界情况的解析策略变了生产环境的旧版本解析失败。问题出在两个环境 lock 文件不同步。从那以后CI 每次构建都会对比 lock 文件 hash任何依赖于版本冲突的 bug 都能第一时间发现。最后依赖升级应小步进行。一次升级十几个核心依赖出问题很难定位。版本治理的核心是可追踪而不是永远停在旧版本。日常维护中一个很实用的命令是cargo tree --duplicates。它能列出哪些 crate 被编译了多个版本。发现重复版本后可以用cargo tree --invert crate反查是谁引用了旧版本。把这个命令放到 CI 里设定最多允许 0 个重复依赖版本漂移就无处可藏了。五、总结Cargo 工作区依赖治理要使用 workspace dependencies 统一版本按需开启 feature并定期检查依赖树。多包项目的稳定性来自边界和依赖方向。版本统一不是复制粘贴而是把重复决策收敛到一个地方。
Cargo 工作区依赖治理：版本统一不是复制粘贴
Cargo 工作区依赖治理版本统一不是复制粘贴一、多包项目最怕依赖漂移Rust 项目从单包变成工作区后依赖管理会变复杂。多个 crate 各自声明 tokio、serde、anyhow 版本时间久了就可能出现版本漂移、feature 不一致和编译时间上升。Cargo 工作区依赖治理的目标是让公共依赖集中声明让每个 crate 只声明自己需要什么。版本统一不是复制粘贴而是减少重复决策。我之前维护过一个 4 个 crate 的工作区。core 用 tokio 1.30cli 用 tokio 1.28plugin 还停在 1.25。三个不同版本同时编译binary 里带了三份 tokio体积多了 8MB。更麻烦的是 feature 也不一致cli 开了fullcore 只开了rt-multi-thread。明明是同一套异步运行时却因为版本不一致调出来的行为都不一样。二、依赖可以放到 workspaceflowchart TD A[workspace Cargo.toml] -- B[crate cli] A -- C[crate core] A -- D[crate plugin] B -- E[统一依赖版本]工作区根目录可以声明 workspace dependencies。子 crate 使用 workspace 版本避免每个包单独写一遍。这样升级 serde 或 tokio 时只改一个地方。feature 也要治理。某个 crate 需要 tokio full另一个只需要 sync如果全部默认 full会增加编译和二进制体积。feature 应按实际需要开启。三、配置示例要清楚[workspace.dependencies] serde { version 1, features [derive] } tokio { version 1, features [rt-multi-thread, macros] } [dependencies] serde { workspace true } tokio { workspace true }子 crate 引用 workspace 依赖后版本由根配置统一管理。这样不会出现 core 用一个版本、cli 用另一个版本的情况。[features] default [] ai [dep:reqwest]可选能力用 feature 管理但不要默认打开所有能力。AI 工具里网络请求、WASM、向量库客户端都可以按需启用。生产环境实战经验用workspace.dependencies最容易被忽略的是版本号的写法。version 1表示接受 1.x 任意版本每次 lock 文件更新都可能拉到新版本。version 1.30精确控制到小版本。团队项目建议写精确版本避免某天 CI 突然挂掉结果是 tokio 1.31 改了某个行为。但精确版本要定期批量升级否则半年后还在用旧版本安全更新也落下了。四、依赖治理要有检查可以定期运行cargo tree查看重复依赖和 feature。编译慢、二进制大、依赖冲突很多都能从依赖树看到线索。还要注意公共 crate 边界。core crate 不应依赖 CLI 输出库协议 crate 不应依赖重型运行时。依赖方向清楚工作区才不会变成一团线。工作区还要统一 lint 和格式化。根目录配置 clippy、rustfmt 和测试命令避免每个 crate 风格不同。系统工具链项目通常会越拆越多早期统一规范很省心。发布版本也要规划。多个 crate 是一起发版还是独立发版取决于 API 边界。如果内部 crate 不对外暴露可以跟随主包版本公共协议 crate 则要更谨慎避免破坏下游。feature 组合要测试。默认 feature、最小 feature、全部 feature 都可能编译不同代码路径。CI 至少覆盖常用组合否则某个可选能力可能长期坏掉。依赖漂移导致的一次线上故障团队有个插件系统用serde_json序列化通信协议。生产环境插件用的是 workspace 版本 1.0.105开发环境某次cargo update后自动升到了 1.0.108。新版本对 JSON 某些边界情况的解析策略变了生产环境的旧版本解析失败。问题出在两个环境 lock 文件不同步。从那以后CI 每次构建都会对比 lock 文件 hash任何依赖于版本冲突的 bug 都能第一时间发现。最后依赖升级应小步进行。一次升级十几个核心依赖出问题很难定位。版本治理的核心是可追踪而不是永远停在旧版本。日常维护中一个很实用的命令是cargo tree --duplicates。它能列出哪些 crate 被编译了多个版本。发现重复版本后可以用cargo tree --invert crate反查是谁引用了旧版本。把这个命令放到 CI 里设定最多允许 0 个重复依赖版本漂移就无处可藏了。五、总结Cargo 工作区依赖治理要使用 workspace dependencies 统一版本按需开启 feature并定期检查依赖树。多包项目的稳定性来自边界和依赖方向。版本统一不是复制粘贴而是把重复决策收敛到一个地方。
