超干货！大型 Rust 项目经验分享｜ Databend 与您共同进步

原文：[https://matklad.github.io/2021/08/22/large-rust-workspaces.html](https://matklad.github.io/2021/08/22/large-rust-workspaces.html)

译者：韩玄亮（一个热爱开源，喜欢 rust 的 go 开发者）

在本篇文章中，我将分享我组织大型Rust项目的经验。但这绝不是权威的，只是我通过尝试和错误中发现的一些小技巧。

Cargo，作为Rust的构建系统，遵循约定大于配置的原则。它不仅为小型项目提供了一套良好的默认配置集，尤其为公共 crates.io 库量身定做。虽然这些默认值并不完美，但它们已经足够用了。这对整个生态系统的一致性也是值得欢迎的。

然而当涉及到大型的、多crate的项目时，Cargo就不那么统一了，它被组织成一个Cargo工作空间。而工作空间是灵活的 —— Cargo对工作空间的布局并没有一个偏好统一。因此，人们会尝试不同的东西，取得不同程度的效果。

回到标题，我认为对于代码行数在一万到一百万之间的项目，扁平化结构是最为合理的。此处 [rust-analyzer](https://github.com/rust-analyzer/rust-analyzer) (多达200k行)是一个比较好的例子，它的项目组织如下：

在 repo 的根部，Cargo.toml 定义了一个虚拟清单：

其他的东西(包括 rust-analyzer "main" crate)都嵌套在 `crates/` 下的某一个层级中。每个目录的名称都等于 `crate` 的名称。

在撰写本文时，`crates/` 中有32个不同子文件夹。

扁平式比嵌套式更好

有趣的是，这个建议和按层级组织的习惯倾向(注：按照我们平时开发习惯来说)刚好对立:

在这种情况下，有几个原因可以说明树形结构是低级的：

1. crates的cargo分级命名空间是扁平的。在 `Cargo.toml` 中不可能写出 `hir::def` ，所以一般crate的名字中都有前缀。树状排列创造了另一种层次结构，这就增加了不一致的可能性。

2. 即使是比较大的列表也比小的树更容易让人一目了然。`ls ./crates` 给出了项目的层级概览，而且这看起来足够小。

在基于树状结构的布局做同样的事情比较困难的：

- 只从单层级上看并不能告诉你哪些文件夹包含嵌套的 crate

- 而在所有层级上看又会列出太多的文件夹(无关文件干扰视觉)

**正确方式**：***只看包含Cargo.toml的文件夹可以得到正确的结果，但并没有 `ls` 那样简单***。

嵌套结构确实比扁平结构更容易扩展。但常数很重要 —— 在你达到一百万行代码之前，项目中的crates数量可能会充满一个屏幕。

3. 层级布局的最后一个问题是：***没有完美的分层结构***。但是对于扁平结构，增加或拆分crates的代价微不足道。在树状结构下，你需要弄清楚把新的crate放在哪里，而且，如果已经没有一个完美的匹配，你将不得不选择以下几种情况:

- 在顶部附近添加一个愚蠢的空的文件夹

- 添加到一个巨无霸的utils文件夹

- 将代码放在一个已存在但是不是很理想的目录中(*所以结构会随着维护而慢慢恶化*)

对于长期维护的多人项目来说，这是一个重要的问题 —— 树状结构往往会随着时间的推移而恶化，而扁平结构则不怎么需要维护。

小技巧

让工作空间的根部成为虚拟清单。

这可以驱使我们把main crate放在根目录下，但这样做会使根目录被 `src/` 污染，需要在每个 Cargo 命令中传递 `--workspace`，并向其他一致的结构添加异常。

 **反对从文件夹名称中去除普通前缀。**

如果每个板块的名字都和它所在的文件夹一模一样，这让导航和重命名就会变得更容易。反向依赖的Cargo.toml同时提到了文件夹和crate的名称，当它们完全相同的时候就很有用。

**对于大型项目来说，很多版本库的臃肿往往来自于自动化。**

Makefiles和各种prepare.sh脚本。为了避免臃肿和临时工作流程的泛滥，可以将所有的Rust自动化写在一个专门的crate里。这里安利一个有用的库：[cargo-xtask](https://github.com/matklad/cargo-xtask)。

 **对于你不打算发布的内部crate，可以使用 `version = "0.0.0"`。**

如果你确实想发布具有符合语义版本API的crate的子集，那么要非常慎重对待它们。将所有这样的crate提取到一个单独的顶层文件夹，即 `libs/`，这样做对未来可能是有意义的。这使得检查 `libs/` 中的东西是否使用了 `crates/` 中的东西更加容易。

**由一个文件组成一个 crate。**

对于这些文件，我们很容易陷入：把 `src` 目录展开，把 lib.rs 和 Cargo.toml 放在同一个目录下。但是我建议不要这样做 —— 即使crate现在是单文件，以后也可能会被扩展。