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 设计与实现设计规范。

定位与优先级

先公共规范：官方 Rust Style Guide（格式规则大部分由 rustfmt 自动执行）+ Rust API Guidelines。本指南在其上叠加 Google 特有规则，冲突时 Google 规则优先。
库代码 vs 应用代码：API 设计类规则对库代码（供其他项目复用、解决较通用问题）是强制要求；对应用代码（单一程序内部、解决特定问题）是强烈建议——应用代码优先简单直接，避免过早泛化和抽象。指南原文多处按此区分（如返回 Vec 还是迭代器、参数收切片还是迭代器）。
[chrome] / [Fuchsia] 标记：带此标记的规则只适用于 Chromium / Fuchsia 代码库，通用 Rust 项目不要套用。参考文件中已保留标记。
指南目标：可读性与可维护性优先于书写便利；规则应利于自动化与大规模变更（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：能自动化的交给工具，人工与模型只处理工具管不到的设计问题。