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

最新推荐文章于 2025-10-05 17:34:46 发布

翻译最新推荐文章于 2025-10-05 17:34:46 发布 · 583 阅读

0 ·

CC 4.0 BY-SA版权

原文链接：https://matklad.github.io/2021/08/22/large-rust-workspaces.html

文章标签：

#Databend #rust

本文探讨了如何组织大型Rust项目，推荐扁平化的结构以提高一致性、可读性和扩展性。作者介绍了rust-analyzer项目的案例，并分享了关于工作空间管理、命名策略和自动化工具的小技巧。

# 大型 Rust 项目工作空间

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

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

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

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

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

```shell
rust-analyzer/
Cargo.toml
Cargo.lock
crates/
rust-analyzer/
hir/
hir_def/
hir_ty/
...
```

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

*Cargo.toml:*

```toml
[workspace]
members = ["crates/*"]
```

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

*crates/hir_def/Cargo.toml:*

```toml
[package]
name = "hir_def"
version = "0.0.0"
edition = "2018"
```

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

## 扁平式比嵌套式更好

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

```shell
rust-analyzer/
Cargo.toml
src/
hir/
Cargo.toml
src/
def/
ty/
```

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

1. crates 的 cargo 分级命名空间是扁平的。在 `Cargo.toml` 中不可能写出 `hir::def` ，所以一般 crate 的名字中都有前缀。树状排列创造了另一种层次结构，这就增加了不一致的可能性。
2. 即使是比较大的列表也比小的树更容易让人一目了然。`ls ./crates` 给出了项目的层级概览，而且这看起来足够小。

```shell
> ls ./crates

base_db
cfg
flycheck
hir
hir_def
hir_expand
hir_ty
ide
ide_assists
ide_completion
ide_db
ide_diagnostics
ide_ssr
limit
mbe
parser
paths
proc_macro_api
proc_macro_srv
proc_macro_test
profile
project_model
rust-analyzer
sourcegen
stdx
syntax
test_utils
text_edit
toolchain
tt
vfs
```