Google 内部 Rust 风格指南公开：从命名到 API 设计的完整规范

eric2013

原文地址：https://google.github.io/styleguide/rustguide.html

现在有AI了，这些规范可以直接喂给AI。

Google 公开了内部的 Rust 风格指南。这份文档不只管代码格式，API 设计和实现写法一起管，覆盖代码组织、导入、所有权与借用、函数输入输出、类型、trait、并发、宏、命名、文档、实现细节、测试框架十几个章节。

几条有代表性的条款：

1、一条 use 只从一个模块导入（对应 rustfmt 的 imports_granularity = Module），禁止 glob 导入。

2、参数收 &str / &[T] / &T，不收 &String / &Vec / &Box 这类加了一层包装的类型；返回类型优先 impl Iterator，而不是 Vec。

3、状态用 enum 表达，别用 bool。必须用 bool 时内联注释写清含义。

4、能用 #[derive] 就不手写；扩展 trait 加 Ext 后缀，如 ForeignTypeExt。

5、错误处理分档：原因明显的简单失败用 Option，需要上下文的可恢复错误用 Result，违反不变式才 panic。expect 优于 unwrap，且要写明原因。

6、unsafe 尽量不用。必须用时封装成安全抽象、隔离在独立 crate 里，逐处写 SAFETY: 注释，说明为什么无法安全实现；若理由是性能，附 benchmark。

7、公开枚举和含公开字段的公开结构体加 #[non_exhaustive]，跨团队 API 尤其如此。