---
name: google-rust-style
description: 按 Google Rust 风格指南（https://google.github.io/styleguide/rustguide.html）编写、审查与重构 Rust 代码：涵盖 API 设计、代码组织、命名、文档与实现规范。凡是用 Rust 写代码、做 code review、讨论或检查 Rust 风格、rustfmt、clippy、Rust API 设计，或提到 Google Rust Style Guide / 谷歌 Rust 规范时都应使用——即使没有明说"风格"二字。
---

# Google Rust 风格指南

提炼自 https://google.github.io/styleguide/rustguide.html（2026-10 抓取版本，原文全文见 references/source-text.md）。Google 对 "style" 的定义不止格式，还包括 API 设计与实现设计规范。

## 定位与优先级

1. **先公共规范**：官方 Rust Style Guide（格式规则大部分由 rustfmt 自动执行）+ Rust API Guidelines。本指南在其上叠加 Google 特有规则，冲突时 Google 规则优先。
2. **库代码 vs 应用代码**：API 设计类规则对库代码（供其他项目复用、解决较通用问题）是强制要求；对应用代码（单一程序内部、解决特定问题）是强烈建议——应用代码优先简单直接，避免过早泛化和抽象。指南原文多处按此区分（如返回 `Vec` 还是迭代器、参数收切片还是迭代器）。
3. **[chrome] / [Fuchsia] 标记**：带此标记的规则只适用于 Chromium / Fuchsia 代码库，通用 Rust 项目不要套用。参考文件中已保留标记。
4. **指南目标**：可读性与可维护性优先于书写便利；规则应利于自动化与大规模变更（LSC）、与更广 Rust 生态一致、确有实际收益，并减少无谓的风格争论。适用范围：Android、Chromium 等代码库各自决定执行严格程度。

## 怎么用

- **写代码 / 设计 API 前**：按下方主题索引读对应参考文件，不要只凭速查表设计关键 API。
- **review / 检查既有代码**：按主题索引定位规则逐条对照；指出问题时给出规则名称与出处文件。
- **格式问题**：交给 rustfmt（推荐配置见 organization-and-formatting.md），不要手工调格式；clippy 覆盖了本指南多条规则（borrowed_box、ptr_arg、should_implement_trait、new_without_default、len_without_is_empty、wrong_self_convention、exhaustive_enums 等），修 clippy 警告通常就是在遵守本指南。
- **查原文**：浓缩规则未覆盖或存疑时，读 references/source-text.md（原文机器提取，英文）核对。

## 高频规则速查

完整规则、例外与代码示例见参考文件。最常出现的判定：

- 参数借用"剥到底"：`&T` 不用 `&Box<T>`，`&[T]` 不用 `&Vec<T>`，`&str` 不用 `&String`，`Option<&T>` 不用 `&Option<T>`。
- 默认唯一所有权：避免 `Rc`/`Arc`（除非替代结构复杂到不合理）；`.clone()` 用于真正需要深拷贝时，不当借用的替代品。
- 错误上报三分法：失败原因显而易见用 `Option`；调用方需要上下文才能恢复用 `Result`；bug 与违反不变量用 `panic!`。
- `expect` 优于 `unwrap`；已知合法的值用模式匹配（`if let Some(v) = …`）而不是 check-then-unwrap。
- 禁用 glob imports（例外有限）；一条 `use` 只从一个模块导入；trait 导入尽量放函数体内；顶层函数调用带模块名（`mem::transmute(y)`），类型名则导入后不加限定（用 `Regex` 不用 `regex::Regex`）。
- API 参数语义不明显时用 `enum` 不用 `bool`。
- 跨团队公开的 enum、含公开字段的 struct 加 `#[non_exhaustive]`（例外：永不变更的稳定本体、需要用户使用 FRU 语法等）。
- 命名：构造器 `new()` / `new_with_foo()`、返回 `Result` 用 `try_new()`、值到值转换 `from_foo()` 配 `From` 实现；getter/setter 用 `foo()` / `foo_mut()` / `take_foo()` / `set_foo()` / `with_foo()` / `replace_foo()`；扩展 trait 名以 `Ext` 结尾。
- unsafe 必须有 `SAFETY:` 注释和技术理由，并封装在安全抽象里；`panic::catch_unwind` 禁用；不用 unstable 特性。
- 文档注释：公开 API 必须有；`///` 文档化条目、`//!` 模块级、`//` 实现注释，鼓励混用；不解释语言基础、不简单复述函数名。
- 长迭代器链、在 `for` 头部构造链 → 先赋给具名变量再迭代，或改写为 `for` 循环；少用 `Iterator::for_each`。
- 拼接超过两段字符串、对字面量做替换：用 `format!` / `write!`。

## 主题索引

| 主题 | 参考文件 |
|---|---|
| crate 大小与拆分、文件/模块布局与命名、imports（glob、use 粒度、trait 导入作用域、限定规则）、rustfmt 配置与 `#[rustfmt::skip]` | references/organization-and-formatting.md |
| 函数参数与返回值（借用形态、迭代器 vs 集合、Into）、错误上报、newtype、trait 设计与选择、泛型 vs dyn、并发、宏的取舍、getter/setter、`#[non_exhaustive]`、`#[must_use]`、unsafe、const fn、运算符重载 | references/api-design.md |
| 方法前缀（as_/to_/into_）、生命周期与泛型参数命名、构造函数命名、缩写、文档注释规范 | references/naming-and-documentation.md |
| Rc/Arc、clone 与借用、类型推断、模式匹配、assert 上下文、迭代器链 vs for、catch_unwind、format!、测试框架 | references/implementation.md |
| 原文全文（机器提取，英文，用于核对） | references/source-text.md |

## 执行注意

- 规则的例外也是规则：应用任何规则前确认不在例外情形里，参考文件逐条保留了原文例外。
- 与项目已有约定冲突时（rustfmt.toml、现有代码风格、crate 结构），先说明差异再动手，不要静默修改项目配置。
- 本指南不替代 rustfmt / clippy：能自动化的交给工具，人工与模型只处理工具管不到的设计问题。