1. 概述

状态

• 《Rust 编码规范》目前为 V 1.0 beta 试行版，改进内容参考 Changelog

详细

• 1.1 为什么需要 Rust 编码规范
• 1.2 编码规范基本约定

介绍

Rust 语言社区内其实分散着很多编码规范，下面罗列一部分公开信息：

• 官方｜Rust API 编写指南
• 官方 | Rust Style Guide
• Rust's Unsafe Code Guidelines Reference
• 法国国家信息安全局 | Rust 安全（Security）规范
• Apache Teaclave 安全计算平台 | Rust 开发规范
• PingCAP | 编码风格指南（包括 Rust 和 Go 等）
• Google Fuchsia 操作系统 Rust 开发指南
• RustAnalyzer 编码风格指南
• 使用 Rust 设计优雅的 API
• Rust FFI 指南

上面这些除了 Rust 官方和法国国家信息安全局的编码规范之外，其他开源项目的编码规范主要是为了规范贡献者们遵循一个统一的编码风格。

所以，一个通用的，覆盖编码风格和具体编码实践的全面的编码规范，更有助于社区各个开源项目和各大公司参考去制定自己的编码规范。

本规范致力于成为统一的 Rust 编码规范，各大公司可以依赖本规范，结合自己的业务领域和团队习惯，形成自己的编码规范，并可以在日常实践中反哺本规范，让本规范更加完善。

1.1 为什么需要 Rust 编码规范

前言

在刚学 Rust 的时候，我赞叹于 Rust 提供的工具之先进性。比如 rustfmt，可以自动格式化代码，clippy 可以帮助你规范代码中写的不地道的地方。它们确实是非常优秀的工具。当时我也认为 Rust 根本不需要像其他语言那样制定编码规范。

但随着对 Rust 越来越深入了解的过程中，我也逐渐发现这些工具的很多不足之处，覆盖的并不全面。比如 rustfmt 配置和使用不当会导致代码错误，而且无法识别 Rust 代码中各种命名的语义；clippy存在一些误报或lint不合理，以及无法覆盖到 Unsafe Rust 等问题。开发者，尤其是新手们，如果长期像使用一个黑盒一样去依赖rustfmt和clippy，但并不去了解其lint背后的原因，只是知其然而无法知其所以然，那在代码质量有一定要求的前提下是无法提升开发效率的。

所以，rutfmt和clippy并不是万能的。我们还需要一个全面且通用的编码规范，并且也能覆盖到像 rustfmt 和 clippy 这样的工具，让广大 Rust 团队通过规范化的原则和规则去了解编写地道 Rust 代码的基本框架，就可以快速落地 Rust ，增强团队间的协作与信任。

Rustfmt 和 Clippy 的局限性

Rustfmt 局限性

Rust 有自动化格式化工具 rustfmt ，可以帮助开发者摆脱手工调整代码格式的工作，提升生产力。但它并不能代替编码规范对 Rust 代码的编码风格进行规范。

rustfmt主要存在以下缺陷：

1. Rust 语言是一门非常注重语义的语言。Rust 中的变量、类型和函数等命名是非常讲究语义的，尤其是所有权语义。rustfmt 工具无法判断代码中命名的语义。这方面利用 Clippy 可以满足部分需求，但是对于开发者来说比较片面。
2. Rustfmt 如果使用不当或配置不当，会导致问题。因为rustfmt是自动格式化工具，它会自动修改代码，但是它修改的时候并不会编译代码。如果开发者配置自动保存以后自动执行rustfmt，就会导致代码被修改错误，或者，有一些rustfmt 配置选项配置错误，也可能导致代码修改错误。
3. rustfmt 工具中的配置项都比较零散，大部分开发者不会去了解其每一个配置项的含义。
4. rustfmt 没有覆盖到代码注释和文档注释的编码规范。

综上所述，需要通过提供一个通用的编码规范，让开发者明确地从命名、格式和注释三方面整体上了解 Rust 遵循什么样的编码风格。其中会覆盖 rustfmt 的内容，但并不是机械地将 rustfmt 的规则都一一提取出来，而是对 rustfmt 的规则进行了统一的归类和梳理，方便开发者去理解 rustfmt 中制定的规则，方便团队去制定适合自己的代码风格。

Clippy 的局限性

Clippy是 Rust 的 linter，是 Rust 生态系统中的主要组件之一。它对已开发的代码执行额外的静态检查，报告发现的问题并解释如何修复它们（有时它甚至可以自动修复它们）。使用它能对 Rust 初学者甚至专业人士都带来好处。

但使用 Clippy 并不是意味着它能代替编码规范，它也存在很多缺陷：

1. Clippy 缺乏很多 Unsafe Rust 相关的 lint 检测。Unsafe Rust 是 Rust 非常重要的一部分，需要一个完整的编码规范来覆盖，帮助开发者编写安全的 Unsafe 代码。
2. Clippy 中的 lint 截止目前有 500多条，而且还有不断增长的趋势，开发者不可能一条条去了解每个 lint，所以需要一个编码规范帮助开发者对lint进行一个梳理归类。
3. Clippy 中的lint 的建议和分级 （allow/warning/deny）有些争议。其中有些 lint 默认是 allow，但不代表在一些场景下，它就是合理的写法；同样，有些 lint 是 warning，但不代表在一些场景下是不合理的。为此，dtolnay 还特意创造了这个仓库：https://github.com/dtolnay/noisy-clippy ，用于分析社区中crate有多少 Clippy lint 的建议并不符合实际场景，从而达到改进 Clippy 的目的。

综上所述，Clippy 虽然是一个十分有用的工具，但它无法替代编码规范。

编码规范作用

Rust 编码规范的作用主要是如下方面：

1. 遵循 Rust 语言特性，提高代码的可读性、可维护性、健壮性和可移植性。
2. 提高 Unsafe Rust 代码编写的规范性和安全性。
3. 编程规范条款力争系统化、易应用、易检查，帮助开发者提升开发效率。
4. 给开发者一个明确的且全局的视野，在其开发代码的过程中就能遵循好的代码规范，而非等写完代码以后再通过rustfmt和clippy这类的工具，一条一条去修改warning。
5. 规范不等于教程，但是开发人员水平参差不齐，对于一些因为知识盲点而可能导致程序错误的地方，规范也将覆盖到。

1.2 编码规范基本约定

编码规范的内容组织说明

编程规范绝不是为了增加开发者的负担而编写的，目的是为了帮助开发者写出高质量的 Rust 代码。

为了达成这个目的，规范条款分为原则和规则两个类别：原则 与 规则。

• 原则，就是编程开发时指导的一个大方向，或是指一类情况。也有少部分原则是 Rust 编译器可检测的情况，但是因为编译器诊断信息比较迷惑，所以增加了原则，帮助开发者去避免这类情况。

• 规则，相对原则来说，更加具体，包含正例和反例来进一步说明。有些规则也会增加例外的情况。规则基本都是可以通过 lint 进行检测的。

规则内容 与 rustfmt 和 clippy 的关系

规范主要分为两大部分内容：代码风格 和 代码实践。

代码风格

在代码风格中包含代码命名、格式和注释：

• 命名部分，主要是通过 clippy lint 来检查，有些命名规则 clippy lint未提供检测，则需要自定义lint来支持。
• 格式部分，主要用 rustfmt 来自动修改，编码规范中的规则对 rustfmt 的大部分配置项进行了分类描述，为了方便开发者进行参考，制定自己的配置项。编码规范中也提供了配置模版。
• 注释部分，其中包括普通注释和文档注释，规则条目通过 rustfmt 和 clippy 合作来进行规范。

代码实践

代码实践的内容是按照 Rust 语言特性进行分类，每个语言特性都尽量针对日常编码最佳实践进行总结，提取为一条条的原则和规则，方便开发者进行参考。其中大部分规则都是建议，涉及要求的规则基本都是和安全相关。

这部分内容的规则条目基本都依赖 Clippy lint 去检测，但并非是把 Clippy 500 多条 lint 都一一对应为规则。Clippy lint 中涉及很多技巧类的lint，就没有放到规范中。

规则主要是侧重于通用场景下，代码可读性、维护性、安全性、性能这四方面的考量，它仅仅覆盖一小部分（不到 1/5）clippy lint。另外还有一些规则是clippy lint没有的，需要自定义lint。

代码实践内容的重点在于 Unsafe Rust 的编码规范，其中编码原则多于规则，并且 Clippy lint 也很少能检测这部分内容。其中要求类的规则更多一些。

希望通过这部分内容，让开发者在编写 Rust 代码过程中，避开一些常见的坑。

编码规范内容约定

通过标题前的编号来标识：

• 标识为P为原则（Principle）。编号方式为P.Element.Number。
• 标识为G为规则（Guideline）。编号方式为G.Element.Number。
• 当有子目录时。编号方式为 P.Element.SubElement.Number 或 G.Element.SubElement.Number。

Number 从01开始递增。其中 Element 为领域知识中关键元素（本规范中对应的二级目录）的三位英文字母缩略语。（术语参考： SEI CERT C Coding Standard）

引用代码开源许可证说明

本规范中引用外部代码，均满足 MIT/Apache/Mozilla public licenses 开源许可证！

特别鸣谢

本指南参考《华为 C 语言编程指南 V 1.0》，感谢华为 开源能力中心 提供编程指南规范协助！

2. 代码风格

代码风格包含标识符的命名风格、排版与格式风格、注释风格等。一致的编码习惯与风格，可以提高代码可读性和可维护性。

2.1 命名

好的命名风格能让我们快速地了解某个名字代表的含义（类型、变量、函数、常量、宏等），甚至能凸显其在整个代码上下文中的语义。命名管理对提升代码的可读性和维护性相当重要。

P.NAM.01 同一个crate中标识符的命名规则应该使用统一的词序

【描述】

具体选择什么样的词序并不重要，但务必要保证同一个 crate 内词序的一致性。 若提供与标准库中相似功能的东西时，也要与标准库名称的词性顺序一致.

拿错误类型来举个例子：

当crate中类型名称都按照 动词-宾语-error 这样的顺序来命名错误类型时，如果要增加新的错误类型，则也需要按同样的词序来增加。

以下是来自标准库的处理错误的一些类型示例：

• JoinPathsError
• ParseBoolError
• ParseCharError
• ParseFloatError
• ParseIntError
• RecvTimeoutError
• StripPrefixError

如果你想新增和标准库相似的错误类型，比如“解析地址错误”类型，为了保持词性一致，应该使用ParseAddrError 名称，而不是AddrParseError。

说明：现在标准库文档中 net模块解析地址错误类型是 AddrParseError，其实和标准库中大部分错误类型遵循的 "动-宾-Error" 词序没有保持一致，所以它是一个特例。

【反例】

#![allow(unused)]
fn main() {
// 不符合：与标准库错误类型词序 "动-宾-Error"  不一致，应该为 ParseAddrError
struct AddrParseError {}
}

【正例】

#![allow(unused)]
fn main() {
// 符合： 与标准库错误类型一致
struct ParseAddrError{}
}

P.NAM.02 为 cargo feature 命名时不应含有无意义的占位词

【描述】

给 Cargo feature 命名时，不应带有无实际含义的的词语，比如使用abc命名来替代 use-abc 或 with-abc。

这条原则经常出现在对 Rust 标准库进行 可选依赖(optional-dependency) 配置的 crate 上。

并且 Cargo 要求 features 应该是相互叠加的，所以像 no-abc 这种负向的 feature 命名实际上并不正确。

【反例】

# In Cargo.toml


[features]
// 不符合
default = ["use-std"]
std = []
// 不符合
no-abc=[]

// In lib.rs

#![cfg_attr(not(feature = "use-std"), no_std)]

【正例】

最简洁且正确的做法是：

# In Cargo.toml

[features]
// 符合
default = ["std"]
std = []

// In lib.rs

#![cfg_attr(not(feature = "std"), no_std)]

P.NAM.03 标识符命名应该符合阅读习惯

【描述】

标识符的命名要清晰、明了，有明确含义，容易理解。符合英文阅读习惯的命名将明显提高代码可读性。

一些好的实践包括但不限于：

• 使用正确的英文单词并符合英文语法，不要使用拼音
• 仅使用常见或领域内通用的单词缩写
• 布尔型变量或函数避免使用否定形式，双重否定不利于理解
• 不要使用 Unicode 标识符

【反例】

#![allow(unused)]
fn main() {
// 不符合： 使用拼音
let ming: &str = "John";
let xing: &str = "Smith";
// 不符合： 含义不明确
const ERROR_NO_1: u32 = 336;
const ERROR_NO_2: u32 = 594;
// 不符合：函数名字表示的函数作用不明了
fn not_number(s:&str) -> bool {/* ... */}
}

【正例】

#![allow(unused)]
fn main() {
// 符合
let first_name: &str = "John";
let last_name: &str = "Smith";
const ERR_DIR_NOT_SUPPORTED: u32 = 336;
const ERR_DVER_CANCEL_TIMEOUT: u32 = 594;
// 符合
fn is_number(s:&str) -> bool {/* ... */} 
}

P.NAM.04 作用域越大命名越精确，反之应简短

【描述】

1. 对于全局函数、全局变量、宏、类型名、枚举命名，应当精确描述并全局唯一。
2. 对于函数局部变量，或者结构体、枚举中的成员变量，在其命名能够准确表达含义的前提下，应该尽量简短，避免冗余信息重复描述。

【反例】

#![allow(unused)]
fn main() {
// 不符合：描述不精确
static GET_COUNT: i32 = 42;  

// 不符合：信息冗余
enum WebEvent {
    PageLoadEvent,
    PageUnloadEvent,
    KeyPressEvent(char),
    PasteEvent(String),
    ClickEvent { x: i64, y: i64 },
}

// 不符合：信息冗余
type MaskSize = u16; 
pub struct HeaderMap {
    mask: MaskSize,
}
}

【正例】

#![allow(unused)]
fn main() {
// 符合
static MAX_THREAD_COUNT: i32 = 42;  

// 符合： 上下文信息已经知道它是 Event
enum WebEvent {
    PageLoad,
    PageUnload,
    KeyPress(char),
    Paste(String),
    Click { x: i64, y: i64 },
}

// 符合：在使用它的地方自然就知道是描述谁的大小
type Size = u16; 
pub struct HeaderMap {
    mask: Size,
}
}

P.NAM.05 用于访问或获取数据的 getter 类方法通常不要使用 get_ 前缀

【描述】

因为 Rust 所有权语义的存在，此例子中两个方法的参数分别是共享引用 &self 和 独占引用 &mut self，分别代表了 getter 的语义。

也存在一些例外情况可以用 get_ 前缀。

【反例】

#![allow(unused)]
fn main() {
pub struct First;
pub struct Second;

pub struct S {
    first: First,
    second: Second,
}

impl S {
    // 不符合：访问成员函数名字不用get_前缀。
    pub fn get_first(&self) -> &First {
        &self.first
    }

    // 不符合：
    // 同样不建议 `get_mut_first`, or `mut_first`.
    pub fn get_first_mut(&mut self) -> &mut First {
        &mut self.first
    }

    // set_前缀是可以的
    pub fn set_first(&mut self, f: First) -> &mut First {
        self.first = f;
    }
}
}

【正例】

#![allow(unused)]
fn main() {
pub struct First;
pub struct Second;

pub struct S {
    first: First,
    second: Second,
}

impl S {
    // 符合
    pub fn first(&self) -> &First {
        &self.first
    }

    // 符合
    pub fn first_mut(&mut self) -> &mut First {
        &mut self.first
    }

    // set_前缀是可以的
    pub fn set_first(&mut self, f: First)  {
        self.first = f;
    }
}
}

【例外】

但也存在例外情况：只有当需要显式的语义来通过getter获取某种数据，才会使用get命名。例如，Cell::get可以访问一个Cell的内容。

对于进行运行时验证的getter，例如边界检查，可以考虑添加一个 Unsafe 的_unchecked 配套方法。一般来说，会有以下签名。

#![allow(unused)]
fn main() {
// 进行一些运行时验证，例如边界检查
fn get(&self, index: K) -> Option<&V>;
fn get_mut(&mut self, index: K) -> Option<&mut V>;
// 没有运行时验证，用于在某些情况下提升性能。比如，在当前运行环境中不可能发生越界的情况。
unsafe fn get_unchecked(&self, index: K) -> &V;
unsafe fn get_unchecked_mut(&mut self, index: K) -> &mut V;
}

getter 和类型转换 (G.NAM.02) 之间的区别很小，大部分时候不那么清晰可辨。比如 TempDir::path 可以被理解为临时目录的文件系统路径的 getter ，而 TempDir::into_path 负责把删除临时目录时转换的数据传给调用者。

因为 path 方法是一个 getter ，如果用 get_path 或者 as_path 会造成信息冗余。

来自标准库的例子：

• std::io::Cursor::get_mut
• std::ptr::Unique::get_mut
• std::sync::PoisonError::get_mut
• std::sync::atomic::AtomicBool::get_mut
• std::collections::hash_map::OccupiedEntry::get_mut
• <[T]>::get_unchecked

P.NAM.06 遵循 iter/ iter_mut/ into_iter 规范来生成迭代器

【描述】

此规则包含两条基本子规则：

1. 对于容纳 U 类型的容器 (container) ，其迭代器方法应该遵循iter/ iter_mut/ into_iter 这三种命名方式。
2. 返回的迭代器类型名称也应该和其方法名保持一致，如一个叫做into_iter()的方法应该返回一个叫做IntoIter的类型。

说明：

• 规则一适用于在概念上属于同质集合的数据结构的方法，而非函数。例如，第三方库 url 中的 percent_encode 返回一个 URL 编码的字符串片段的迭代器，使用iter/iter_mut/into_iter约定的话，函数名就会失去明确的语义。
• 规则二同样主要适用于方法，但通常对函数也有意义。例如，第三方库 url 中的 percent_encode 返回一个PercentEncode 类型的迭代器。

【反例】

// 不符合：没必要加 `to_` 前缀
fn to_iter(&self) -> Iter             // Iter 实现 Iterator<Item = &U>
fn to_iter_mut(&mut self) -> IterMut  // IterMut 实现 Iterator<Item = &mut U>
fn to_into_iter(self) -> IntoIter     // IntoIter 实现 Iterator<Item = U>

【正例】

// 符合
fn iter(&self) -> Iter             // Iter 实现 Iterator<Item = &U>
fn iter_mut(&mut self) -> IterMut  // IterMut 实现 Iterator<Item = &mut U>
fn into_iter(self) -> IntoIter     // IntoIter 实现 Iterator<Item = U>

【例外】

标准库中存在一个例外： str 类型是有效 UTF-8 字节的切片（slice），概念上与同质集合略有差别，所以 str 没有提供 iter/iter_mut/into_iter 命名的迭代器方法，而是提供 str::bytes 方法来输出字节迭代器、 str::chars 方法来输出字符迭代器。

【参考】

参考 [RFC 199]: https://github.com/rust-lang/rfcs/blob/master/text/0199-ownership-variants.md

还有有一些来自标准库的例子可参考：

• Vec::iter
• Vec::iter_mut
• Vec::into_iter
• BTreeMap::iter
• BTreeMap::iter_mut
• BTreeMap::keys 返回 [Keys]btree_map::Keys
• BTreeMap::values 返回 [Values]btree_map::Values

P.NAM.07 避免使用语言内置保留字、关键字、内置类型和trait等特殊名称

【描述】

命名必须要避免使用语言内置的保留字、关键字、内置类型和trait等特殊名称。 具体可以参考The Rust Reference-Keywords。

【反例】

// 不符合：Rust 内置了 Sized trait 
type Sized = u16; 

fn main() {
    // 不符合：try 为保留关键字
    let try = 1;
}

【正例】

// 符合
type Size = u16; 

fn main() {
    // 符合
    let tried = 1;
}

【例外】

在一些特定场合，比如对接遗留数据库中的字段和Rust关键字冲突：

#![allow(unused)]

fn main() {
struct SomeTable{
    // 使用 `r#`+type 来解决这种问题
    r#type: String
}

}

或者当序列化为 json 或 proto 时，存在成员为关键字，则可以通过相关库提供的功能来使用：

#![allow(unused)]
fn main() {
pub struct UserRepr {
    // ...
    #[serde(rename="self")]
    pub self_: Option<String>,
    // ...
}
}

P.NAM.08 避免在变量的命名中添加类型标识

【描述】

因为 Rust 语言类型系统崇尚显式的哲学，所以不需要在变量命名中也添加关于类型的标识。

【反例】

#![allow(unused)]
fn main() {
let account_bytes: Vec<u8> = read_some_input();   // 不符合：account 的类型很清楚，没必要在命名中加 `_bytes`
let account_str = String::from_utf8(account_bytes)?; // 不符合：account 的类型很清楚，没必要在命名中加 `_str`
let account: Account = account_str.parse()?;   // 不符合：account 的类型很清楚，没必要在命名中加 `_str`
}

【正例】

#![allow(unused)]
fn main() {
let account: Vec<u8> = read_some_input();   // 符合
let account = String::from_utf8(account)?;  // 符合
let account: Account = account.parse()?;   // 符合
}

P.NAM.09 定义全局静态变量时需加前缀G_以便和常量有所区分

【描述】

为了提升代码可读性和可维护性，有必要将常量的命名和全局静态变量加以区分。所以在定义全局静态变量时，需要以前缀G_命名。

【反例】

#![allow(unused)]
fn main() {
// 不符合： 无法通过命名直接区分常量和静态变量
static EVENT: [i32;5]=[1,2,3,4,5];
const MAGIC_NUM: i32 = 65 ;
}

【正例】

#![allow(unused)]
fn main() {
// 符合
static G_EVENT: [i32;5]=[1,2,3,4,5];
const MAGIC_NUM: i32 = 65 ;
}

G.NAM.01 使用统一的命名风格

【级别】 要求

【描述】

Rust 倾向于在“类型”级的结构中使用驼峰（ UpperCamelCase） 命名风格，在 “变量、值（实例）、函数名”等结构中使用蛇形（ snake_case）命名风格。

下面是汇总信息：

说明 :

1. 在 UpperCamelCase情况下，由首字母缩写组成的缩略语和 复合词的缩写，算作单个词。比如，应该使用 Uuid 而非 UUID，使用 Usize 而不是 USize，或者是 Stdin 而不是 StdIn。
2. 在snake_case中，首字母缩写和缩略词是小写的 is_xid_start。
3. 在 snake_case 或者 SCREAMING_SNAKE_CASE 情况下，每个词不应该由单个字母组成——除非这个字母是最后一个词。比如，使用 btree_map 而不使用 b_tree_map，使用 PI_2 而不使用 PI2 。

关于包命名：

• 由于历史问题，包名有两种形式 snake_case 或 kebab-case ，但实际在代码中需要引入包名的时候，Rust 只能识别 snake_case，也会自动将 kebab-case 识别为 kebab_case。所以建议使用snake_case。
• Crate 的名称通常不应该使用 -rs 或者 -rust 作为后缀或者前缀。但是有些情况下，比如是其他语言移植的同名 Rust 实现，则可以使用 -rs 后缀来表明这是 Rust 实现的版本。

【参考】

Rust 命名规范在 RFC 0430 中有也描述。

【Lint 检测】

G.NAM.02 类型转换函数命名需要遵循所有权语义

【级别】 建议

【描述】

进行特定类型转换的方法名应该包含以下前缀：

以 as_ 和 into_ 作为前缀的类型转换通常是 降低抽象层次 ，要么是查看背后的数据 ( as ) ，要么是分解 (deconstructe) 背后的数据 ( into ) 。 相对来说，以 to_ 作为前缀的类型转换处于同一个抽象层次，但是底层会做更多工作，比如多了内存拷贝等操作。

当一个类型用更高级别的语义 (higher-level semantics) 封装 (wraps) 一个内部类型时，应该使用 into_inner() 方法名来取出被封装类型的值。

这适用于以下封装器：

读取缓存 (BufReader) 、编码或解码 (GzDecoder) 、取出原子 (AtomicBool 、 或者任何相似的语义封装 (BufWriter)。

【正例】

标准库 API 命名有如下示例：

• as_
  • str::as_bytes() 用于查看 UTF-8 字节的 str 切片，这是无内存代价的（不会产生内存分配）。 传入值是 &str 类型，输出值是 &[u8] 类型。
• to_
  • Path::to_str 对操作系统路径进行 UTF-8 字节检查，开销昂贵。 虽然输入和输出都是借用，但是这个方法对运行时产生不容忽视的代价， 所以不应使用 as_str 名称。
  • str::to_lowercase() 生成正确的 Unicode 小写字符， 涉及遍历字符串的字符，可能需要分配内存。 输入值是 &str 类型，输出值是 String 类型。
  • f64::to_radians() 把浮点数的角度制转换成弧度制。 输入和输出都是 f64 。没必要传入 &f64 ，因为复制 f64 花销很小。 但是使用 into_radians 名称就会具有误导性，因为输入数据没有被消耗。
• into_
  • String::into_bytes() 从 String 提取出背后的 Vec<u8> 数据，这是无代价的。 它转移了 String 的所有权，然后返回具有所有权的 Vec<u8> 。
  • BufReader::into_inner() 转移了 buffered reader 的所有权，取出其背后的 reader ，这是无代价的。 存于缓冲区的数据被丢弃了。
  • BufWriter::into_inner() 转移了 buffered writer 的所有权，取出其背后的 writer ，这可能以很大的代价刷新所有缓存数据。

如果类型转换方法返回的类型具有 mut 修饰，那么这个方法的名称应如同返回类型组成部分的顺序那样，带有 mut 。 比如 Vec::as_mut_slice 返回 &mut [T] 类型，这个方法的功能正如其名称所述，所以这个名称优于 as_slice_mut 。

其他参考示例：

• Result::as_ref
• RefCell::as_ptr
• slice::to_vec
• Option::into_iter

【Lint 检测】

2.2 格式

制定统一的编码风格，是为了提升代码的可读性，让日常代码维护和团队之间审查代码更加方便。

Rust 有自动化格式化工具 rustfmt ，可以帮助开发者摆脱手工调整代码格式的工作，提升生产力。但是，rustfmt 遵循什么样的风格规范，作为开发者需要了解，在编写代码的时候可以主动按这样的风格编写。

说明：

对于 rustfmt 中未稳定的配置项（Stable为No），则表示该配置项不能在稳定版（Stable）Rust 中更改配置，但其默认值会在cargo fmt时生效。在 Nightly Rust 下则都可以自定义配置。

如需了解在稳定版 Rust 中使用未稳定配置项的方法、配置示例及其他全局配置项说明，请参阅：Rustfmt 配置相关说明 。

【注意事项】

因为 rustfmt 工具会自动修改代码，为了确保 rustfmt 不会因为意外而改错代码，所以在使用 rustfmt 时应该注意下面两项描述：

1. 务必保证在全部把代码修改完毕且编译通过之后再执行 rustfmt 命令。 因为 rustfmt 执行过程中不会对代码进行编译，所以就不会有静态检查保护。
2. 如果是使用 IDE 或 编辑器的时候开启了自动保护功能，就不要开启自动执行 rustfmt 功能。

P.FMT.01 使用 rustfmt 进行自动格式化代码

【描述】

应该总是在项目中添加 rustfmt.toml 或 .rustfmt.toml文件。即使它是空文件，这是向潜在的合作者表明你希望代码是自动格式化的。

【例外】

在特殊的情况下，可以通过条件编译属性 #[cfg_attr(rustfmt, rustfmt_skip)] 或 #[rustfmt::skip] 来关闭自动格式化。

比如下面示例：

vec! 中的元素排布是固定格式，这样有助于开发的便利。

fn main() {
    let got = vec![
            0x00, 0x05, 0x01, 0x00,
            0xff,
            0x00,
            0x00,
    
            0x01, 0x0c, 0x02, 0x00,
            0xde, 0xad, 0xbe, 0xef, 0xde, 0xad, 0xbe, 0xef,
            b'd', b'e', b'a', b'd', b'b', b'e', b'e', b'f', 0x00,
            0x00,
    
            127, 0x06, 0x03, 0x00,
            0x01, 0x02,
            b'a', b'b', b'c', b'd', 0x00,
            b'1', b'2', b'3', b'4', 0x00,
            0x00,
    ];
}

如果使用 自动格式化，会变成：

fn main() {
    let got = vec![
        0x00, 0x05, 0x01, 0x00, 0xff, 0x00, 0x00, 0x01, 0x0c, 0x02, 0x00, 0xde, 0xad, 0xbe, 0xef,
        0xde, 0xad, 0xbe, 0xef, b'd', b'e', b'a', b'd', b'b', b'e', b'e', b'f', 0x00, 0x00, 127,
        0x06, 0x03, 0x00, 0x01, 0x02, b'a', b'b', b'c', b'd', 0x00, b'1', b'2', b'3', b'4', 0x00,
        0x00,
    ];
}

但是加上 #[rustfmt::skip] 就不会被自动格式化影响：

fn main() {
    #[rustfmt::skip] 
    let got = vec![
            0x00, 0x05, 0x01, 0x00,
            0xff,
            0x00,
            0x00,
    
            0x01, 0x0c, 0x02, 0x00,
            0xde, 0xad, 0xbe, 0xef, 0xde, 0xad, 0xbe, 0xef,
            b'd', b'e', b'a', b'd', b'b', b'e', b'e', b'f', 0x00,
            0x00,
    
            127, 0x06, 0x03, 0x00,
            0x01, 0x02,
            b'a', b'b', b'c', b'd', 0x00,
            b'1', b'2', b'3', b'4', 0x00,
            0x00,
    ];
}

P.FMT.02 缩进使用空格而非制表符

【描述】

缩进要使用四个空格，不要使用制表符（\t）代替。可以通过 IDE 或编辑器把缩进设置为四个空格。

【rustfmt 配置】

P.FMT.03 行间距最大宽度空一行

【描述】

代码行之间，最小间隔 0 行，最大间隔1行。

【反例】

#![allow(unused)]
fn main() {
fn foo() {
    println!("a");
}
// 不符合：空两行 
// 不符合：空两行
fn bar() {
    println!("b");
// 不符合：空两行 
// 不符合：空两行
    println!("c");
}
}

【正例】

#![allow(unused)]
fn main() {
fn foo() {
    println!("a");
}
// 符合：空一行 
fn bar() {
    println!("b");
    println!("c");
}
}

或者

#![allow(unused)]
fn main() {
fn foo() {
    println!("a");
}
fn bar() {
    println!("b");
	// 符合：空一行 
    println!("c");
}

}

【rustfmt 配置】

P.FMT.04 语言项（Item) 定义时左花括号（brace）位置应该与语言项保持同一行

【描述】

为了保持代码结构的良好可读性，Rust 中定义各种语言项，包括控制结构（if / match 等）、函数、结构体、枚举等，要求左花括号与其定义保持同一行。

但是如果携带 where语句，则要求换行，并且where 子句和 where 关键字不在同一行。

rustfmt 提供三个配置项对不同的语言项进行格式化：

• brace_style 配置项对应于大部分语言项，包括函数、结构体等，但是控制结构（if / match等）除外，默认值为SameLineWhere，代表左花括号与语言项定义保持同一行。
• where_single_line 配置项对应于 where 语句，默认值是 false，表示 where语句的花括号是换行。
• control_brace_style 配置项对应于控制结构（if / match等），默认值为AlwaysSameLine，表示左花括号与语言项定义保持同一行。

所以，只需要使用 rustfmt 默认配置即可。

【反例】

如果设置 brace_style = "AlwaysNextLine"，则不符合。

#![allow(unused)]
fn main() {
// 不符合： 左花括号与函数语言项定义未保持同一行
fn lorem()
{
    // body
}
}

如果设置 brace_style = "PreferSameLine"，则符合：

#![allow(unused)]
fn main() {
// 不符合： 左花括号与 where 语句 应该换行
fn lorem<T>(ipsum: T)
where
    T: Add + Sub + Mul + Div, { // 注意这里和 `SameLineWhere`的区别
    // body
}
}

结构体与枚举：

如果设置 brace_style = "AlwaysNextLine"，则不符合：

#![allow(unused)]
fn main() {
// 不符合： 左花括号与结构体语言项定义未保持同一行
struct Lorem
{
    ipsum: bool,
}
}

如果设置 brace_style = "PreferSameLine"，则符合：

#![allow(unused)]
fn main() {
// 不符合： 左花括号与 where 语句应该换行
struct Dolor<T>
where
    T: Eq, {
    sit: T,
}
}

流程控制倾向于默认使用 AlwaysSameLine，即，总在同一行。因为流程控制没有where子句。

如果设置 brace_style = "AlwaysNextLine"，则不符合：

fn main() {
    // 不符合： 左花括号与控制结构未保持同一行
    if lorem
    {
        println!("ipsum!");
    }
    else
    {
        println!("dolor!");
    }
}

【正例】

函数：

#![allow(unused)]
fn main() {
// 符合： 左花括号和 函数语言项定义在同一行
fn lorem() { 
    // body
}

fn lorem<T>(ipsum: T)
where // 符合：`where` 子句和 `where` 关键字不在同一行
    T: Add + Sub + Mul + Div,
{ // 符合：当有 `where` 子句的时候，花括号换行
    // body
}
}

结构体与枚举

#![allow(unused)]
fn main() {
// 符合
struct Lorem {
    ipsum: bool,
}

// 符合
struct Dolor<T>
where 
    T: Eq,
{
    sit: T,
}
}

流程控制倾向于默认使用 AlwaysSameLine，即，总在同一行。因为流程控制没有where子句。

// 符合
// "AlwaysSameLine" (default)
fn main() {
    if lorem {
        println!("ipsum!");
    } else {
        println!("dolor!");
    }
}

【rustfmt 配置】

P.FMT.05 存在多个标识符时应该保持块状（Block）缩进

【描述】

当在表达式或语言项定义中出现多个标识符，则应该让其保持块状风格缩进。

【反例】

fn main() {
    // 不符合：缩进不符合标准，只是为了对齐
    let lorem = vec!["ipsum",
                     "dolor",
                     "sit",
                     "amet",
                     "consectetur",
                     "adipiscing",
                     "elit"];
}

流程控制

fn main() {
    // 不符合：缩进不符合标准，只是为了对齐
    if lorem_ipsum
       && dolor_sit // 注意：这里缩进只是三个空格，仅仅是和前一行 `lorem_ipsum`对齐
       && amet_consectetur
       && lorem_sit
       && dolor_consectetur
       && amet_ipsum
       && lorem_consectetur
    {
        // ...
    }
}

函数参数

#![allow(unused)]
fn main() {
fn lorem() {}

fn lorem(ipsum: usize) {}
// 不符合
fn lorem(ipsum: usize,
         dolor: usize,
         sit: usize,
         amet: usize,
         consectetur: usize,
         adipiscing: usize,
         elit: usize) {
    // body
}
}

函数调用

fn main() {
    // 不符合
    lorem("lorem",
          "ipsum",
          "dolor",
          "sit",
          "amet",
          "consectetur",
          "adipiscing",
          "elit");
}

泛型

#![allow(unused)]
fn main() {
// 不符合
fn lorem<Ipsum: Eq = usize,
         Dolor: Eq = usize,
         Sit: Eq = usize,
         Amet: Eq = usize,
         Adipiscing: Eq = usize,
         Consectetur: Eq = usize,
         Elit: Eq = usize>(
    ipsum: Ipsum,
    dolor: Dolor,
    sit: Sit,
    amet: Amet,
    adipiscing: Adipiscing,
    consectetur: Consectetur,
    elit: Elit)
    -> T {
    // body
}
}

结构体

fn main() {
    let lorem = Lorem { ipsum: dolor,
                        sit: amet };
}

【正例】

数组：

fn main() {
    // 符合： 缩进四个空格
    let lorem = vec![
        "ipsum",
        "dolor",
        "sit",
        "amet",
        "consectetur",
        "adipiscing",
        "elit",
    ];
}

流程控制

fn main() {
    // 符合： 缩进四个空格
    if lorem_ipsum
        && dolor_sit
        && amet_consectetur
        && lorem_sit
        && dolor_consectetur
        && amet_ipsum
        && lorem_consectetur
    {
        // ...
    }
}

函数参数

#![allow(unused)]
fn main() {
fn lorem() {}

fn lorem(ipsum: usize) {}

// 符合： 缩进四个空格
fn lorem(
    ipsum: usize,
    dolor: usize,
    sit: usize,
    amet: usize,
    consectetur: usize,
    adipiscing: usize,
    elit: usize,
) {
    // body
}

}

函数调用

fn main() {
    // 符合： 缩进四个空格
    lorem(
        "lorem",
        "ipsum",
        "dolor",
        "sit",
        "amet",
        "consectetur",
        "adipiscing",
        "elit",
    );
}

泛型

#![allow(unused)]
fn main() {
// 符合： 缩进四个空格
fn lorem<
    Ipsum: Eq = usize,
    Dolor: Eq = usize,
    Sit: Eq = usize,
    Amet: Eq = usize,
    Adipiscing: Eq = usize,
    Consectetur: Eq = usize,
    Elit: Eq = usize,
>(
    ipsum: Ipsum,
    dolor: Dolor,
    sit: Sit,
    amet: Amet,
    adipiscing: Adipiscing,
    consectetur: Consectetur,
    elit: Elit,
) -> T {
    // body
}
}

结构体

fn main() {
    let lorem = Lorem {
        ipsum: dolor,
        sit: amet,
    };
}

【rustfmt 配置】

P.FMT.06 当有多行表达式操作时，操作符应该置于行首

【描述】

当有多行表达式操作时，操作符应该置于行首，这样有利于代码的可读性和可维护性。

【反例】

操作符置于行尾

fn main() {
    // 不符合
    let or = foofoofoofoofoofoofoofoofoofoofoofoofoofoofoofoo ||
        barbarbarbarbarbarbarbarbarbarbarbarbarbarbarbar;
    // 不符合
    let sum = 123456789012345678901234567890 +
        123456789012345678901234567890 +
        123456789012345678901234567890;
    // 不符合
    let range = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa..
        bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb;
}

【正例】

操作符置于行首

fn main() {
    // 符合
    let or = foofoofoofoofoofoofoofoofoofoofoofoofoofoofoofoo
        || barbarbarbarbarbarbarbarbarbarbarbarbarbarbarbar;

    // 符合
    let sum = 123456789012345678901234567890
        + 123456789012345678901234567890
        + 123456789012345678901234567890;
    // 符合
    let range = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
        ..bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb;
}

【rustfmt 配置】

P.FMT.07 枚举变体和结构体字段都应左对齐

【描述】

对于自定义了判别式的枚举体，和有字段的结构体而言，默认只需要左对齐就可以。

这个宽度可以设置为任意值，但默认是0。

说明：此宽度并不是指插入多少空格，而是指需要对齐的字符长度。

【反例】

当 enum_discrim_align_threshold = 20 时。

#![allow(unused)]
fn main() {
// 不符合： 设置了变体长度最大是20
enum Foo {
    A   = 0,
    Bb  = 1,
    RandomLongVariantGoesHere = 10, // 注意，该变体长度已经超过了20，所以它不会被对齐
    Ccc = 2,
}

enum Bar {
    VeryLongVariantNameHereA = 0, // 注意，该变体长度已经超过了20，所以它不会被对齐
    VeryLongVariantNameHereBb = 1, // 注意，该变体长度已经超过了20，所以它不会被对齐
    VeryLongVariantNameHereCcc = 2,// 注意，该变体长度已经超过了20，所以它不会被对齐
}
}

当 enum_discrim_align_threshold = 50 时。

#![allow(unused)]
fn main() {
// 不符合： 因为通过更改配置值填充了空格
enum Foo {
    A                         = 0,
    Bb                        = 1,
    RandomLongVariantGoesHere = 10, // 注意，该变体长度未超过50，所以它会被对齐
    Ccc                       = 2,
}

enum Bar {
    VeryLongVariantNameHereA   = 0, // 注意，该变体长度未超过50，所以它会被对齐
    VeryLongVariantNameHereBb  = 1, // 注意，该变体长度未超过50，所以它会被对齐
    VeryLongVariantNameHereCcc = 2, // 注意，该变体长度未超过50，所以它会被对齐
}
}

【正例】

#![allow(unused)]
fn main() {
// 符合: 无论变体长度多长，都左对齐
enum Bar {
    A = 0,
    Bb = 1,
    RandomLongVariantGoesHere = 10,
    Ccc = 71,
}
// 符合
enum Bar {
    VeryLongVariantNameHereA = 0,
    VeryLongVariantNameHereBb = 1,
    VeryLongVariantNameHereCcc = 2,
}
}

【rustfmt 配置】

P.FMT.08 函数参数超过五个或导入模块个数超过四个需换行

【描述】

1. 五个以内函数参数可以置于一行，超过五个则使用「块」状缩进。
2. 导入模块每行超过四个，则换行。

【反例】

当 rustfmt 配置型 fn_args_layout 和 imports_layout 未使用默认值：

#![allow(unused)]
fn main() {
trait Lorem {
    fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet);

    fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet) {
        // body
    }

    // 不符合： 超过五个参数未使用块状缩进
    fn lorem(
        ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet, consectetur: Consectetur,
        adipiscing: Adipiscing, elit: Elit,
    );

    fn lorem(
        ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet, consectetur: Consectetur,
        adipiscing: Adipiscing, elit: Elit,
    ) {
        // body
    }
}

use foo::{xxxxxxxxxxxxxxxxxx, yyyyyyyyyyyyyyyyyy, zzzzzzzzzzzzzzzzzz};

// 不符合： 模块换行即可，无需使用块状缩进
use foo::{
    aaaaaaaaaaaaaaaaaa,
    bbbbbbbbbbbbbbbbbb,
    cccccccccccccccccc,
    dddddddddddddddddd,
    eeeeeeeeeeeeeeeeee,
    ffffffffffffffffff,
};
}

【正例】

当 rustfmt 配置项 fn_args_layout 和 imports_layout 使用默认值时：

#![allow(unused)]

fn main() {
trait Lorem {
    fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet, consectetur: Consectetur);

    fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet) {
        // body
    }

    // 符合
    fn lorem(
        ipsum: Ipsum,
        dolor: Dolor,
        sit: Sit,
        amet: Amet,
        consectetur: Consectetur,
        adipiscing: Adipiscing,
        elit: Elit,
    );

    // 符合
    fn lorem(
        ipsum: Ipsum,
        dolor: Dolor,
        sit: Sit,
        amet: Amet,
        consectetur: Consectetur,
        adipiscing: Adipiscing,
        elit: Elit,
    ) {
        // body
    }
}

use foo::{xxxxxxxxxxxxxxxxxx, yyyyyyyyyyyyyyyyyy, zzzzzzzzzzzzzzzzzz};

// 符合
use foo::{
    aaaaaaaaaaaaaaaaaa, bbbbbbbbbbbbbbbbbb, cccccccccccccccccc, dddddddddddddddddd,
    eeeeeeeeeeeeeeeeee,
};
}

【rustfmt 配置】

P.FMT.09 不同的场景，使用不同的空格风格

【描述】

1. 在冒号之后添加空格，在冒号之前不要加空格。
2. 在范围（range）操作符（..和..=）前后不要使用空格。
3. 在+或=操作符前后要加空格。

【反例】

#![allow(unused)]
fn main() {
// 不符合： 冒号之后未加空格
// 当 `space_after_colon=false`
fn lorem<T:Eq>(t:T) {
    let lorem:Dolor = Lorem {
        ipsum:dolor,
        sit:amet,
    };
}

// 不符合： 冒号之前加空格
// 当 `space_before_colon=true`
fn lorem<T : Eq>(t : T) {
    let lorem : Dolor = Lorem {
        ipsum : dolor,
        sit : amet,
    };
}

// 不符合： `..`前后加空格
// 当 `spaces_around_ranges=true`
let lorem = 0 .. 10;
let ipsum = 0 ..= 10;

// 不符合： `+`和`=`前后加空格
// 当 `type_punctuation_density="Compressed"`
fn lorem<Ipsum: Dolor+Sit=Amet>() {
    // body
    let answer = 1 + 2;
}
}

【正例】

#![allow(unused)]
fn main() {
// 符合
// 当 `space_after_colon=true`
fn lorem<T: Eq>(t: T) {
    let lorem: Dolor = Lorem {
        ipsum: dolor,
        sit: amet,
    };
}

// 符合
// 当 `space_before_colon=false`
fn lorem<T: Eq>(t: T) {
    let lorem: Dolor = Lorem {
        ipsum: dolor,
        sit: amet,
    };
}

// 符合
// 当 `spaces_around_ranges=false`
let lorem = 0..10;
let ipsum = 0..=10;

// 符合
// 当 `type_punctuation_density="Wide"`
fn lorem<Ipsum: Dolor + Sit = Amet>() {
    // body
    let answer = 1 + 2;
}
}

【rustfmt 配置】

P.FMT.10 match 分支应该具有良好的可读性

【描述】

1. 当match分支右侧代码体太长无法和=>置于同一行需要使用块(block)来包裹。
2. 在match分支左侧匹配表达式前不要增加管道符(|)

【反例】

// 不符合： 与 `=>` 不同行应该用块来包裹
// 当 `match_arm_blocks=false`
fn main() {
    match lorem {
        ipsum => 
            foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x),
        dolor => println!("{}", sit),
        sit => foo(
            "foooooooooooooooooooooooo",
            "baaaaaaaaaaaaaaaaaaaaaaaarr",
            "baaaaaaaaaaaaaaaaaaaazzzzzzzzzzzzz",
            "qqqqqqqqquuuuuuuuuuuuuuuuuuuuuuuuuuxxx",
        ),
    }
}

// 当 `match_arm_leading_pipes="Alaways"`
fn foo() {
    match foo {
        // 不符合： 分支左侧匹配表达式前不要加管道符
        | "foo" | "bar" => {}
        | "baz"
        | "something relatively long"
        | "something really really really realllllllllllllly long" => println!("x"),
        | "qux" => println!("y"),
        | _ => {}
    }
}

【正例】

// 当 `match_arm_blocks=true`
fn main() {
    match lorem {
        // 符合
        ipsum => { 
            foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x)
        }
        dolor => println!("{}", sit),
        // 符合
        sit => foo(
            "foooooooooooooooooooooooo",
            "baaaaaaaaaaaaaaaaaaaaaaaarr",
            "baaaaaaaaaaaaaaaaaaaazzzzzzzzzzzzz",
            "qqqqqqqqquuuuuuuuuuuuuuuuuuuuuuuuuuxxx",
        ),
    }
}

// 当 `match_arm_leading_pipes="Never"`
fn foo() {

    match foo {
        // 符合
        "foo" | "bar" => {}
        "baz"
        | "something relatively long"
        | "something really really really realllllllllllllly long" => println!("x"),
        "qux" => println!("y"),
        _ => {}
    }
}

【rustfmt 配置】

P.FMT.11 导入模块分组应该具有良好的可读性

【描述】

1. 导入同一模块的类型，应该置于同一个块内（imports_granularity="Crate"）。
2. 模块导入应该按以下规则进行分组（group_imports="StdExternalCrate"）：
   • 导入来自 std、core 和 alloc的模块需要置于前面。
   • 导入来自 第三方库的模块 应该置于中间。
   • 导入来自本地 self、super和crate前缀的模块，置于后面。
3. 分组内使用字典序进行排序（reorder_imports=true）。

说明： 默认 rustfmt 不会对导入的模块自动分组，而是保留开发者的导入顺序。所以，这里需要修改 rustfmt 默认配置，才能让rustfmt应用此规则，但因为这几个配置项暂时未稳定，所以需要在 Nightly 下使用。

【反例】

例1:

#![allow(unused)]
fn main() {
// 不符合： 同一模块类型应该置于同一个块内
// 当 `imports_granularity="Preserve"`
use foo::b;
use foo::b::{f, g};
use foo::{a, c, d::e};
use qux::{h, i};
}

例2:

#![allow(unused)]
fn main() {
// 不符合：当按默认值设置时，模块导入比较乱，影响可读性
use super::update::convert_publish_payload;
use chrono::Utc;

use alloc::alloc::Layout;
use juniper::{FieldError, FieldResult};
use uuid::Uuid;

use std::sync::Arc;

use broker::database::PooledConnection;

use super::schema::{Context, Payload};
use crate::models::Event;
use core::f32;
}

【正例】

例1:

#![allow(unused)]
fn main() {
// 符合
// 当 `imports_granularity="Crate"`
use foo::{
    a, b,
    b::{f, g},
    c,
    d::e,
};
use qux::{h, i};
}

例2:

#![allow(unused)]
fn main() {
// 符合
// 当 `group_imports="StdExternalCrate` 且 `reorder_imports=true`
use alloc::alloc::Layout;
use core::f32;
use std::sync::Arc;

use broker::database::PooledConnection;
use chrono::Utc;
use juniper::{FieldError, FieldResult};
use uuid::Uuid;

use super::schema::{Context, Payload};
use super::update::convert_publish_payload;
use crate::models::Event;
}

【rustfmt 配置】

P.FMT.12 声明宏分支应该具有良好的可读性

【描述】

1. 在声明宏中，模式匹配分支（=> 左侧）应该使用紧凑格式（format_macro_matchers=true）。
2. 而分支代码体（=> 右侧） 使用宽松格式。

说明：因为这里需要修改format_macro_matchers的默认值，且该配置项并未 Stable ，所以需要在 Nightly 下修改配置项的值以便使用。

【反例】

#![allow(unused)]
fn main() {
// 不符合： 匹配分支使用了宽松格式
// 当 `format_macro_matchers=false`且 `format_macro_bodies=true`
macro_rules! foo {
    ($a: ident : $b: ty) => {
        $a(42): $b;
    };
    ($a: ident $b: ident $c: ident) => {
        $a = $b + $c;
    };
}

// 不符合： 分支代码体使用了紧凑格式
// 当 `format_macro_matchers=false`且 `format_macro_bodies=false`
macro_rules! foo {
    ($a: ident : $b: ty) => {
        $a(42):$b;
    };
    ($a: ident $b: ident $c: ident) => {
        $a=$b+$c;
    };
}
}

【正例】

#![allow(unused)]
fn main() {
// 当 `format_macro_matchers=true` 且 `format_macro_bodies=true`
macro_rules! foo {
    // 符合：匹配分支紧凑格式， `$a:ident` 和 `$b:ty` 各自配对
    ($a:ident : $b:ty) => {
        $a(42): $b; // 在代码体内，则宽松一点
    };
    // 符合
    ($a:ident $b:ident $c:ident) => {
        $a = $b + $c;
    };
}
}

【rustfmt 配置】

P.FMT.13 具名结构体字段初始化时不要省略字段名

【描述】

因为本规则依赖于rustfmt，而rustfmt会根据相应配置项对代码进行自动更改，为了确保不会因为rustfmt配置项的更改而导致代码错误，请在遵循rustfmt使用注意事项的基础上遵循本规则：

1. 省略字段名的时候需要注意变量名和字段名保持一致。
2. 变量名和字段名不一致的情况下，不要省略字段名。

注意：如果将 rustfmt 默认配置 use_field_init_shorthand改为true时，有可能会发生代码被修改错误的情况。

【反例】

struct Foo {
    a: u32, // 注意这里是 a
    y: u32,
    z: u32,
}

fn main() {
    let x = 1;
    let y = 2;
    let z = 3;
    // 不符合： 如果允许省略字段名，并且rustfmt 配置 `use_field_init_shorthand`改为`true`时，
    //        下面代码中字段`a`就会被rustfmt删除，变为 `Foo{x, y, z}`，从而造成错误
    // rustfmt 无法检查这个错误，但是编译时能检查出来，所以要遵循rustfmt使用注意事项就不会出问题
    let a = Foo { a: x, y, z };
}

【正例】

struct Foo {
    a: u32,
    y: u32,
    z: u32,
}

fn main() {
    let x = 1;
    let y = 2;
    let z = 3;
    // 符合
    let a = Foo { a: x, y: y, z: z };
}

【rustfmt 配置】

P.FMT.14 extern 外部函数需要显式指定 C-ABI

【描述】

当使用 extern 指定外部函数时，建议显式指定 C-ABI。

虽然 extern 不指定的话默认就是 C-ABI，但是 Rust 语言显式指定是一种约定俗成。

【反例】

#![allow(unused)]
fn main() {
// 不符合：不要省略 C-ABI 指定
extern {
    pub static lorem: c_int;
}
}

【正例】

#![allow(unused)]
fn main() {
// 符合
extern "C" {
    pub static lorem: c_int;
}

extern "Rust" {
    type MyType;
    fn f(&self) -> usize;
}
}

【rustfmt 配置】

P.FMT.15 解构元组的时候允许使用..来指代剩余元素

【描述】

rustfmt 可以由 condense_wildcard_suffixes 配置项来格式化此规则，其默认选项是 false，表示不允许 解构元组的时候使用..来指代剩余元素，所以需要修改默认配置项的值为 true 才符合规范。

【反例】

默认情况下，rustfmt 不会自动更改代码，会保留原来的写法。

fn main() {
    // 不符合： 应该使用`..`
    let (lorem, ipsum, _, _) = (1, 2, 3, 4);
    let (lorem, _,ipsum, _, _) = (1, 2, 3, 4, 5);
}

【正例】

设置 condense_wildcard_suffixes = true 时，会强行更改代码为下面形式。

fn main() {
    // 符合
    let (lorem, ipsum, ..) = (1, 2, 3, 4);
    let (lorem, _,ipsum, ..) = (1, 2, 3, 4, 5);
}

【rustfmt 配置】

P.FMT.16 不要将派生宏中多个不相关的特质合并为同一行

【描述】

不要将派生宏（Derive）中多个特质（trait）合并为同一行，这样可以增加代码可读性，明确语义。

rustfmt 配置项 merge_derives 用于匹配此格式，其默认值是让派生宏中多个特质在同一行，所以需要修改其默认值。

说明： rustfmt 并不会识别哪些特质相关，所以需要开发者手工指定好。

【反例】

当使用默认设置 merge_derives = true 时，不符合。

#![allow(unused)]
fn main() {
// 不符合：不相关的特质放到一行
#[derive(Eq, PartialEq, Debug, Copy, Clone)]
pub enum Foo {}
}

【正例】

修改默认设置 merge_derives = false，符合。

#![allow(unused)]
fn main() {
// 符合
#[derive(Eq, PartialEq)]
#[derive(Debug)]
#[derive(Copy, Clone)]
pub enum Foo {}
}

【rustfmt 配置】

2.3 注释与文档

在 Rust 中，注释分为两类：普通注释和文档注释。普通注释使用 // 或 /* ... */，文档注释使用 ///、//! 或 /** ... **/。

在原则和规则中提到「注释」时，包括普通注释和文档注释。当提到「文档」时，特指文档注释。

参考

1. RFC 505: API 注释约定
2. RFC 1574: API 文档约定
3. Making Great Docs with Rustdoc
4. Rust Doc book

P.CMT.01 代码能做到自注释，文档要干练简洁

【描述】

一、代码能够做到自注释，避免冗余的普通代码注释。

注释固然很重要, 但最好的代码应当本身就是文档。有意义的类型名、函数名和变量名, 要远胜过要用注释解释的含糊不清的名字。当有意义的类型名、函数名和变量名还不能表达完整的语义时，再使用注释。

不要描述显而易见的现象, 永远不要用自然语言翻译代码作为注释。

二、文档注释要干练简洁：

1. 文档注释中内容用语应该尽量简短精干，不宜篇幅过长。请确保你的代码注释良好并且易于他人理解，好的注释能够传达上下文关系和代码目的。
2. 注释内容始终围绕两个关键点来构建：
   • What : 用于阐述代码为了什么而实现。
   • how : 用于阐述代码如何去使用。
3. 注释和文档注释使用的自然语言要保持一致。
4. Rust 项目文档应该始终基于 rustdoc 工具来构建，rustdoc 支持 Markdown 格式，为了使得文档更加美观易读，文档注释应该使用 Markdown 格式。

【正例】

模块级文档，来自于 Rust 标准库std::vec：

#![allow(unused)]
fn main() {
// 符合

//! # The Rust core allocation and collections library
//!
//! This library provides smart pointers and collections for managing
//! heap-allocated values.
//!
//! This library, like libcore, normally doesn’t need to be used directly
//! since its contents are re-exported in the [`std` crate](../std/index.html).
//! Crates that use the `#![no_std]` attribute however will typically
//! not depend on `std`, so they’d use this crate instead.
//!
//! ## Boxed values
//!
//! The [`Box`] type is a smart pointer type. There can only be one owner of a
//! [`Box`], and the owner can decide to mutate the contents, which live on the
//! heap.
}

普通文档注释示例，来自标准库Vec::new方法：

#![allow(unused)]
fn main() {
// 符合

/// Constructs a new, empty `Vec<T>`.
///
/// The vector will not allocate until elements are pushed onto it.
///
/// # Examples
///
/// ```
/// # #![allow(unused_mut)]
/// let mut vec: Vec<i32> = Vec::new();
/// ```
#[inline]
#[rustc_const_stable(feature = "const_vec_new", since = "1.39.0")]
#[stable(feature = "rust1", since = "1.0.0")]
pub const fn new() -> Self {
    Vec { buf: RawVec::NEW, len: 0 }
}
}

P.CMT.02 注释应该有宽度限制

【描述】

每行注释的宽度不能过长，需要设置一定的宽度，不超过120，有助于提升可读性。

rustfmt中通过comment_width配合 wrap_comments 配置项，可将超过宽度限制的注释自动分割为多行。

注意：rustfmt的 use_small_heuristics配置项并不包括comment_width。

【反例】

#![allow(unused)]
fn main() {
// 不符合
// Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
}

【正例】

当 comment_width=80 且 wrap_comments=true时。

注意：这里 wrap_comments并未使用默认值，需要配置为 true。

#![allow(unused)]
fn main() {
// 符合
// Lorem ipsum dolor sit amet, consectetur adipiscing elit,
// sed do eiusmod tempor incididunt ut labore et dolore
// magna aliqua. Ut enim ad minim veniam, quis nostrud
// exercitation ullamco laboris nisi ut aliquip ex ea
// commodo consequat.
}

【rustfmt 配置】

P.CMT.03 使用行注释而避免使用块注释

【描述】

尽量使用行注释（// 或 ///），而非块注释。这是Rust社区的约定俗成。

对于文档注释，仅在编写模块级文档时使用 //!，在其他情况使用 ///更好。

说明： #![doc] 和 #[doc] 对于简化文档注释有特殊作用，没有必要通过 rustfmt 将其强制转化为 //! 或 /// 。

【反例】

#![allow(unused)]
fn main() {
// 不符合

/*
 * Wait for the main task to return, and set the process error code
 * appropriately.
 */
mod tests {
    //! This module contains tests

    // ...
}
}

【正例】

当 normalize_comments = true 时：

#![allow(unused)]
fn main() {
// 符合

// Wait for the main task to return, and set the process error code
// appropriately.

// 符合
// 在使用 `mod` 关键字定义模块时，在 `mod`之上使用 `///` 更好。

/// This module contains tests
mod tests {
    // ...
}

// 符合
#[doc = "Example item documentation"]
pub enum Foo {}
}

【rustfmt 配置】

P.CMT.04 文件头注释包含版权说明

【描述】

文件头（即，模块级）注释应先包含版权说明。如果文件头注释需要增加其他内容，可以在版权说明下面补充。

可以包括：

1. 文件功能说明。
2. 作者。
3. 创建日期 和 最后修改日期。
4. 注意事项。
5. 开源许可证(比如, Apache 2.0, BSD, LGPL, GPL)。
6. 其他。

版权说明格式如下：

• 中文版：版权所有（c）XXX 技术有限公司 2015-2022。
• 英文版： Copyright (c) XXX Technologies Co.Ltd. 2015-2022. All rights reserved. Licensed under Apache-2.0.

其内容可以进行调整，参加下面详细说明：

• 2015-2022 根据实际需要可以修改。2015是文件首次创建年份，2022是文件最后修改年份。可以只写一个创建年份，后续如果经常修改则无需修改版权声明。
• 如果是内部使用，则无需增加 All rights reserved。
• Licensed under Apache-2.0.，如果是开源则可以增加许可证声明。

编写版权注释时注意事项：

• 版权注释应该从文件头顶部开始写。
• 文件头注释首先包含“版权说明”，然后紧跟其他内容。
• 可选内容应按需添加，避免空有格式没有内容的情况。
• 保持统一格式，具体格式由项目或更大的范围统一制定。
• 保持版面工整，换行注意对齐。

【正例】

#![allow(unused)]
fn main() {
// 符合
// 版权所有（c）XXX 技术有限公司 2015-2022。

// Or

// 符合
// Copyright (c) XXX Technologies Co.Ltd. 2015-2022. 
// All rights reserved. Licensed under Apache-2.0.
}

P.CMT.05 在注释中使用 FIXME 和 TODO 来帮助任务协作

【描述】

通过在注释中开启 FIXME 和 TODO 可以方便协作。正式发布版本可以不做此类标注。

注意：此条目不适于使用 rustfmt相关配置项 report_fixme 和 report_todo，在 rustfmt v2.0 中已经移除这两项配置。

【正例】

#![allow(unused)]
fn main() {
// 符合
// TODO(calebcartwright): consider enabling box_patterns feature gate
fn annotation_type_for_level(level: Level) -> AnnotationType {
    match level {
        Level::Bug | Level::Fatal | Level::Error => AnnotationType::Error,
        Level::Warning => AnnotationType::Warning,
        Level::Note => AnnotationType::Note,
        Level::Help => AnnotationType::Help,
        // FIXME(#59346): Not sure how to map these two levels
        Level::Cancelled | Level::FailureNote => AnnotationType::Error,
        Level::Allow => panic!("Should not call with Allow"),
    }
}
}

G.CMT.01 在公开的返回Result类型的函数文档中增加 Error 注释

【级别】 建议

【描述】

在公开（pub）的返回Result类型的函数文档中，建议增加 # Error 注释来解释什么场景下该函数会返回什么样的错误类型，方便用户处理错误。

说明： 该规则可以通过 cargo clippy 来检测，但默认不会警告。

【反例】

#![allow(unused)]
#![warn(clippy::missing_errors_doc)]

fn main() {
use std::io;
// 不符合： Clippy 会警告 "warning: docs for function returning `Result` missing `# Errors` section"
pub fn read(filename: String) -> io::Result<String> {
    unimplemented!();
}
}

【正例】

#![allow(unused)]
#![warn(clippy::missing_errors_doc)]

fn main() {
use std::io;
// 符合：增加了规范的 Errors 文档注释

/// # Errors
///
/// Will return `Err` if `filename` does not exist or the user does not have
/// permission to read it.
pub fn read(filename: String) -> io::Result<String> {
    unimplemented!();
}
}

【Lint 检测】

G.CMT.02 如果公开的API在某些情况下会发生Panic，则相应文档中需增加 Panic 注释

【级别】 要求

【描述】

在公开（pub）函数文档中，建议增加 # Panic 注释来解释该函数在什么条件下会 Panic，便于使用者进行预处理。

说明： 该规则通过 cargo clippy 来检测。默认不会警告。

【反例】

#![allow(unused)]
#![warn(clippy::missing_panics_doc)]

fn main() {
// 不符合：没有添加 Panic 相关的文档注释，Clippy会报错 "warning: docs for function which may panic missing `# Panics` section"。
pub fn divide_by(x: i32, y: i32) -> i32 {
    if y == 0 {
        panic!("Cannot divide by 0")
    } else {
        x / y
    }
}
}

【正例】

#![allow(unused)]
#![warn(clippy::missing_panics_doc)]

fn main() {
// 符合：增加了规范的 Panic 注释
/// # Panics
///
/// Will panic if y is 0
pub fn divide_by(x: i32, y: i32) -> i32 {
    if y == 0 {
        panic!("Cannot divide by 0")
    } else {
        x / y
    }
}
}

【Lint 检测】

默认为 allow，但是此规则需要设置#![warn(clippy::missing_panics_doc)]。

G.CMT.03 在文档注释中要使用空格代替 tab

【级别】 建议

【描述】

Rust 代码风格中提倡使用四个空格代替tab，在文档注释中也应该统一使用四个空格。

【反例】

下面文档注释中使用了 tab。

#![allow(unused)]
fn main() {
// 不符合：文档注释中使用了 tab 缩进
///
/// Struct to hold two strings:
/// 	- first		one
/// 	- second	one
pub struct DoubleString {
   ///
   /// 	- First String:
   /// 		- needs to be inside here
   first_string: String,
   ///
   /// 	- Second String:
   /// 		- needs to be inside here
   second_string: String,
}
}

【正例】

#![allow(unused)]
fn main() {
// 符合：文档注释中使用了四个空格缩进
///
/// Struct to hold two strings:
///     - first        one
///     - second    one
pub struct DoubleString {
   ///
   ///     - First String:
   ///         - needs to be inside here
   first_string: String,
   ///
   ///     - Second String:
   ///         - needs to be inside here
   second_string: String,
}
}

【Lint 检测】

3. 编程实践

编码实践相关原则和规则，有助于编写更地道更安全的 Rust 代码。

3.1 常量

在 Rust 中，常量有两种用途：

• 编译时常量（Compile-time constants）
• 编译时求值 （CTEF, compile-time evaluable functions）

常量命名风格指南请看 编码风格-命名

G.CNS.01 对于科学计算中涉及浮点数近似值的常量宜使用预定义常量

【级别】 建议

【描述】

Rust标准库中已经提供了一些特殊常量的定义，其精确度通常会比开发者自行定义的高，所以若考虑数值精确度时则宜使用标准库已定义的特殊常量。

这些特殊常量都可以在标准库中找到，例如std::f32::consts

【反例】

#![allow(unused)]
fn main() {
let x = 3.14; // 不符合：自定义 Pi
let y = 1_f64 / x; // 不符合
}

【正例】

#![allow(unused)]
fn main() {
let x = std::f32::consts::PI; // 符合
let y = std::f64::consts::FRAC_1_PI; // 符合
}

【Lint 检测】

该 Lint 默认为 deny，但在某些场景下，可以设置为allow，#![allow(clippy::approx_constant)]。

G.CNS.02 不应断言常量布尔类型

【级别】 建议

【描述】

此类语句会被编译器优化掉。最好直接使用 panic! 或 unreachable!代替。

【反例】

#![allow(unused)]
fn main() {
// 不符合
const B: bool = false;
assert!(B);
assert!(true);
}

【正例】

#![allow(unused)]
fn main() {
// 符合
panic!（"something"）;
}

【例外】

该示例需要维护一个常量的不变性，确保它在未来修改时不会被无意中破坏。类似于 static_assertions 的作用。

#![allow(unused)]
#![allow(clippy::assertions_on_constants)]
fn main() {
const MIN_OVERFLOW: usize = 8192;
const MAX_START: usize = 2048;
const MAX_END: usize = 2048;
const MAX_PRINTED: usize = MAX_START + MAX_END;
assert!(MAX_PRINTED < MIN_OVERFLOW);
}

【Lint 检测】

G.CNS.03 不应将内部可变性容器声明为常量

【级别】 要求

【描述】

由于常量有内联的特性。若将一个内容可变容器声明为常量，那么在引用它的时候同样会新建一个实例，这样会破坏内容可变容器的使用目的， 所以需要将它的值存储为静态（static）或者直接将其定义为静态。

【反例】

#![allow(unused)]
fn main() {
use std::sync::atomic::{AtomicUsize, Ordering::SeqCst};
const CONST_ATOM: AtomicUsize = AtomicUsize::new(12);

// 不符合
CONST_ATOM.store(6, SeqCst); // 此处相当于新建了一个atomic实例，所以原容器内容并未改变
assert_eq!(CONST_ATOM.load(SeqCst), 12); // 仍为12，因为这两行的CONST_ATOM为不同实例

}

【正例】

#![allow(unused)]
fn main() {
use std::sync::atomic::{AtomicUsize, Ordering::SeqCst};
const CONST_ATOM: AtomicUsize = AtomicUsize::new(12);

// 符合
static STATIC_ATOM: AtomicUsize = CONST_ATOM;
STATIC_ATOM.store(9, SeqCst);
assert_eq!(STATIC_ATOM.load(SeqCst), 9); // 使用`static`, 故上下文的STATIC_ATOM皆指向同一个实例

// 符合： 或直接声明为static
static ANOTHER_STATIC_ATOM: AtomicUsize = AtomicUsize::new(15);
ANOTHER_STATIC_ATOM.store(9, SeqCst);
assert_eq!(ANOTHER_STATIC_ATOM.load(SeqCst), 9);
}

【Lint 检测】

G.CNS.04 不应在常量定义中增加显式的 'static 生命周期

【级别】 要求

【描述】

在常量和静态变量声明时已经默认含有隐式的'static生命周期，所以不需要额外增加显式'static。

【反例】

#![allow(unused)]
fn main() {
// 不符合
const FOO: &'static [(&'static str, &'static str, fn(&Bar) -> bool)] =
&[...]
static FOO: &'static [(&'static str, &'static str, fn(&Bar) -> bool)] =
&[...]
}

【正例】

#![allow(unused)]
fn main() {
// 符合
const FOO: &[(&str, &str, fn(&Bar) -> bool)] = &[...]
 static FOO: &[(&str, &str, fn(&Bar) -> bool)] = &[...]
}

【Lint 检测】

G.CNS.05 对于适用 const fn 的函数或方法宜尽可能地使用 const fn

【级别】 建议

【描述】

函数或方法缺失const关键词时无法被指派给常量。

但是要注意不是所有函数都能使用const fn，因为相比一般函数或方法，const fn在使用时会有限制，必须满足const 安全，如果不满足，编译器会报告错误信息。

【反例】

#![allow(unused)]
fn main() {
fn foo() -> usize {
    10
}

// 不符合：必须是 constant 函数才能用于声明 const 常量
const BAZ: usize = foo(); 
}

【正例】

#![allow(unused)]
fn main() {
const fn foo() -> usize {
    10
} 

const BAZ: usize = foo(); // 符合
}

【例外】

#![allow(unused)]
fn main() {
const fn foo() -> bool {
    for _i in 0..5 {}      // ERROR, 因为for loop默认不能用在const fn内（需要注明#![feature(const_for)]）
    false
}
}

【Lint 检测】

3.2 静态变量

静态变量是用 static 关键字定义的全局静态变量。

G.STV.01 不宜直接使用可变静态变量作为全局变量

【级别】 建议

【描述】

对可变静态变量直接进行全局修改是 Unsafe 的。在多线程应用中，修改静态变量会导致数据竞争（data race）。

【反例】

#![allow(unused)]
fn main() {
// 不符合
static mut NUM_OF_APPLES: usize = 0;

unsafe fn buy_apples(count: usize) {
    NUM_OF_APPLES += count;
}

unsafe fn eat_apple() {
    NUM_OF_APPLES -= 1;
}
}

【正例】

如果必须使用的话，可以通过 thread_local!宏在本地线程中使用内部可变性容器：

#![allow(unused)]
fn main() {
thread_local!{
    // 符合
    static NEXT_USER_ID: Cell<u64> = Cell::new(0);
}
}

若需要变更的值的类型为整数或布尔时，可直接使用 atomic。

#![allow(unused)]
fn main() {
use std::sync::atomic::{AtomicUsize, Ordering::SeqCst};


// 符合
static NUM_OF_APPLES: AtomicUsize = AtomicUsize::new(0);

fn buy_apple(count: usize) {
    NUM_OF_APPLES.fetch_add(count, SeqCst);
}

fn eat_apple() {
    NUM_OF_APPLES.fetch_sub(1, SeqCst);
}
}

补充说明：

若需修改整数或布尔之外的数据类型时，可考虑使用 Mutex 或 Rwlock 配合 once_cell 对全局变量进行变更。

（注: once_cell 目前已经被引入到 Nightly 版本的标准库中但还不稳定, 可参考 std::lazy。若要在 Stable 版本下使用，则需要引入第三方库 once_cell。）

#![feature(once_cell)]          // 需要nightly compiler

use std::sync::Mutex;
use std::lazy::SyncLazy;        // 若使用stable版本则需要将之替换为once_cell::sync::Lazy

static GLOBAL_MESSAGE: SyncLazy<Mutex<String>> = SyncLazy::new(|| {
    Mutex::new(String::from("I'm hungry"))
});

fn update_msg(msg: &str) {
    let mut old_msg = GLOBAL_MESSAGE.lock().unwrap();
    *old_msg = msg.to_string();
}

fn main() {
    println!("{}", GLOBAL_MESSAGE.lock().unwrap()); // I'm hungry
    update_msg("I'm not hungry anymore!");
    println!("{}", GLOBAL_MESSAGE.lock().unwrap()); // I'm not hungry anymore!
}

上述示例亦可通过使用第三方库 lazy_static 的方式实现。

#![allow(unused)]
fn main() {
use std::sync::Mutex;
use lazy_static::lazy_static;

lazy_static! {
    static ref GLOBAL_MESSAGE: Mutex<String> = Mutex::new(String::from("I'm hungry"));
}

fn update_msg(msg: &str) {
    ...
}
...
}

【例外】

在使用FFI引用外部，例如C的函数时，其本身有可能会返回全局变量。当 rust 接入这些函数时需要指定输入的变量类型为静态（static），而若要改变它们的值的时候就需要将其定义为可变静态变量（static mut）。

use std::ffi::CString;
use std::ptr;

#[link(name = "readline")]
extern {
    static mut rl_prompt: *const libc::c_char;
}

fn main() {
    let prompt = CString::new("[my-awesome-shell] $").unwrap();
    unsafe {
        rl_prompt = prompt.as_ptr();
        println!("{:?}", rl_prompt);
        rl_prompt = ptr::null();
    }
}

通常情况下直接修改 static mut 会有线程安全风险，但若配合使用 std::sync::Once 则可保证该变量只初始化一次，不会产生线程安全风险。

（注：此用法在功能上等同于 once_cell::sync::OnceCell 或 Nightly 版本中的 std::lazy::SyncOnceCell。但在使用 Stable 版本编译器并且不使用第三方库的条件下此写法完全合规，故算作例外情况。）

use std::sync::{Mutex, Once};

static mut SOUND: Option<Mutex<String>> = None;
static SOUND_ONCE: Once = Once::new();

fn make_sound() -> &'static Mutex<String> {
    unsafe {
        SOUND_ONCE.call_once(|| {
            SOUND = Some(Mutex::new("Oh! Apple! nom nom nom...".to_string()));
        });
        SOUND.as_ref().unwrap()
    }
}

fn main() {
    println!("{}", *make_sound().lock().unwrap()); // Oh! Apple! nom nom nom...
}

【Lint 检测】

【定制化参考】

这条规则如果需要定制 Lint，则应考虑两种情况:

1. 代码中定义为 static mut 的变量是否仅被用于 FFI
2. 代码中定义为 static mut 的变量是否经过 call_once 初始化

3.3 本地变量

这里所说的变量单指局部变量而不包括全局变量。 默认情况下，Rust 会强制初始化所有变量的值，以防止使用未初始化的内存。

P.VAR.01 一般情况下避免先声明可变变量再赋值

【描述】

一般情况下，不要先声明一个可变的变量，然后在后续过程中再去改变它的值。声明一个变量的时候，要对其进行初始化。如果后续可能会改变其值，要考虑优先使用变量遮蔽（继承式可变）功能。如果需要在一个子作用域内改变其值，再使用可变绑定或可变引用。

【反例】

#![allow(unused)]
fn main() {
// 不符合
let mut base : u8;
if cfg!(not(USB_PROTOCOL_NEW_ARCH)) {
    base = other_instance.base;
} else {
    base = 42u8;
}
}

【正例】

#![allow(unused)]
fn main() {
// 符合
let base : u8 = if cfg!(not(USB_PROTOCOL_NEW_ARCH)) {
    other_instance.base
} else {
    42u8
}
}

P.VAR.02 利用变量遮蔽功能保证变量安全使用

【描述】

在某些场景，可能会临时准备或处理一些数值，但在此之后，数据只用于检查而非修改。

那么可以将其通过变量遮蔽功能，重新绑定为不可变变量，来表明这种临时可变，但后面不变的意图。

【反例】

#![allow(unused)]
fn main() {
// 不符合：代码语义上没有表现出来先改变，后不变那种顺序语义
let data = {
    let mut data = get_vec();
    data.sort();
    data 
}

//  `data` 在后面不会再被改变
}

【正例】

#![allow(unused)]
fn main() {
// 符合
let mut data = get_vec();
data.sort(); //临时需要排序
let data = data; // 符合： 后面就不需要改动了，由编译器可以确保

//  `data` 在后面不会再被改变
}

G.VAR.01 以解构元组方式定义超过四个变量时不应使用太多无意义变量名

【级别】 建议

【描述】

在以解构元组的方式定义超过四个变量时，变量名可能是无特别语义的，如用单个字符表示的临时变量。但是不宜使用过多无意义变量名。

【反例】

#![allow(unused)]
#![warn(clippy::many_single_char_names)]
fn main() {
// 不符合
let (a, b, c, d, e, f, g) = (...);
}

【正例】

元组元素超过四个的，建议使用包含语义的变量命。

#![allow(unused)]
#![warn(clippy::many_single_char_names)]
fn main() {
// 符合
let (width, high, len, shape, color, status) = (...);
}

【Lint 检测】

该 lint 对应 clippy.toml 配置项：

# 修改可以绑定的单个字符变量名最大数量。默认为 4
single-char-binding-names-threshold=4

G.VAR.02 不应使用非 ASCII 字符作为标识符

【级别】 要求

【描述】

Rust 语言默认支持 Non ASCII 字符作为合法标识符。但是，为了统一团队代码风格，建议使用最常用的 ASCII 字符作为合法标识符。

此外，通常命名相关的 Clippy Lint 检查只支持英文命名。

【反例】

// 不符合
#[derive(Debug)]
struct 人 {
    /// 普通话
    名字: String,
    /// 廣東話
    屋企: String,
}

fn main () {
    let 我的名字 = "मनीष".to_string();
    let 我嘅屋企 = "Berkeley".to_string();
    
    // मराठी
    let मनीष = 人 {
        名字: 我的名字,
        屋企: 我嘅屋企,
    };
    
    // हिंदी
    let उसका_नाम = "مصطفى".to_string();
    let 他的家 = "Oakland".to_string();
   
    // اردو 
    let مصطفى = 人 {
        名字: उसका_नाम,
        屋企: 他的家,
    }; 
    
    println!("मी: {:?}", मनीष);
    println!("माझा मित्र: {:?}", مصطفى);
}

// 输出：
// मी: 人 { 名字: "मनीष", 屋企: "Berkeley" }
// माझा मित्र: 人 { 名字: "مصطفى", 屋企: "Oakland" }

【正例】

// 符合
#[derive(Debug)]
struct People {
    name: String,
    addr: String,
}

fn main () {
    let name = "मनीष".to_string();
    let addr = "Berkeley".to_string();
    
    // मराठी
    let me = People {
        name: name,
        addr: addr,
    };
    
    // हिंदी
    let name = "مصطفى".to_string();
    let addr = "Oakland".to_string();
   
    // اردو     
    let he = People {
        name: name,
        addr: addr,
    }; 
    
    println!("my name: {:?}", me);
    println!("his name: {:?}", he);
}

// 输出
// my name: People { name: "मनीष", addr: "Berkeley" }
// his name: People { name: "مصطفى", addr: "Oakland" }

【Lint 检测】

G.VAR.03 变量遮蔽功能应当合理使用

【级别】 建议

【描述】

变量遮蔽功能在功能上属于一种继承式可变。他会覆盖之前的变量绑定，而创建一个新的同名的变量绑定。

1. 在同一个作用域中，非必要时不宜通过新变量声明遮蔽旧变量声明的方式来修改变量。
2. 在子作用域内修改“哨兵变量”时，应该避免使用变量遮蔽功能，防止引起逻辑bug。
3. 如果使用变量遮蔽，禁止用不同类型的变量遮蔽前一个变量，如果实现同一个 trait 的可以例外。

【反例】

#![warn(clippy::shadow_reuse, clippy::shadow_same, clippy::shadow_unrelated)]

fn main() {
    let mut a = 0;
    {
        // 不符合：这里使用变量遮蔽，代码逻辑已经被改变
        // clippy::shadow_unrelated
        let a = 42;
    }
    
    a; // use a again

    let x = 2; 
    // 不符合： 将会改变x的值
    // clippy::shadow_reuse
    let x = x + 1; 

    // 不符合：只是改变引用级别
    // clippy::shadow_same
    let x = &x; 

    let y = 1;
    // 不符合：这里使用变量遮蔽逻辑已经被改变
    // clippy::shadow_unrelated
    let x = y; // 更早的绑定
    let z = 2;
    // 不符合：这里使用变量遮蔽逻辑已经被改变
    // clippy::shadow_unrelated
    let x = z; // 遮蔽了更早的绑定
}

【正例】

#![warn(clippy::shadow_reuse, clippy::shadow_same, clippy::shadow_unrelated)]

fn main() {
    let mut a = 0;
    {
        // 符合
        a = 42;
    }
    a;// use a again


    let x = 2;
    let y = x + 1; // 符合： 不改变x的值，声明新的变量y


    let ref_x = &x; // 符合：不改变x的绑定，声明新的变量
    let z = 2;
    let w = z; // 符合： 使用不同的名字
}

【Lint 检测】

G.VAR.04 避免因局部变量过大而导致的大量栈分配

【级别】 建议

【描述】

Rust 局部变量默认分配在栈上。当局部变量占用栈空间过大时，会栈溢出。

采用Box<T>分配也可能出现栈溢出，参见issues #53827，因为目前 Box<T>的行为是先在栈上分配然后再复制到堆上。

Rust 默认栈分配空间为：

1. 主线程默认 8MiB 。
2. 运行中代码创建的子线程默认是 2MiB 。

也可以自行配置栈分配内存大小。

所以，局部变量占用多少空间才算过大，这个需要开发者根据具体的场景根据栈大小配置情况做出合适的预判，一般以 512 KiB为宜。

【反例】

fn main() {
    // 不符合：运行时会栈溢出
    let a = [-1; 3000000];
    // or 
    // 不符合：运行时会栈溢出
    let a = Box::new([-1; 3000000]);
}

【正例】

#![allow(unused)]
fn main() {
// 符合：栈大小适中
let _: [i32; 8000] = [1; 8000];
}

3.4 数据类型

数据类型记录 Rust 标准库提供的 原生类型，以及结构体和枚举体等编码实践。

P.TYP.01 必要时，应使类型可以表达更明确的语义，而不是只是直接使用原生类型

【描述】

在类型中表达语义，可以增加代码的可读性。

【反例】

fn main() {
    // 不符合
    let years = 1942;
}

【正例】

// 符合： 语义更明确
struct Years(i64);

fn main() {
    let years = Years(1942);
    let years_as_primitive_1: i64 = years.0; 
    let Years(years_as_primitive_2) = years; 
}

G.TYP.01 类型转换尽可能使用安全的转换函数代替 as

【级别】 建议

【描述】

当在数字类型之间转换时，需要注意的是，如果要确保不会存在有损转换(lossy conversion)，就不要使用 as，而应该使用 From::from。因为 From 只实现了无损转换。例如，可以用From从i32转换到i64，但反过来转换却不允许。

对于指针类型，尽量使用 cast方法来代替 as 直接转换。

【反例】

#![warn(
    clippy::as_conversions,
    clippy::cast_lossless,
    clippy::cast_possible_truncation,
    clippy::cast_possible_wrap,
    clippy::cast_precision_loss,
    clippy::ptr_as_ptr
)]

fn as_u64(x: u8) -> u64 {
    // 不符合
    x as u64
}
// or

// 不符合
fn main() {
    // or
    let ptr: *const u32 = &42_u32;
    let mut_ptr: *mut u32 = &mut 42_u32;
    let _ = ptr as *const i32; // 不符合
    let _ = mut_ptr as *mut i32; // 不符合
}

【正例】

#![warn(
    clippy::as_conversions,
    clippy::cast_lossless,
    clippy::cast_possible_truncation,
    clippy::cast_possible_wrap,
    clippy::cast_precision_loss,
    clippy::ptr_as_ptr
)]

fn as_u64(x: u8) -> u64 {
    // 符合
    u64::from(x)
}

fn main() {
    let ptr: *const u32 = &42_u32;
    let mut_ptr: *mut u32 = &mut 42_u32;
    let _ = ptr.cast::<i32>(); // 符合
    let _ = mut_ptr.cast::<i32>(); // 符合
}

【Lint 检测】

G.TYP.02 数字字面量在使用的时候应该明确标注类型

【级别】 建议

【描述】

如果数字字面量没有被指定具体类型，那么单靠类型推导，整数类型会被默认绑定为 i32 类型，而浮点数则默认绑定为 f64类型。这可能导致某些运行时的意外。

【反例】

#![allow(unused)]
#![warn(clippy::default_numeric_fallback)]
fn main() {
// 不符合
let i = 10; // i32
let f = 1.23; // f64
}

【正例】

#![allow(unused)]
#![warn(clippy::default_numeric_fallback)]

fn main() {
// 符合
let i = 10u32;
let f = 1.23f32;
}

【Lint 检测】

G.TYP.03 不要用数字类型边界值判断能否安全转换，而应使用 try_from 方法

【级别】 建议

【描述】

在 Rust 中 From 代表不能失败的转换，而 TryFrom 则允许返回错误。

一般在数字类型转换的时候，不需要防御式地去判断数字大小边界，那样可读性比较差，应该使用 try_from 方法，在无法转换的时候处理错误即可。

【反例】

#![allow(unused)]
#![warn(clippy::checked_conversions)]

fn main() {
// 不符合
let foo: u32 = 5;
let _ = foo <= i16::MAX as u32; // 等价于 let _ = foo <= (i32::MAX as u32);
}

【正例】

#![allow(unused)]
#![warn(clippy::checked_conversions)]

fn main() {
// 符合
let foo: u32 = 5; 
let f = i16::try_from(foo).is_ok(); // 返回 false
}

【Lint 检测】

布尔

Rust 中的布尔类型有 true和false两种值。

G.TYP.BOL.01 不应将布尔值和布尔字面量进行比较

【级别】 要求

【描述】

在 Rust 中，返回为布尔值的表达式或函数值可以直接当作布尔值使用。

总之，使用布尔表达式的时候，要尽可能地简洁明了。

【反例】

#![allow(unused)]
fn main() {
// 不符合
if x == true {}
if y == false {}

assert_eq!("a".is_empty(), false);
assert_ne!("a".is_empty(), true);
}

【正例】

#![allow(unused)]
fn main() {
// 符合
if x {}
if !y {}

assert!(!"a".is_empty());
}

【Lint 检测】

G.TYP.BOL.02 如果 match 匹配表达式为布尔类型，宜使用 if 表达式来代替

【级别】 建议

【描述】

对于布尔表达式更倾向于使用 if ... else ...，相比 match 模式匹配更有利于代码可读性。

【反例】

#![allow(unused)]
#![warn(clippy::match_bool)]

fn main() {
fn foo() {}
fn bar() {}
let condition: bool = true;
// 不符合
match condition {
    true => foo(),
    false => bar(),
}
}

【正例】

#![allow(unused)]
#![warn(clippy::match_bool)]

fn main() {
fn foo() {}
fn bar() {}
let condition: bool = true;
// 符合
if condition {
    foo();
} else {
    bar();
}
}

【Lint 检测】

G.TYP.BOL.03 不应将数字类型转换为布尔值

【级别】 要求

【描述】

这可能会让布尔值在内存中的表示无效。

【反例】

#![allow(unused)]
fn main() {
let x = 1_u8;
unsafe {
    // 不符合
    let _: bool = std::mem::transmute(x); // where x: u8
}

}

【Lint 检测】

G.TYP.BOL.04 禁止在if表达式条件中使用块结构

【级别】 要求

【描述】

为了增加可读性。

【反例】

#![allow(unused)]
fn main() {
// 不符合
if { true } { /* ... */ }

fn somefunc() -> bool { true };
// 不符合
if { let x = somefunc(); x } { /* ... */ }
}

【正例】

#![allow(unused)]
fn main() {
// 符合
if true { /* ... */ }

fn somefunc() -> bool { true };
let res = { let x = somefunc(); x };
// 符合
if res { /* ... */ }
}

【Lint 检测】

G.TYP.BOL.05 非必要时，布尔运算应使用逻辑运算符( &&/||)而非位运算符 (&/|)

【级别】 建议

【描述】

位运算不支持短路（short-circuiting），所以会影响性能。逻辑运算符则支持短路。

【反例】

#![allow(unused)]
#![warn(clippy::needless_bitwise_bool)]
fn main() {
let (x,y) = (true, false);
if x & !y {} //  不符合：位运算符，不支持短路
}

【正例】

#![allow(unused)]
#![warn(clippy::needless_bitwise_bool)]

fn main() {
let (x,y) = (true, false);
if x && !y {} //  符合：逻辑运算符，支持短路
}

【Lint 检测】

G.TYP.BOL.06 不应使用数字代替布尔值

【级别】 要求

【描述】

Rust 中布尔值就是 true 和 false。 不要试图使用数字 1 和 0 来代替布尔值。

虽然 布尔值 可以强转为 对应的数字，但是反之则不行。

不要通过判断数字来代替 布尔值，除非是 FFi 场景通过 C-ABI 和其他语言打交道。

【反例】

#![allow(unused)]
fn main() {
// 不符合
let a = 1;
let b = 0;
assert_eq!(true, a == 1);  
assert_eq!(false, b == 0);
}

【正例】

#![allow(unused)]
fn main() {
// 符合
let a = true;
let b = false;
assert_eq!(true, a );
assert_eq!(false, b);
}

G.TYP.BOL.07 使用 .not() 方法代替逻辑取反运算符 (!)

【级别】 建议

【描述】

逻辑取反运算符 (!) 是前缀一元运算符，相对较长的逻辑表达式来说很不显眼。

理解业务逻辑时，容易忽略取反符号，并且需要回头看。

使用 .not() 后缀方法 (std::ops::Not) 可以吸引注意力，视觉上更为连续。

【反例】

#![allow(unused)]
fn main() {
assert!(!self.map.contains(&key));

if !cache.contains(&key) {
    // ...
}

// 不符合：容易忽略取反符号
}

【正例】

#![allow(unused)]
fn main() {
use std::ops::Not;

assert!(self.map.contains(&key).not());

if cache.contains(&key).not() {
    // ...
}

// 符合：`.not()` 更容易吸引注意力
}

字符

在 Rust 中，字符是一个合法的 Unicode 标量值（Unicode scalar value），一个字符大小为 4 字节，对应一个 Unicode 码位（CodePoint）。

G.TYP.CHR.01 不应将字符字面量强制转换为 u8

【级别】 建议

【描述】

应该使用字节字面量，而不应使用字符字面量强转为 u8。

【反例】

#![allow(unused)]
fn main() {
// 不符合
'x' as u8
}

【正例】

#![allow(unused)]
fn main() {
// 符合
b'x'
}

【Lint 检测】

G.TYP.CHR.02 字符串方法中如果需要单个字符的值作为参数，宜使用字符而非字符串

【级别】 建议

【描述】

大部分情况下，使用字符比用字符串性能更好。

【反例】

#![allow(unused)]
fn main() {
// 不符合
let s = "yxz";
s.split("x");
}

【正例】

#![allow(unused)]
fn main() {
// 符合
let s = "yxz";
s.split('x');
}

【Lint 检测】

G.TYP.CHR.03 需要将整数转换为字符时，应使用安全转换函数，而非 transmute

【级别】 要求

【描述】

并非每个整数都对应一个合法的 Unicode 标量值，使用 transmute 转换会有未定义行为。

【反例】

#![allow(unused)]
fn main() {
let x = 37_u32;
unsafe {
    // 不符合
    let x: char = std::mem::transmute(x); // where x: u32
    assert_eq!('%', x);
}
}

【正例】

#![allow(unused)]
fn main() {
let x = 37_u32;

// 符合：x 会返回一个 Result 类型，开发者可以进行错误处理
let x = std::char::from_u32(x); 
assert_eq!('%', x);

// 符合：如果确定该整数对应合法的 unicode，可以使用 uncheck 方法加速
let x = unsafe {std::char::from_u32_unchecked(x) };  
assert_eq!('%', x);
}

【Lint 检测】

整数

Rust 中有目前有十二种整数类型：i8/u8, i16/u16, i32/u32, i64/u64, i128/u128, isize/usize 。

G.TYP.INT.01 在用整数计算的时候需要考虑整数溢出、回绕和截断的风险

【级别】 建议

【描述】

如果从代码上下文的逻辑来看，该计算不可能产生溢出，则可以不进行校验。

比如，对于时间要求精准的系统，如果在计算时间发生整数溢出，或者去计算某个数组的索引等，那可能会发生严重问题。但如果你只是一个简单的计算器，不会被用到具体的业务场合，那溢出也没有关系，因为你只需要在合理的数字范围内计算性能最好。

在 Rust 标准库中，提供 add/ checked_add / saturating_add/overflowing_add / wrapping_add 不同系列方法，返回值不同，根据不同的场合选择适合的方法。

1. check_*函数返回Option，一旦发生溢出则返回None。
2. saturating_*系列函数返回类型是整数，如果溢出，则给出该类型可表示范围的“最大/最小”值。
3. wrapping_*系列函数则是直接抛弃已经溢出的最高位，将剩下的部分返回。即，返回直接二进制补码结果。
4. overflowing_*系列函数返回二进制补码结果以及指示是否发生溢出的布尔值。

Rust 编译器在编译时默认没有溢出检查（可通过编译参数来引入），但在运行时会有 Rust 内置 lint (#[deny(arithmetic_overflow)])来检查，如果有溢出会 Panic。

无符号整数使用时要注意回绕(wrap around)，不同整数类型转换时需注意截断。

【反例】

#![allow(unused)]
#![warn(clippy::integer_arithmetic)]

fn main() {
// 不符合
assert_eq!((-5i32).abs(), 5);
assert_eq!(100i32+1, 101);

fn test_integer_overflow() {

    // 不符合：这种写法 debug 与 release 编译时会有溢出检查
    let mut a: u8 = 255 + 1;
    
    // 不符合：这种写法，Rust 编译器不检查，但 Clippy可以检查到
    //  debug模式，运行 panic；release模式，x = 0
    let mut x: u8 = 255;
    x += 1;
    println!("x={}", x);
}
}

【正例】

#![allow(unused)]
#![warn(clippy::integer_arithmetic)]

fn main() {
// 符合
assert_eq!((-5i32).checked_abs(), Some(5));
assert_eq!(100i32.saturating_add(1), 101);

// 符合
fn add_num(a: u8) -> u8 { a.wrapping_add(255) }

fn test_integer_overflow() {
    // 符合： 对于字面量或常量表达式，debug 与 release 编译模式都会有溢出检查
    let mut a: u8 = 255 + 1;

    // 符合
    // debug模式，运行会Panic
    // release模式，x 会等于 0
    let mut x: u8 = 255;
    x = add_num(x);
    println!("x={}", x);
}
}

【Lint 检测】

G.TYP.INT.02 避免在有符号整数和无符号整数之间进行强制转换

【级别】 建议

【描述】

当有符号整数被强制转换为无符号整数时，负值会发生回绕（wrap around），变成更大的正值，这在实际应用时有可能助长缓冲区溢出风险。

注意：在 Rust 中整数溢出属于 未指定（unspecified）行为，而非未定义行为 （见 RFC 560）。

【反例】

#![warn(clippy::cast_sign_loss)]
fn main(){
    let y: i8 = -1;
    y as u128; // will return 18446744073709551615
}

【正例】

#![warn(clippy::cast_sign_loss)]

fn main(){
    let y : i8 = -1;
    // Error: 
    // the trait `From<i8>` is not implemented for `u128`
    // the trait bound `u128: From<i8>` is not satisfied
    let z = u128::from(y);
}

【Lint 检测】

注意：默认情况下该 lint 是 allow，如果需要检查这种转换，则需要设置为 warn或 deny。

参考

• https://huonw.github.io/blog/2016/04/myths-and-legends-about-integer-overflow-in-rust/
• https://github.com/rust-lang/rfcs/blob/master/text/0560-integer-overflow.md

G.TYP.INT.03 对负数取模计算的时候不应使用%

【级别】 建议

【描述】

Rust 中的 % 符号为余数运算符，它的行为与C或Java等语言中相同符号的运算符相同。它也类似于Python或Haskell等语言中的模（modulo）运算符，只是它对负数的行为不同：余数是基于截断除法，而模运算是基于向下取整（floor）除法。

【反例】

#![warn(clippy::modulo_arithmetic)]

fn main() {
    let a: i32 = -1;
    let b: i32 = 6;
    // 余数运算符只是返回第一个操作数除以第二个操作数的余数。所以 -1/6 给出 0，余数为 -1
    assert_eq!(a % b, -1);
}

【正例】

#![warn(clippy::modulo_arithmetic)]

fn main() {
    let a: i32 = -1;
    let b: i32 = 6;
	//  取模是严格低于第二个操作数的自然数（所以是非负数），与第二个操作数的最大倍数相加，也低于或等于第一个操作数，则为第一个操作数。
    //  6的最大倍数低于或等于-1 是 -6（6*-1），模数是5，因为-6+5=-1。
    assert_eq!(a.rem_euclid(b), 5);
}

【Lint 检测】

浮点数

Rust 的浮点数包括 f32 和 f64 两种类型。Rust 编译器默认推断的 Float 类型是 f64。

G.TYP.FLT.01 使用浮点数字面量时，要警惕是否存在被Rust编译器截断的风险

【级别】 建议

【描述】

当指定超过类型精度（f32 或 f64）的字面量值时，Rust 会默认截断该值。

【反例】

#![allow(unused)]
fn main() {
// 不符合
let v: f32 = 0.123_456_789_9;
println!("{}", v); //  0.123_456_789
}

【正例】

#![allow(unused)]
fn main() {
// 符合
let v: f64 = 0.123_456_789_9;
println!("{}", v); //  0.123_456_789_9
}

【Lint 检测】

G.TYP.FLT.02 从任何数字类型转换为浮点类型时注意避免损失精度

【级别】 建议

【描述】

开发者了解发生精度损失的位置，会对解决因为转换而损失精度的问题更加有好处。

【反例】

#![warn(clippy::cast_precision_loss)]

fn main(){
    // 不符合
    let x = u64::MAX;
    x as f64;
    // 不符合
    let x: f32 = 16_777_219.0 ; // 该数字转换为 f64 后会表示为 16_777_220.0
    x as f64;
}

【正例】

#![warn(clippy::cast_precision_loss)]

fn main(){
    // 符合
    let x = i32::MAX;
    let y = f64::from(x);  // 如果 x 为 u64 类型，则编译会出错，不接受这类转换
    // 符合
    let x: f32 = 16_777_219.0 ;
    let y = f64::from(x);  // 该数字转换为 f32 后会表示为 16_777_220.0
    println!("{y:?}")
}

【Lint 检测】

G.TYP.FLT.03 对精度高要求的场景下，使用浮点数进行运算和比较时需要注意精度损失

【级别】 建议

【描述】

浮点数计算通常都是不精确的，直接对浮点数进行运算和比较可能造成数据错误。 如何更好地处理浮点数，可以参阅 浮点数指南 。

但是对精度要求不高的场合，比如机器学习中某些场景，对此不做要求。

【反例】

#![warn(clippy::float_arithmetic, clippy::float_cmp, clippy::float_cmp_const)]

fn main(){
    let x = 1.2331f64;
    let y = 1.2332f64;

    payment(x, y);
}

fn payment(x: f64, y: f64) -> f64{
    // 不符合： 浮点数计算有精度损失
    y - x
}

【正例】

推荐使用精度更高的类型，比如 Decimal 类型（需要第三方库支持）。

#![warn(clippy::float_arithmetic, clippy::float_cmp, clippy::float_cmp_const)]

fn main(){
    let x = 1.2331f64;
    let y = 1.2332f64;

    payment(x, y);
}

fn payment(x: f64, y: f64) -> Result<f64, PaymentErr>{
    let z = y - x;
    let error_margin = f64::EPSILON;
    // 符合：浮点数的差异绝对值在允许范围内
    if z.abs() < error_margin {
        return Ok(z);
    } else {
        return PaymentErr(e);
    }
}

【Lint 检测】

G.TYP.FLT.04 宜使用Rust内置方法处理浮点数计算

【级别】 建议

【描述】

内置方法可能会牺牲一定性能，但可以提升准确性。

【反例】

#![warn(clippy::imprecise_flops, clippy::suboptimal_flops)]

// 不符合
fn main() {
    let a = 3f32;
    let _ = a.powf(1.0 / 3.0);
    let _ = (1.0 + a).ln();
    let _ = a.exp() - 1.0;

    use std::f32::consts::E;

    let a = 3f32;
    let _ = (2f32).powf(a);
    let _ = E.powf(a);
    let _ = a.powf(1.0 / 2.0);
    let _ = a.log(2.0);
    let _ = a.log(10.0);
    let _ = a.log(E);
    let _ = a.powf(2.0);
    let _ = a * 2.0 + 4.0;
    let _ = if a < 0.0 {
        -a
    } else {
        a
    };
    let _ = if a < 0.0 {
        a
    } else {
        -a
    };
}

【正例】

#![warn(clippy::imprecise_flops, clippy::suboptimal_flops)]

// 符合
fn main(){
    let a = 3f32;
    let _ = a.cbrt();
    let _ = a.ln_1p();
    let _ = a.exp_m1();

    use std::f32::consts::E;

    let a = 3f32;
    let _ = a.exp2();
    let _ = a.exp();
    let _ = a.sqrt();
    let _ = a.log2();
    let _ = a.log10();
    let _ = a.ln();
    let _ = a.powi(2);
    let _ = a.mul_add(2.0, 4.0);
    let _ = a.abs();
    let _ = -a.abs();
}

【Lint 检测】

G.TYP.FLT.05 禁止在浮点数和整数相互转换时使用 transmute

【级别】 要求

【描述】

使用 transmute 转换容易产生未定义行为，建议使用 to_bites 这样转换更加安全。

【反例】

#![allow(unused)]
fn main() {
// 不符合
unsafe {
    let _: u32 = std::mem::transmute(1f32);
    let _: f32 = std::mem::transmute(1_u32);
}
}

【正例】

#![allow(unused)]
fn main() {
//符合
let _: u32 = 1f32.to_bits();
let _: f32 = f32::from_bits(1_u32);
}

【Lint 检测】

切片

切片（slice）允许开发者引用集合中连续的元素序列，类型签名用 [T]表示，但因为它是动态大小类型（DST），所以一般用 &[T] 表示切片。

&str 就是一种字符串切片。

P.TYP.SLC.01 宜使用切片迭代器来代替手工索引

【描述】

在 for 循环中使用索引是比较常见的编程习惯，但是这种方式是最有可能导致边界错误的。

利用 切片自带的方法，并利用迭代器，可以避免这种错误。

【反例】

#![allow(unused)]
fn main() {
let points: Vec<Coordinate> = ...;
let differences = Vec::new();

// 不符合：人工计算长度选择范围很可能会出错
for i in 1..points.len() [
  let current = points[i];
  let previous = points[i-1];
  differences.push(current - previous);
]
}

【正例】

#![allow(unused)]
fn main() {
let points: Vec<Coordinate> = ...;
let mut differences = Vec::new();

// 符合：切片提供 windows 或 array_windows 方法返回迭代器
for [previous, current] in points.array_windows().copied() {
    differences.push(current - previous);
}
}

P.TYP.SLC.02 宜使用切片模式来提升代码的可读性

【描述】

切片也支持模式匹配，适当应用切片模式，可以有效提升代码可读性。

【正例】

利用切片模式编写判断回文字符串（如"aba"、"abba"之类）的函数。代码来自于：Daily Rust: Slice Patterns，还有更多用例。

#![allow(unused)]
fn main() {
pub fn word_is_palindrome(word: &str) -> bool {
    let letters: Vec<_> = word.chars().collect();

    is_palindrome(&letters)
}
// 符合：利用切片模式匹配来判断是否回文字符串
fn is_palindrome(items: &[char]) -> bool {
    match items {
        [first, middle @ .., last] => first == last && is_palindrome(middle),
        [] | [_] => true,
    }
}
}

元组

元组是异构复合类型，可以存储多个不同类型的元素。

G.TYP.TUP.01 使用元组时，其元素不宜超过3个

【级别】 建议

【描述】

元组是异构复合类型，元素过多，其表达力会下降，影响代码可读性和可维护性。

尤其是利用元组作为函数返回值时，不宜过多。

【反例】

// 不符合：超过3个元组参数
fn convert(x: i8) -> (i8, i16, i32, i64, f32, f64) {
    (x as i8, x as i16, x as i32, 
     x as i64, x as f32, x as f64)
}

fn main(){
    let _ = convert(3);
}

数组

这里指固定长度数组。注意，不同长度的数组，被视为不同的类型。比如 [T;1]和 [T;3] 是两种不同的类型。

从 Rust 1.51 版本开始，稳定了常量泛型（const generics）功能，形如 [T;1]和 [T;3] 这种不同的类型可以统一为 [T; N]。

G.TYP.ARR.01 创建大全局数组时宜使用静态变量而非常量

【级别】 建议

【描述】

因为常量会内联，对于大的数组，通常情况下，会使用其引用，使用静态变量定义更好。

栈上的数组大小以不超过 512KiB 为宜。

虽然常量本质上是会内联，但 Rust 支持复制消除（Copy Elision）优化（非强制），而且在不断改进完善中，对于这种大的数据应该会有相关优化。

【反例】

#![allow(unused)]
#![warn(clippy::large_stack_arrays)]

fn main() {
// 不符合
pub const A: [u32;1_000_000] = [0u32; 1_000_000];
}

【正例】

#![allow(unused)]
#![warn(clippy::large_stack_arrays)]

fn main() {
// 符合
pub static A: [u32;1_000_000] = [0u32; 1_000_000];
}

【Lint 检测】

注意： large_stack_arrays 会检查在栈上分配的大数组，但clippy默认是 allow，根据实际使用场景决定是否针对这种情况发出警告。

G.TYP.ARR.02 使用数组索引时禁止越界访问

【级别】 要求

【描述】

越界访问在运行时会 Panic！

【反例】

#![allow(unused)]
fn main() {
// 不符合
let x = [1, 2, 3, 4];
x[9];
&x[2..9];
}

【正例】

#![allow(unused)]
fn main() {
// 符合
let x = [1, 2, 3, 4];
x[0];
x[3];
}

【Lint 检测】

G.TYP.ARR.03 当数组元素为原生数据类型（Primitive），排序时优先选用非稳定排序

【级别】 建议

【描述】

稳定排序会消耗更多的内存和 CPU 周期，相对而言，非稳定排序性能更佳。

当然，在必须要稳定排序的场合，不应该使用非稳定排序。

注： Vec<T> 动态数组也适用此规则

【反例】

#![allow(unused)]
fn main() {
// 不符合
let mut vec = vec![2, 1, 3];
vec.sort();  // stable sort
}

【正例】

#![allow(unused)]
fn main() {
// 符合
let mut vec = vec![2, 1, 3];
vec.sort_unstable(); // unstable sort
}

【例外】

#![allow(unused)]
fn main() {
// https://docs.rs/crate/solana-runtime/1.7.11/source/src/accounts_db.rs#:~:text=clippy%3a%3astable_sort_primitive
 pub fn generate_index(&self, limit_load_slot_count_from_snapshot: Option<usize>) {
        let mut slots = self.storage.all_slots();
        #[allow(clippy::stable_sort_primitive)]
        slots.sort(); // 商业需求这里需要稳定排序
        // ...
}
}

【Lint 检测】

当确实需要稳定排序时，需要修改该 lint 的设置为 allow。

动态数组

这里指可以动态增长的数组Vec<T>。

在数组一节中有部分原则和规则也适用于这里。

P.TYP.VEC.01 非必要时不宜使用动态数组

【描述】

非必须不宜使用 Vec<T>，应该优先尝试使用固定长度数组或常量泛型。

或者可以参考第三方库，诸如 smallvec ，在元素比较少量的时候，可以放到栈上进行管理，如果超过一定元素才会选择堆内存。

【反例】

fn main() {
    // 不符合
    let v: Vec<i32> = vec![1, 2, 3];
    println!("{:#}", v);
}

【正例】

fn main() {
    // 符合
    let v = [1, 2, 3];
    println!("{:#?}", v);
}

P.TYP.VEC.02 创建动态数组时，宜预先分配足够容量，避免后续操作中产生多次分配

【描述】

预分配足够的容量，避免后续内存分配，可以提升代码性能。

【反例】

#![allow(unused)]
fn main() {
// 不符合
let mut output = Vec::new();
}

【正例】

#![allow(unused)]
fn main() {
// 符合
let mut output = Vec::with_capacity(input.len());
}

G.TYP.VEC.01 禁止访问未初始化的数组

【级别】 建议

【描述】

访问未初始化数组的内存会导致未定义行为。

【反例】

#![allow(unused)]
fn main() {
let mut vec: Vec<u8> = Vec::with_capacity(1000);
unsafe { vec.set_len(1000); }
// 不符合
reader.read(&mut vec); // error: Undefined Behavior: using uninitialized data, but this operation requires initialized memory
}

【正例】

#![allow(unused)]
fn main() {
// 符合
let mut vec: Vec<u8> = vec![0; 1000];
reader.read(&mut vec);
}

【Lint 检测】

结构体

Rust 包含了三种结构体： 命名结构体、元组结构体、单元结构体。

P.TYP.SCT.01 为结构体实现构造性方法时，避免构造后再初始化的情况

【描述】

跟其他OOP 或 FP 语言不一样， Rust 的惯用方式是构建即初始化。

【反例】

#![allow(unused)]
fn main() {
// 不符合
// 先构建
let mut dict = Dictionary::new();
// 后初始化
dict.load_from_file("./words.txt")?;
}

【正例】

#![allow(unused)]
fn main() {
// 符合
// 构建即初始化
let dict = Dictionary::from_file("./words.txt")?;

impl Dictionary {
  fn from_file(filename: impl AsRef<Path>) -> Result<Self, Error> {
    let text = std::fs::read_to_string(filename)?;
    // 不会去存储空状态
    let mut words = Vec::new();
    for line in text.lines() {
      words.push(line);
    }
    Ok(Dictionary { words })
  }
}
}

P.TYP.SCT.02 结构体实例需要默认实现时，宜使用Default特质

【描述】

为结构体实现 Default 对于简化代码提高可读性很有帮助。

【示例】

use std::{path::PathBuf, time::Duration};

#[derive(Default, Debug, PartialEq)]
struct MyConfiguration {
    output: Option<PathBuf>,
    search_path: Vec<PathBuf>,
    timeout: Duration,
    check: bool,
}

fn main() {
    // 使用 default 方法创建实例
    let mut conf = MyConfiguration::default();
    conf.check = true;
    println!("conf = {:#?}", conf);
        
    // 创建新实例的时候，使用局部更新更加方便
    let conf1 = MyConfiguration {
        check: true,
        ..Default::default()
    };
    assert_eq!(conf, conf1);
}

G.TYP.SCT.01 对外导出的公开的 Struct，宜添加#[non_exhaustive]属性

【级别】 建议

【描述】

作为对外公开的 结构体，为了保持稳定性，应该使用 #[non_exhaustive]属性，避免因为将来结构体字段发生变化而影响到下游的使用。主要涉及命名结构体和元组结构体。

【反例】

在 #[non_exhaustive] 属性稳定之前，社区内还有一种约定俗成的写法来达到防止下游自定义枚举方法。通过 manual_non_exhaustive 可以监控这类写法。

#![allow(unused)]
#![warn(clippy::exhaustive_structs)]

fn main() {
struct S {
    pub a: i32,
    pub b: i32,
    _priv: (),  // 不符合：这里用 下划线作为前缀定义的字段，作为私有字段，不对外公开
}

// 用户无法自定义实现该结构体的方法。
}

【正例】

#![allow(unused)]
#![warn(clippy::exhaustive_structs)]

fn main() {
// 符合
#[non_exhaustive]
struct Foo {
    bar: u8,
    baz: String,
}
}

【例外】

也有例外情况！

从语义角度看，#[non_exhaustive] 只是代表未穷尽的字段或枚举变体，是为了表达“未来可能有变化”这种语义。

但是当要表达 “这个结构体不允许对方实例化” 的语义时，通过自定义的 _priv字段就可以更好地表达这个语义。

而使用 #[non_exhaustive] 虽然也能达到 “不允许对方实例化的目的”，但是在代码可读性层面，却无法表达出这个语义。

#![allow(unused)]
fn main() {
// From: https://github.com/tokio-rs/tokio/blob/master/tokio-util/src/codec/framed.rs

#[allow(clippy::manual_non_exhaustive)]
pub struct FramedParts<T, U> {
    pub io: T,
    pub codec: U,
    pub read_buf: BytesMut,
    pub write_buf: BytesMut,
    
    /// This private field allows us to add additional fields in the future in a
    /// backwards compatible way.
    _priv: (),
}

impl<T, U> FramedParts<T, U> {
    /// Create a new, default, `FramedParts`
    pub fn new<I>(io: T, codec: U) -> FramedParts<T, U>
    where
        U: Encoder<I>,
    {
        FramedParts {
            io,
            codec,
            read_buf: BytesMut::new(),
            write_buf: BytesMut::new(),
            _priv: (),
        }
    }
}
}

【Lint 检测】

G.TYP.SCT.02 当结构体中有超过三个布尔类型的字段，宜将其独立为新的枚举类

【级别】 建议

【描述】

这样有助于提升 代码可读性和 API 。

【反例】

#![allow(unused)]
#![warn(clippy::struct_excessive_bools)]

fn main() {
// 不符合
struct S {
    name: String,
    is_pending: bool,
    is_processing: bool,
    is_finished: bool,
}
}

【正例】

#![allow(unused)]
#![warn(clippy::struct_excessive_bools)]
fn main() {
// 符合
struct S {
    name: String,
    state: State,
}

enum State {
    Pending,
    Processing,
    Finished,
}
}

【Lint 检测】

该 lint 对应 clippy.toml 配置项：

# 用于配置函数可以拥有的 bool 类型参数最大数量，默认为 3。
max-struct-bools=3 

G.TYP.SCT.03 宜使用结构体功能更新语法来提升代码可读性

【级别】 建议

【描述】

更改结构体最好提供结构体方法进行更改，而不是直接构建结构体内容。

但是需要多次修改结构体内容的时候，宜使用结构体更新语法来提升代码可读性。

【反例】

#![allow(unused)]
fn main() {
// 不符合
impl<'a> Colorize for &'a str {
    fn red(self) -> ColoredString {
        ColoredString {
            fgcolor: String::from("31"),
            input: String::from(self), // 该方法只更新 fgcolor 和 input
            bgcolor: String::default(); // 如果该结构体字段比较多的话，此处就需要指派很多字段，不太方便
        }   
    }
    fn on_yellow(self) -> ColoredString {
        ColoredString {
            bgcolor: String::from("43"),
            input: String::from(self),
            fgcolor: String::default();
        }   
    }
}
}

【正例】

#![allow(unused)]
fn main() {
// 符合
impl<'a> Colorize for &'a str {
    fn red(self) -> ColoredString {
        ColoredString {
            fgcolor: String::from("31"),
            input: String::from(self),
            ..ColoredString::default() // 通过该语法，开发者可以快速了解该方法只更新 fgcolor 和 input，也不需要指派其他不需要更新的字段，更加方便
        }   
    }
    fn on_yellow(self) -> ColoredString {
        ColoredString {
            bgcolor: String::from("43"),
            input: String::from(self),
            ..ColoredString::default()
        }
    }
}
}

【Lint 检测】

枚举体

Rust 的枚举是一种带 Tag 的联合体。 一般分为三类：空枚举、无字段（fieldless）枚举和数据承载（data carrying）枚举。

G.TYP.ENM.01 合理使用map和and_then方法

【级别】 建议

【描述】

在标准库中内置的一些 Enum 类型中提供了一些方便的组合算子，比如 map 和 and_then。

• map ，函数签名是 fn map<U, F>(self, f: F) -> Option<U> where F: FnOnce(T) -> U 。
• and_then ，函数签名是 fn and_then<U, F>(self, f: F) -> Option<U> where F: FnOnce(T) -> U 。

Result 中实现的 map/and_then 函数签名也和 Option 一致。这两个方法之间的区别在于传入的闭包参数的返回值类型不同。

这意味着：

• 当你通过 F 对 U 进行 map 转换的时候，意味着这个转换是一定会成功的。
• 当你通过 F 对 U 进行 and_then 转换的时候，意味着这个转换是不一定会成功的，需要在 F 调用之后对其结果 Option<U>/Result<U> 进行处理。

在合适的场景中选择合适的组合算子，可以让代码更加简洁，提升可读性和可维护性。

【反例】

#![allow(unused)]
fn main() {
// 不符合： 当前这种情况是一定会成功的情况，应该使用 map
fn opt() -> Option<&'static str> { Some("42") }
fn res() -> Result<&'static str, &'static str> { Ok("42") }
let _ = opt().and_then(|s| Some(s.len()));
let _ = res().and_then(|s| if s.len() == 42 { Ok(10) } else { Ok(20) });
let _ = res().or_else(|s| if s.len() == 42 { Err(10) } else { Err(20) });

}

【正例】

#![allow(unused)]
fn main() {
// 符合
fn opt() -> Option<&'static str> { Some("42") }
fn res() -> Result<&'static str, &'static str> { Ok("42") }
let _ = opt().map(|s| s.len());
let _ = res().map(|s| if s.len() == 42 { 10 } else { 20 });
let _ = res().map_err(|s| if s.len() == 42 { 10 } else { 20 });
}

【Lint 检测】

G.TYP.ENM.02 不应自行创建空枚举

【级别】 建议

【描述】

在 Rust 中 只有 never 类型（!）才是唯一合法表达 无法被实例化类型 的类型。但目前 never 类型还未稳定，只能在 Nightly 下使用。

【反例】

#![allow(unused)]
#![feature(never_type)] // 当启用该功能的时候，下面的clippy才会生效
#![warn(clippy::empty_enum)]

fn main() {
// 不符合
enum Test {}
}

【正例】

所以，如果想在稳定版 Rust 中使用，建议使用std::convert::Infallible 。 Infallible 枚举是一个合法的空枚举，常用于错误处理中，表示永远不可能出现的错误。但是目前也可以用于在稳定版中替代 never 类型。

#![allow(unused)]
#![feature(never_type)] // 当启用该功能的时候，下面的clippy才会生效
#![warn(clippy::empty_enum)]

fn main() {
//符合： 未来 never 类型稳定的话，将会把 Infallible 设置为 never 类型的别名
pub type Infallible = !;
}

【例外】

因为 std::convert::Infallible 默认实现了很多 trait，如果不想依赖其他 trait ，那么可以用 空枚举。

#![allow(unused)]
#![feature(never_type)] // 当启用该功能的时候，下面的clippy才会生效
#![allow(clippy::empty_enum)]
fn main() {
pub enum NoUserError {}

impl Display for NoUserError {
    fn fmt(&self, _formatter: &mut fmt::Formatter) -> fmt::Result {
        match *self {}
    }
}

}

【Lint 检测】

G.TYP.ENM.03 在使用类似 C 语言的枚举写法且使用repr(isize/usize) 布局时注意 32位架构上截断的问题

【级别】 建议

【描述】

在使用类似 C 语言的枚举写法且使用repr(isize/usize) 布局时，在32位架构上会截断变体值，但在64位上工作正常。

【反例】

#![allow(unused)]

fn main() {
#[repr(usize)]
enum NonPortable {
    X = 0x1_0000_0000, // 不符合：如果在 32位架构上会截断变体值，导致该指针地址变化
    Y = 0,
}
}

【正例】

因为当前 lint 默认是 deny，所以需要将其配置为 allow。

#![allow(unused)]
#![allow(clippy::enum_clike_unportable_variant)]

fn main() {
#[repr(isize)]
pub enum ZBarColor {
    ZBarSpace = 0, // 符合：因为值足够小，没有截断风险
    ZBarBar   = 1,
}

// 符合：没有指定 repr(isize/usize)
#[allow(clippy::enum_clike_unportable_variant)]
pub(crate) enum PropertyType {
    ActionItemSchemaVersion = 0x0C003473,
    ActionItemStatus = 0x10003470,
    ActionItemType = 0x10003463,
    Author = 0x1C001D75,
}
}

【Lint 检测】

G.TYP.ENM.04 不宜在use语句中引入Enum的全部变体（variants）

【级别】 建议

【描述】

使用 Enum 的类型前缀可以使代码更加可读。

【反例】

#![allow(unused)]
#![warn(clippy::enum_glob_use)]

fn main() {
// 不符合
use std::cmp::Ordering::*; // 这里导入了全部变体
foo(Less);
}

【正例】

#![allow(unused)]
#![warn(clippy::enum_glob_use)]

fn main() {
// 符合
use std::cmp::Ordering;
foo(Ordering::Less)


}

【例外】

当枚举体非常多的时候，比如 oci_spec::Arch 中对应平台架构的枚举值，直接用 * 导入会更加方便。

#![allow(unused)]
fn main() {
// From:  https://github.com/alacritty/alacritty/blob/master/alacritty/src/config/bindings.rs#L368
#![allow(clippy::enum_glob_use)]
use oci_spec::Arch::*;

pub enum Arch {
    /// The native architecture.
    ScmpArchNative = 0x00000000,

    /// The x86 (32-bit) architecture.
    ScmpArchX86 = 0x40000003,

    /// The x86-64 (64-bit) architecture.
    ScmpArchX86_64 = 0xc000003e,

    // ... more 
}
}

【Lint 检测】

G.TYP.ENM.05 对外导出的公开Enum，宜添加#[non_exhaustive]属性

【级别】 建议

【描述】

作为对外公开的 Enum，为了保持稳定性，应该使用 #[non_exhaustive]属性，避免因为将来Enum 枚举变体的变化而影响到下游的使用。

【反例】

在 #[non_exhaustive] 属性稳定之前，社区内还有一种约定俗成的写法来达到防止下游自定义枚举方法。

#![allow(unused)]
#![warn(clippy::exhaustive_enums)]

fn main() {
enum E {
    A,
    B,
    #[doc(hidden)]
    _C, // 不符合： 这里用 下划线作为前缀定义的变体，作为隐藏的变体，不对外展示
}
}

【正例】

#![allow(unused)]
fn main() {
// 符合
#[non_exhaustive]
enum E {
    A,
    B,
}
}

【Lint 检测】

G.TYP.ENM.06 Enum内变体的大小差异不宜过大

【级别】 建议

【描述】

要注意 Enum 内变体的大小差异不要过大，因为 Enum 内存布局是以最大的变体进行对齐。根据场景，如果该Enum 实例中小尺寸变体的实例使用很多的话，内存就会有所浪费。如果小尺寸变体的实例使用很少，则影响不大。

解决办法之一为把大尺寸变体包含到 Box<T>中。

【反例】

#![allow(unused)]
fn main() {
// 不符合
enum Test {
    A(i32),
    B([i32; 1000]),
    C([i32; 8000]),
}
}

【正例】

#![allow(unused)]
fn main() {
// 符合
enum Test {
    A(i32),
    B(Box<[i32; 1000]>),
    C(Box<[i32; 8000]>),
}
}

【Lint 检测】

该 lint 可以通过 clippy 配置项 enum-variant-size-threshold = 200 来配置，默认是 200 字节。

G.TYP.ENM.07 如需依赖 Enum 中变体的序数，则应为变体设置明确的数值

【级别】 要求

【描述】

在日常开发中，有时需要产生出有独立名称，且为连续或是有规律的数值，用来当作接口的参数数值，一般采用枚举（Enum）来实现。

Rust 语言的枚举变体的序数（ordinal）依赖于它的定义顺序。在开发过程中，很有可能需要新增变体。一般情况下，都是从尾部追加变体，但不排除有人会从中间新增变体，或者，依赖于某些库将变体自动按字典序排序，这样就有可能打乱枚举变体本来到顺序，导致程序中依赖变体序数的代码产生逻辑错误。

所以，在这种情况下，我们需要为变体设置明确的数值

【反例】

// 不符合
enum Mode {
    Mode0, // 0
    Mode1, // 1
    Mode3, // 2
    Mode2, // 3
}
 
fn main() {
    // 不符合：报错，此处 Mode::Mode3 对应值为 2 ，而不是 3
    assert_eq!(3, Mode::Mode3 as u8);
}

【正例】

// 符合
enum Mode {
    Mode0 = 0, 
    Mode1 = 1, 
    Mode3 = 3, 
    Mode2 = 2, 
}
 
fn main() {
    // 符合
    assert_eq!(3, Mode::Mode3 as u8);
}

3.5 表达式

Rust 中几乎一切皆表达式。

G.EXP.01 当需要对表达式求值后重新赋值时，宜使用复合赋值模式

【级别】 建议

【描述】

略

【反例】

#![allow(unused)]
fn main() {
let mut a = 5;
let b = 0;
a = a + b; // 不符合
}

【正例】

#![allow(unused)]
fn main() {
let mut a = 5;
let b = 0;
a += b; // 符合
}

【Lint 检测】

G.EXP.02 不宜在比较中使用不兼容的位掩码

【级别】 要求

【描述】

如果比较的位总是被位掩码设置为零或一，则比较是常量true或 false（取决于掩码、比较值和运算符），这种代码是有误导性的，可能是故意这么写用于赢得一场性能竞赛或者是通过一个测试用例。

可以对照下面表格进行检查。

【反例】

#![allow(unused)]
fn main() {
let x = 2;
// 不符合：该表达式会永远是 false
if (x & 1 == 2) { }
}

【正例】

#![allow(unused)]
fn main() {
let x = 2;
// 符合
if (x == 2) { }
}

【Lint 检测】

G.EXP.03 不应利用数组表达式的边界检查来 Panic，而应使用断言

【级别】 建议

【描述】

这样会影响代码可读性。使用断言可以更好的描述代码的意图。

【反例】

fn main(){
   // 不符合
   [42, 55][get_usize()];
   compute_array()[0];
}

fn get_usize() -> usize {
   6
}

fn compute_array() -> [i32; 3] {
   [1,2,3]
}

【正例】

fn main(){
   // 符合
   assert!([42, 55].len() > get_usize());
   assert!(compute_array().len() > 0);
}

fn get_usize() -> usize {
   6
}

fn compute_array() -> [i32; 3] {
   [1,2,3]
}

【Lint 检测】

G.EXP.04 自增或自减运算使用+=或-=

【级别】 建议

【描述】

C/Cpp 等编程语言常用的自增自减操作，如 ++i 、i++ 、i-- 等不是合法的 Rust 表达式， --i 虽然是合法的 Rust 表达式，但是表达对i取反两次，而不是自减语义。

【反例】

#![allow(unused)]
fn main() {
let mut x = 3;
--x; // 不符合：x 的值还是 3
}

【正例】

#![allow(unused)]
fn main() {
let mut x = 3;
x -= 1; // 符合
}

【Lint 检测】

G.EXP.05 使用括号来清楚表示表达式的计算顺序

【级别】 建议

【描述】

并不是每个人都能记得住优先级，所以最好使用括号把优先级顺序区分出来，增加可读性。

【反例】

#![allow(unused)]
fn main() {
1 << 2 + 3 // 不符合
-1i32.abs() // 不符合
}

【正例】

#![allow(unused)]
fn main() {
(1 << 2) + 3  // 符合
(-1i32).abs() // 符合
}

【Lint 检测】

G.EXP.06 避免在比较中添加无用的掩码操作

【级别】 要求

【描述】

检查比较中的无用位掩码操作，可以在不改变结果的情况下删除该位掩码操作。

请对照下面表格进行检查。

【反例】

#![allow(unused)]
fn main() {
// 不符合
if (x | 1 > 3) {  }
}

【正例】

#![allow(unused)]
fn main() {
// 符合
if (x > 3) {  }
}

【Lint 检测】

3.6 控制流程

Rust中流程控制也是属于表达式，但在本规范中将其独立出来。

P.CTF.01 避免滥用迭代器

【描述】

迭代器虽然是 Rust 中比较推崇的方式，但也没必要过度使用它。总之，如果使用迭代器让代码太复杂，就考虑换个非迭代器的方式实现吧。

【反例】

创建一个 Matrix变换的函数，但是这种迭代器的方式，代码可读性相比于命令式更困难。

#![allow(unused)]
fn main() {
// From : https://adventures.michaelfbryan.com/posts/rust-best-practices/bad-habits/#overusing-iterators
pub fn functional_blur(input: &Matrix) -> Matrix {
    assert!(input.width >= 3);
    assert!(input.height >= 3);

    let mut rows = input.rows();
    let first_row = rows.next().unwrap();
    let last_row = rows.next_back().unwrap();

    let top_row = input.rows();
    let middle_row = input.rows().skip(1);
    let bottom_row = input.rows().skip(2);

    let blurred_elements = top_row
        .zip(middle_row)
        .zip(bottom_row)
        .flat_map(|((top, middle), bottom)| blur_rows(top, middle, bottom));

    let elements: Vec<f32> = first_row
        .iter()
        .copied()
        .chain(blurred_elements)
        .chain(last_row.iter().copied())
        .collect();

    Matrix::new_row_major(elements, input.width, input.height)
}

fn blur_rows<'a>(
    top_row: &'a [f32],
    middle_row: &'a [f32],
    bottom_row: &'a [f32],
) -> impl Iterator<Item = f32> + 'a {
    // 不符合： 使用迭代器处理矩阵变换，代码不直观

    let &first = middle_row.first().unwrap();
    let &last = middle_row.last().unwrap();

    let top_window = top_row.windows(3);
    let middle_window = middle_row.windows(3);
    let bottom_window = bottom_row.windows(3);

    let averages = top_window
        .zip(middle_window)
        .zip(bottom_window)
        .map(|((top, middle), bottom)| top.iter().chain(middle).chain(bottom).sum::<f32>() / 9.0);

    std::iter::once(first)
        .chain(averages)
        .chain(std::iter::once(last))
}
}

【正例】

创建一个 Matrix变换的函数，使用命令式风格，代码功能比较明确，更加直观。

#![allow(unused)]
fn main() {
// From: https://adventures.michaelfbryan.com/posts/rust-best-practices/bad-habits/#overusing-iterators
pub fn imperative_blur(input: &Matrix) -> Matrix {
    assert!(input.width >= 3);
    assert!(input.height >= 3);

    let mut output = input.clone();

    for y in 1..(input.height - 1) {
        for x in 1..(input.width - 1) {
            let mut pixel_value = 0.0;

            // 符合： 直接使用数组计算坐标更加直观方便
            pixel_value += input[[x - 1, y - 1]];
            pixel_value += input[[x, y - 1]];
            pixel_value += input[[x + 1, y - 1]];

            pixel_value += input[[x - 1, y]];
            pixel_value += input[[x, y]];
            pixel_value += input[[x + 1, y]];

            pixel_value += input[[x - 1, y + 1]];
            pixel_value += input[[x, y + 1]];
            pixel_value += input[[x + 1, y + 1]];

            output[[x, y]] = pixel_value / 9.0;
        }
    }

    output
}
}

P.CTF.02 优先使用模式匹配而非判断后再取值

【描述】

Rust 中 模式匹配 是惯用法，而不是通过 if 判断值是否相等。

【反例】

#![allow(unused)]
fn main() {
let opt: Option<_> = ...;
// 不符合
if opt.is_some() {
  let value = opt.unwrap();
  ...
}

// 不符合
let list: &[f32] = ...;

if !list.is_empty() {
  let first = list[0];
  ...
}

}

【正例】

#![allow(unused)]
fn main() {
// 符合
if let Some(value) = opt {
  ...
}
// 符合
if let [first, ..] = list {
  ...
}
}

G.CTF.01 当需要通过多个if判断来比较大小来区分不同情况时，优先使用match和cmp来代替if表达式

【级别】 建议

【描述】

在使用多个if-else来对不同情况进行区分时，使用 match 和 cmp 代替 if 的好处是语义更加明确，而且也能帮助开发者穷尽所有可能性。 但是这里需要注意这里使用 match 和 cmp 的性能要低于 if表达式，因为 一般的 > 或 < 等比较操作是内联的，而 cmp方法没有内联。

【反例】

#![allow(unused)]
fn main() {
fn a() {}
fn b() {}
fn c() {}
fn f(x: u8, y: u8) {
    // 不符合
    if x > y {
        a()
    } else if x < y {
        b()
    } else {
        c()
    }
}
}

【正例】

#![allow(unused)]
fn main() {
use std::cmp::Ordering;
fn a() {}
fn b() {}
fn c() {}
fn f(x: u8, y: u8) {
    // 符合
     match x.cmp(&y) {
         Ordering::Greater => a(),
         Ordering::Less => b(),
         Ordering::Equal => c()
     }
}
}

【Lint 检测】

G.CTF.02 if条件表达式分支中如果包含了else if分支也应该包含else分支

【级别】 建议

【描述】

这样做有助于代码逻辑更加健壮清晰，在一些要求严格的编码规范中要求这么做，比如《MISRA-C:2004 Rule 14.10》编码规范。

【反例】

#[warn(clippy::else_if_without_else)]
fn a() {}
fn b() {}

fn main(){
    let x: i32 = 1;
    if x.is_positive() {
        a();
    } else if x.is_negative() {
        b();
    } // 不符合：没有 else 分支
}

【正例】

#[warn(clippy::else_if_without_else)]
fn a() {}
fn b() {}

fn main(){
    let x: i32 = 1;
    if x.is_positive() {
        a();
    } else if x.is_negative() {
        b();
    } else {
        // 符合
    }
}

【Lint 检测】

G.CTF.03 如果要通过 if 条件表达式来判断是否 Panic，请优先使用断言

【级别】 建议

【描述】

略

【反例】

#![allow(unused)]
fn main() {
let sad_people: Vec<&str> = vec![];
// 不符合
if !sad_people.is_empty() {
    panic!("there are sad people: {:?}", sad_people);
}
}

【正例】

#![allow(unused)]
fn main() {
let sad_people: Vec<&str> = vec![];
// 符合
assert!(sad_people.is_empty(), "there are sad people: {:?}", sad_people);
}

【Lint 检测】

G.CTF.04 在 Match 分支的 Guard 语句中不要使用带有副作用的条件表达式

【级别】 建议

【描述】

因为在 mactch 分支中， 匹配几次就会执行 Guard 几次。如果携带副作用，会产生意料之外的情况。

【反例】

// 不符合：下面代码会输出两次 "ha"
fn main() {
    use std::cell::Cell;
    let i: Cell<i32> = Cell::new(0);
    match 1 {
        1 | _  // 这里匹配两次
            if { // 这个 Guard 条件表达式带有副作用：打印，因为匹配两次，所以会执行两次
                println!("ha");
                i.set(i.get() + 1);
                false
            } => {}
        _ => {}
    }
    assert_eq!(i.get(), 2);
}

3.7 字符串

Rust 中字符串是有效的 UTF-8 编码的字节数组。

Rust 字符串类型众多，但本节内容主要围绕 ：String / &str

P.STR.01 处理字符串元素时优先按字节处理而非字符

【描述】

处理字符串有两种方式，一种是按字符处理，即把字符串转为字符数组[char]，另一种是直接按字节处理[u8]。

两者之间的一些区别：

• [char] 保证是有效的 Unicode，但不一定是有效的 UTF-8，一般将其看作是 UTF-32 。将字符数组转换为字符串需要注意。
• [u8] 不一定是有效的字符串，它比 [char] 节省内存。将其转换为字符串需要检查 UTF-8编码。

P.STR.02 创建字符串时，宜预先分配大约足够的容量来避免后续操作中产生多次分配

【描述】

预分配足够的容量，避免后续内存分配，可以提升代码性能。

【反例】

#![allow(unused)]
fn main() {
let mut output = String::new();
}

【正例】

#![allow(unused)]
fn main() {
let mut output = String::with_capacity(input.len());
}

P.STR.03 在使用内建字符串处理函数或方法的时候，应注意避免隐藏的嵌套迭代或多次迭代

【描述】

比如 contains 函数的实现就是按字符遍历字符串，但是如果你将它用于一个字符串的迭代处理中，就会产生嵌套迭代，时间复杂度从你以为的 O(n) 变成了 O(n^2)。没有将其用于迭代中，也有可能产生多次迭代，O(n) 变为 O(n+m) 。 为了避免这个问题，我们可以用 find 来代替 contains。

所以，在使用内建函数的时候要注意它的实现，选择合适的函数或方法，来避免这类问题。

【示例】

#![allow(unused)]
fn main() {
// 对输入的字符串进行转义
pub fn find<'a, S: Into<Cow<'a, str>>>(input: S) -> Cow<'a, str> {
    let input = input.into();
    fn is_trouble(c: char) -> bool {
        c == '<' || c == '>' || c == '&'
    }
    
    // 使用 find 而非 contains
    // find 使用模式查找，可以返回匹配字符的位置信息
    let first = input.find(is_trouble);
    
    // 利用 find 的位置信息，避免第二次遍历
    if let Some(first) = first {
        let mut output = String::from(&input[0..first]);
        output.reserve(input.len() - first);
        let rest = input[first..].chars();
        for c in rest {
            match c {
                '<' => output.push_str("&lt;"),
                '>' => output.push_str("&gt;"),
                '&' => output.push_str("&amp;"),
                _ => output.push(c),
            }
        }

        Cow::Owned(output)
    } else {
        input.into()
    }
}
}

P.STR.04 在使用 Cow<'a, B> 时要注意选择合理场景以便最大化地优化性能

【描述】

Cow<'a, B> 可以减少不必要的内存拷贝。Cow 代表 Clone-On-Write，意味着，使用它可以只在必要的时候再进行拷贝。

但它并不是万能的，只有在需要大量读取数据但仅有少量情况需要修改时，Cow<'a, B> 才能真正起到优化性能的作用。

如果不在意依赖库过多，编译文件更大，也可以使用第三方库 regex 来处理大数据的搜索匹配和替换等需求，性能更佳。

【反例】

假设场景一：要处理的大文件中，至少一半数据包含转义符号

#![allow(unused)]
fn main() {
// 不符合：这种情况在输入不包含转义符号的数据时，也需要对所有字符进行匹配处理，性能较低
pub fn naive(input: &str) -> String {
    let mut output = String::new();
    for c in input.chars() {
        match c {
            '<' => output.push_str("&lt;"),
            '>' => output.push_str("&gt;"),
            '&' => output.push_str("&amp;"),
            _ => output.push(c)
        }
    }
    output
}
}

假设场景二：要处理的大文件中，几乎所有数据都包含转义符号。这种场景下，使用 Cow<'a, B> 对性能也无法起到太大的优化作用，此时宜尝试使用 regex 之类的高性能第三方库处理。

【正例】

假设场景一：要处理的大文件中，至少一半数据包含转义符号。

#![allow(unused)]
fn main() {
// 对输入的字符串进行转义
// 符合： 性能提升大概 1 倍
pub fn naive<'a, S: Into<Cow<'a, str>>>(input: S) -> Cow<'a, str> {
    let input = input.into();
    fn is_trouble(c: char) -> bool {
        c == '<' || c == '>' || c == '&'
    }

    if input.contains(is_trouble) {
        let mut output = String::with_capacity(input.len());
        for c in input.chars() {
            match c {
                '<' => output.push_str("&lt;"),
                '>' => output.push_str("&gt;"),
                '&' => output.push_str("&amp;"),
                _ => output.push(c)
            }
        }
        // 只有在字符串修改的时候才使用 String
        Cow::Owned(output)
    } else {
        //其他情况使用 &str
        input
    }
}
}

P.STR.05 在拼接字符串时，优先使用format!

【描述】

在Rust中有很多方法可以连接字符串，不同的连接方法适用于不同的场景，性能也会有所差别。

【示例】

 // 组合字符串是最简单和直观的方法，尤其是在字符串和非字符串混合的情况下。
 fn main() {
	let name = "world!";
	let hw = format!("Hello {}!", name);
	println!("{:#?}", hw);
 }
 
 // 在追加字符串的时候，可以使用`push_str`方法,`push_str`性能比`format!`更好
 fn main() {
    let mut hw = String::new();
    hw.push_str("hello");
    hw.push_str(" world!");
    println!("{:#?}", hw);
}

 // 通过`concat()`方法将字符串数组拼接成一个字符串
 fn main() {
    let hw = ["hello", " ", "world!"].concat();
    println!("{:#?}", hw);
 }
 
 // 通过`join()`方法将字符串数组拼接成一个字符串
 fn main() {
    let hw_1 = ["hello", "world!"].join("");
    println!("{:#?}", hw_1);
	// 输出：
	// helloworld!
	
    // 使用`join()`方法在拼接字符串时添加或指定字符
    let hw_2 = ["hello", "world!"].join("+");
    println!("{:#?}", hw_2);
	// 输出：
	// hello+world!
 }
 
 // 使用`collect()`方式对数组中的字符串进行拼接
 fn main() {
    let hw = ["hello", " ", "world!"];
    let res: String = hw.iter().map(|x| *x).collect();
    println!("{:#?}", res);
 }
 
 // 使用符号`+`进行字符串拼接
 fn main() {
    let hw_1 = &(String::from("hello") + &String::from(" ") + &String::from("world!"));
    println!("{:#?}", hw_1);
    
    let hw_2 = &(String::from("hello") + " " + "world!");
    println!("{:#?}", hw_2);
    
    let hw_3 = &("hello".to_owned() + " " + "world!");
    println!("{:#?}", hw_3);

    let hw_4 = &("hello".to_string() + " " + "world!");
    println!("{:#?}", hw_4);
 }

G.STR.01 在实现Display特质时不应调用to_string()方法

【级别】 要求

【描述】

因为 to_string 是间接通过 Display 来实现的，如果实现 Display 的时候再使用 to_tring 的话，将会无限递归。

【反例】

#![allow(unused)]
fn main() {
use std::fmt;

struct Structure(i32);
impl fmt::Display for Structure {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "{}", self.to_string()) // 不符合
    }
}
}

【正例】

#![allow(unused)]
fn main() {
use std::fmt;

struct Structure(i32);
impl fmt::Display for Structure {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "{}", self.0) // 符合
    }
}
}

【Lint 检测】

G.STR.02 在追加字符串时使用push_str方法

【级别】 建议

【描述】

增强代码的可读性

【反例】

#![allow(unused)]
#![warn(clippy::string_add_assign, clippy::string_add)]

fn main() {
let mut x = "Hello".to_owned();
x = x + ", World"; // 不符合
}

【正例】

#![allow(unused)]
#![warn(clippy::string_add_assign, clippy::string_add)]

fn main() {
let mut x = "Hello".to_owned();

// More readable
x += ", World";
x.push_str(", World"); // 符合
}

【Lint 检测】

G.STR.03 将只包含 ASCII字符的字符串字面量转为字节序列可以直接使用b"str" 语法代替调用as_bytes方法

【级别】 建议

【描述】

这是为了增强可读性，让代码更简洁。

注意，"str".as_bytes() 并不等价于 b"str"，而是等价于 &b"str"[..] 。

【反例】

#![allow(unused)]
#![warn(clippy::string_lit_as_bytes)]
fn main() {
// 不符合
let bs = "a byte string".as_bytes();
}

【正例】

#![allow(unused)]
#![warn(clippy::string_lit_as_bytes)]
fn main() {
// 符合
let bs = b"a byte string";
}

【Lint 检测】

G.STR.04 需要辨别字符串的字符开头或结尾字符时，不应按字符迭代比较

【级别】 建议

【描述】

Rust 语言核心库和标准库都对字符串内置了一些方便的方法来处理这类需求。

迭代字符的性能虽然也很快（对500多个字符迭代转义处理大概需要4.5微秒左右），但这种场景用迭代的话，代码可读性更差一些。

【反例】

#![allow(unused)]
fn main() {
let name = "_";
// 不符合
name.chars().last() == Some('_') || name.chars().next_back() == Some('-');

let name = "foo";
// 不符合
if name.chars().next() == Some('_') {};
}

【正例】

#![allow(unused)]
fn main() {
let name = "_";
// 符合
name.ends_with('_') || name.ends_with('-');

let name = "foo";
// 符合
if name.starts_with('_') {};
}

【Lint 检测】

G.STR.05 对字符串按指定位置进行切片的时候需要小心破坏其 UTF-8 编码

【级别】 建议

【描述】

字符串默认是合法的 UTF-8字节序列，如果通过指定索引位置来对字符串进行切片，有可能破坏其合法 UTF-8 编码，除非这个位置是确定的，比如按 char_indices 方法来定位是合法的。

【反例】

#![warn(clippy::string_slice)]

fn main(){ 
    let s = "Ölkanne";
    // 不符合
    // 字节索引 1 不是字符的边界，所以程序会 panic 
    // `Ölkanne` 的 'Ö' 是 字节 `0..2`
    let sub_s = &s[1..];
    // println!("{:?}", sub_s);
}

【正例】

#![allow(clippy::string_slice)]

fn main(){
    let s = "Ölkanne";
    let mut char_indices = s.char_indices();
    assert_eq!(Some((0, 'Ö')), char_indices.next());
    // assert_eq!(Some((2, 'l')), char_indices.next()); 
    let pos = if let Some((pos, _)) = char_indices.next(){ pos } else {0};
    // 符合：计算出了正确的字符位置
    // 注意，这里 lint 检查工具可能误报，但这里是合法的，所以将lint设置为 allow
    let sub_s = &s[pos..];
    assert_eq!("lkanne", sub_s);
}

【Lint 检测】

3.8 集合类型

Rust 中的集合类型包括四大类：

• 线性序列： Vec, VecDeque, LinkedList
• 映射集：HashMap, BTreeMap
• 集合： HashSet, BTreeSet
• 其他： BinaryHeap

P.CLT.01 创建HashMap、VecDeque时，可以预先分配大约足够的容量来避免后续操作中产生多次分配

【描述】

预分配足够的容量，避免后续内存分配，可以提升代码性能。

【反例】

use std::collections::HashMap;
use std::collections::VecDeque;

fn main() {

    // 不符合
    let mut map = HashMap::new();
    map.insert("a", 1);
    map.insert("b", 2);
    map.insert("c", 3);
    println!("{:#?}", map);
    
    // 不符合
    let mut deque = VecDeque::new();
    deque.push_back(1);
    deque.push_back(2);
    deque.push_back(3);
    println!("{:#?}", deque);
}

【正例】

use std::collections::HashMap;
use std::collections::VecDeque;

fn main() {

    // 符合
    let mut map = HashMap::with_capacity(3);
    map.insert("a", 1);
    map.insert("b", 2);
    map.insert("c", 3);
    println!("{:#?}", map);
    
    // 符合
    let mut deque = VecDeque::with_capacity(3);
    deque.push_back(1);
    deque.push_back(2);
    deque.push_back(3);
    println!("{:#?}", deque);
}

G.CLT.01 非必要情况下，不要使用LinkedList，而用Vec或VecDeque代替

【级别】 建议

【描述】

一般情况下，有 Vec和VecDeque 性能更好。LinkedList 存在内存浪费，缓存局部性（Cache Locality）比较差，无法更好地利用CPU 缓存机制，性能很差。

只有在有大量的 列表 拆分 和 合并 操作时，才真正需要链表，因为链表允许你只需操作指针而非复制数据来完成这些操作。

【Lint 检测】

该 lint 对应 clippy.toml 配置项：

# 如果函数是被导出的 API，则该 lint 不会被触发，是防止 lint 建议对 API 有破坏性的改变。默认为 true
avoid-breaking-exported-api=true 

3.9 函数设计

创建函数或使用闭包时需要注意的地方。

P.FUD.01 传递到闭包的变量建议单独重新绑定

【描述】

默认情况下，闭包通过借用来捕获环境变量。或者，可以使用 move 关键字来移动环境变量到闭包中。

将这些要在闭包内用的变量，重新进行分组绑定，可读性更好。

【反例】

#![allow(unused)]
fn main() {
use std::rc::Rc;

let num1 = Rc::new(1);
let num2 = Rc::new(2);
let num3 = Rc::new(3);
let closure = {
    // `num1` 所有权已经转移
    let num2 = num2.clone();  
    let num3 = num3.as_ref(); 
    move || {
        *num1 + *num2 + *num3; // 不符合
    }
};
}

【正例】

#![allow(unused)]
fn main() {
use std::rc::Rc;

let num1 = Rc::new(1);
let num2 = Rc::new(2);
let num3 = Rc::new(3);
// 符合： 单独对要传递到闭包的变量重新绑定
let num2_cloned = num2.clone();
let num3_borrowed = num3.as_ref();
let closure = move || {
    *num1 + *num2_cloned + *num3_borrowed; // 符合
};
}

P.FUD.02 函数返回值不要使用 return

【描述】

Rust 中函数块会自动返回最后一个表达式的值，不需要显式地指定 return。

只有在函数过程中需要提前返回的时候再加 Return。

【反例】

#![allow(unused)]
fn main() {
fn foo(x: usize) -> usize {
    if x < 42{
        return x;
    }
    return x + 1; // 不符合
}
}

【正例】

#![allow(unused)]
fn main() {
fn foo(x: usize) -> usize {
    if x < 42{
        return x;
    }
    x + 1 // 符合
}
}

G.FUD.01 函数参数最长不要超过五个

【级别】 建议

【描述】

为了提升代码可读性，函数的参数最长不宜超过五个。

【反例】

#![allow(unused)]
fn main() {
struct Color;
// 不符合
fn foo(x: f32, y: f32, name: &str, c: Color, w: u32, h: u32, a: u32, b: u32) {
    // ..
}
}

【正例】

想办法把过长的参数缩短。

struct Color;
// 符合：此处使用 常量泛型（const generic） 来接收后面多个 u32 类型的参数
// 使用元组 缩短 2~3 个参数为一个参数
fn foo<T, const N: usize>(x: (f32, f32), name: &str, c: Color, last: [T; N]) {
    ;
}

fn main(){
    let arr = [1u32, 2u32];
    foo((1.0f32, 2.0f32), "hello", Color, arr);
    let arr = [1.0f32, 2.0f32, 3.0f32];
    foo((1.0f32, 2.0f32), "hello", Color, arr);
}

【Lint 检测】

该 lint 对应 clippy.toml 配置项：

# 函数参数最长不要超过5个
too-many-arguments-threshold=5

G.FUD.02 当函数参数实现了 Copy，并且是按值传入，如果值可能会太大，则宜考虑按引用传递

【级别】 建议

【描述】

通过值传递的参数可能会导致不必要的 memcpy 拷贝，这可能会造成性能损失。

【反例】

#![allow(unused)]
#![warn(clippy::large_types_passed_by_value)]

fn main() {
#[derive(Clone, Copy)]
struct TooLarge([u8; 2048]);

// 不符合
fn foo(v: TooLarge) {}
}

【正例】

#![allow(unused)]
#![warn(clippy::large_types_passed_by_value)]

fn main() {
#[derive(Clone, Copy)]
struct TooLarge([u8; 2048]);

// 符合
fn foo(v: &TooLarge) {}
}

【Lint 检测】

该 lint 对应 clippy.toml 配置项：

# 如果函数是被导出的 API，则该 lint 不会被触发，是防止 lint 建议对 API 有破坏性的改变。默认为 true
avoid-breaking-exported-api=true 

G.FUD.03 当函数参数出现太多 bool 类型的参数时，应该考虑将其封装为自定义的结构体或枚举

【级别】 建议

【描述】

布尔类型的参数过多，很难让人记住，容易出错。将其封装为枚举或结构体，可以更好地利用类型系统的检查而避免出错。 其他类型参数过多时，也可以考虑是否可以用自定义结构体或枚举进行封装。

【反例】

#![allow(unused)]
#![warn(clippy::fn_params_excessive_bools)]

fn main() {
// 不符合
fn f(is_round: bool, is_hot: bool) { ... }
}

【正例】

#![allow(unused)]
#![warn(clippy::fn_params_excessive_bools)]

fn main() {
enum Shape {
    Round,
    Spiky,
}

enum Temperature {
    Hot,
    IceCold,
}

// 符合
fn f(shape: Shape, temperature: Temperature) { ... }
}

【Lint 检测】

该 lint 对应 clippy.toml 配置项：

# 用于配置函数可以拥有的 bool 类型参数最大数量，默认为 3。
max-fn-params-bools=3 

G.FUD.04 当Copy 类型的足够小的值作为函数参数时，应该按值（by-value）传入，而不是引用(by-ref)

【级别】 建议

【描述】

在函数参数为 Copy 类型 且 其值足够小的时候，一般情况下，会避免传引用。因为对于这种小的值，性能上和按引用传递是一样快的，并且在代码更容易编写和可读。包括一些小的 结构体，也推荐按值传递，但要注意【例外】示例所示的情况。

【反例】

#![allow(unused)]
#![warn(clippy::trivially_copy_pass_by_ref)]
fn main() {
fn foo(v: &u32) {}
}

【正例】

#![allow(unused)]
#![warn(clippy::trivially_copy_pass_by_ref)]
fn main() {
fn foo(v: u32) {}
}

【例外】

需要注意这种情况下，lint 检查工具会误报。

#[derive(Clone, Copy)]
struct RawPoint {
    pub x: u8,
}

#[derive(Clone, Copy)]
struct Point {
    pub raw: RawPoint,
}

impl Point {
    pub fn raw(&self) -> *const RawPoint {
        &self.raw
    }
    // 如果听信 lint 的建议，将上面的 raw 函数参数 self 的引用去掉就是 raw_linted 函数, 这在没有编译优化的情况下（如只是 cargo build 运行在debug模式下）的时候不会出错，但在有编译优化的场景下（如 cargo build --release 运行在release模式）就会出现以下问题。
    pub fn raw_linted(self) -> *const RawPoint {
        &self.raw
    }
}

fn main() {
    let p = Point { raw: RawPoint { x: 10 } };

    // This passes
    assert_eq!(p.raw(), p.raw());
    // This fails 
    // 事实上，如果去掉那个 self 的引用，该函数的行为就变了
    // 因为 结构体 Point 是 Copy 的，每次调用 raw_linted 方法，结构体实例就会被复制一次，得到的结果就不一样了
    assert_eq!(p.raw_linted(), p.raw_linted());
}

【Lint 检测】

该 lint 对应 clippy.toml 配置项：

# 如果函数是被导出的 API，则该 lint 不会被触发，是防止 lint 建议对 API 有破坏性的改变。默认为 true
avoid-breaking-exported-api=true
# 考虑Copy按值而不是按引用传递的类型的最大大小（以字节为单位）。默认是None
trivial-copy-size-limit=None

注意，该 lint 没有考虑指针相关的情况，见例外示例。需要酌情考虑使用。例外示例来自 rust-clippy/issues/5953 。

G.FUD.05 不要总是为函数指定 inline(always)

【级别】 建议

【描述】

inline 虽然可以提升性能，但也会增加编译时间和编译大小。

Rust 中性能、编译时间和编译大小之间需要权衡。根据需要再 inline 即可。

【反例】

#![allow(unused)]
#![warn(clippy::inline_always)]

fn main() {
// 不符合
#[inline(always)]
fn not_quite_hot_code(..) { ... }
}

【例外】

根据需要再inline即可，比如明确知道某个函数被调用次数非常频繁，这个时候为了性能考虑要为其手工指定内联。

#![allow(unused)]
fn main() {
// 符合：实现内存回收功能，调用非常频繁。性能优先。
#[inline(always)]
pub fn buf_recycle(buf_id: usize) {
    // ...
}
}

【Lint 检测】

G.FUD.06 函数参数应该考虑兼容多种类型

【级别】 建议

【描述】

这样的好处是参数可以灵活兼容更多类型，代码方便扩展。

【反例】

// 不符合
fn three_vowels(word: &String) -> bool {
    let mut vowel_count = 0;
    for c in word.chars() {
        match c {
            'a' | 'e' | 'i' | 'o' | 'u' => {
                vowel_count += 1;
                if vowel_count >= 3 {
                    return true
                }
            }
            _ => volweld_count = 0
        }
    }
    false
}

fn main() {
    let sentence_string = "Once upon a time, there was a friendly curious crab named Ferris".to_string();
    for word in sentence_string.split(' ') {
        if three_vowels(word.to_string()) {
            println!("{} has three consecutive vowels!", word);
        }
    }
}

【正例】

// 符合：这里的参数可以接受 &String / &'str/ &'static str 三种类型参数
fn three_vowels(word: &str) -> bool {
    let mut vowel_count = 0;
    for c in word.chars() {
        match c {
            'a' | 'e' | 'i' | 'o' | 'u' => {
                vowel_count += 1;
                if vowel_count >= 3 {
                    return true
                }
            }
            _ => vowel_count = 0
        }
    }
    false
}

fn main() {
    let sentence_string =
        "Once upon a time, there was a friendly curious crab named Ferris".to_string();
    for word in sentence_string.split(' ') {
        if three_vowels(word) {
            println!("{} has three consecutive vowels!", word);
        }
    }
}

3.10 泛型

Rust 中的泛型允许开发人员编写更加简洁、更少重复的代码。但泛型可能会引起编译文件大小膨胀，酌情使用。

P.GEN.01 用泛型来抽象公共语义

【描述】

应该巧用泛型来抽象公共语义，消除重复代码。

【反例】

use std::ops::Add;

#[derive(Debug, Clone, Copy)]
struct Meter {
    value: f64
}

impl Meter {
    fn new(value: f64) -> Self {
        Self { value }
    }
}

impl Add for Meter {
    type Output = Meter;

    fn add(self, another: Meter) -> Self::Output {
        let value = self.value + another.value;
        Meter { value }
    }
}

#[derive(Debug, Clone, Copy)]
struct Kilogram {
    value: f64
}

impl Kilogram {
    fn new(value: f64) -> Self {
        Self { value }
    }
}

impl Add for Kilogram {
    type Output = Kilogram;

    fn add(self, another: Kilogram) -> Self::Output {
        let value = self.value + another.value;
        Kilogram { value }
    }
}
fn main() {
    // 不符合：如果要再新增新的单位，还需要实现很多重复代码
    let one_meter = Meter::new(1.0);
    let two_kilograms = Kilogram::new(2.0);
    
    let two_meters = one_meter + one_meter;
}

【正例】

use std::ops::Add;
use std::marker::PhantomData;

#[derive(Debug, Clone, Copy)]
struct Unit<T> {
    value: f64,
    unit_type: PhantomData<T>,
}

impl<T> Unit<T> {
    fn new(value: f64) -> Self {
        Self {
            value,
            unit_type: PhantomData,
        }
    }
}

impl<T> Add for Unit<T> {
    type Output = Unit<T>;

    fn add(self, another: Unit<T>) -> Self::Output {
        let new_value = self.value + another.value;
        Unit::new(new_value)
    }
}

#[derive(Debug, Clone, Copy)]
struct MeterType;

#[derive(Debug, Clone, Copy)]
struct KilogramType;

type Meter = Unit<MeterType>;
type Kilogram = Unit<KilogramType>;
fn main() {
    // 符合：如果要再新增新的单位，就方便很多了
    let one_meter = Meter::new(1.0);
    let two_kilograms = Kilogram::new(2.0);
    
    let two_meters = one_meter + one_meter;
}

P.GEN.02 不要随便使用 impl Trait 语法替代泛型限定

【描述】

impl Trait 语法 和 泛型限定，虽然都是静态分发，且效果类似，但是它们的语义是不同的。

在类型系统层面上的语义：

1. impl Trait 是 存在量化类型。意指，存在某一个被限定的类型。
2. 泛型限定 是 通用量化类型。意指，所有被限定的类型。

要根据它们的语义来选择不同的写法。

另外，impl Trait 可以用在函数参数位置和返回值位置，但是不同位置意义不同。

函数参数位置

等价于 泛型参数。

但要注意：

#![allow(unused)]
fn main() {
fn f(b1: impl Bar, b2: impl Bar) -> usize
}

等价于：

#![allow(unused)]
fn main() {
fn f<B1: Bar, B2: Bar>(b1: B1, b2: B2) -> usize
}

而不是

#![allow(unused)]
fn main() {
fn f<B: Bar>(b1: B, b2: B) -> usize
}

证明示例：

use std::fmt::Display;

// 函数参数可以传入 整数，但是函数返回值是 String
fn func(arg: impl Display) -> impl Display {
    format!("Hay! I am not the same as \"{}\"", arg)
}

// 很明显不等价于下面这类
// fn somefunc2<T: Display>(arg: T) -> T {
//     // 需要指定同一个类型 T 的行为
// }

fn main(){
    let a  = 42;
    let a = func(42);
}

函数返回值

在返回值位置上，如果是泛型参数，则是由调用者来选择具体类型，比如 parse::<i32>("32") ； 如果是 impl Trait，则是由被调用者来决定具体类型，但只能有一种类型。

在返回值位置上的 impl Trait 会根据函数体的返回值自动推断实现了哪些 auto trait。这意味着你不必在 impl Trait 后面再 加 Sync + Send 这种auto trait。

注意下面代码：

#![allow(unused)]
fn main() {
// Error： 这里只允许有同一种具体类型，Foo 和 Baz 都实现了 Bar 也是错的。
fn f(a: bool) -> impl Bar {
    if a {
        Foo { ... }
    } else {
        Baz { ... }
    }
}
}

P.GEN.03 不要使用太多泛型参数和 trait 限定，否则会增长编译时间

【描述】

为泛型函数添加详细的 trait 限定，可以在一定程度上增强用户使用体验，但使用过多的泛型参数和 trait 限定会显著地增长编译时间。

【反例】

此写法比正例的写法编译时间要多十倍。

#![allow(unused)]
fn main() {
    // From: https://github.com/tokio-rs/axum/pull/198
    fn handle_error<ReqBody, ResBody, F, Res, E>(
        self,
        f: F,
    ) -> HandleError<Self, F, ReqBody, HandleErrorFromRouter>
    where
        Self: Service<Request<ReqBody>, Response = Response<ResBody>>,
        F: FnOnce(Self::Error) -> Result<Res, E>,
        Res: IntoResponse,
        ResBody: http_body::Body<Data = Bytes> + Send + Sync + 'static,
        ResBody::Error: Into<BoxError> + Send + Sync + 'static,
    {
        HandleError::new(self, f)
    }
}

【正例】

来自于 Web 框架 Axum 的代码：

#![allow(unused)]
fn main() {
    // From: https://github.com/tokio-rs/axum/pull/198
    fn handle_error<ReqBody, F>(
        self,
        f: F,
    ) -> HandleError<Self, F, ReqBody, HandleErrorFromRouter> {
        HandleError::new(self, f)
    }   
}

P.GEN.04 为泛型类型实现方法时，impl 中声明的泛型类型参数一定要被用到

【描述】

在 impl 中被声明的类型参数，至少要满足下面三种形式：

1. impl<T> Foo<T>， T 出现在实现的Self 类型Foo<T> 中 。
2. impl<T> SomeTrait<T> for Foo ， T出现在要实现的 trait 中 。
3. impl<T, U> SomeTrait for T where T: AnotherTrait<AssocType=U> ， 出现在 T 的 trait 限定的关联类型中。

除此之外，都不算 T 被用到（出现在 Self 类型中）。

有这种限制，主要有两个原因：

1. 方便 Rust 类型推断。有这些限制才能明确能推断这些泛型参数的行为，避免产生错误。参考 RFC 0447 。
2. 避免语义定义不明确的情况。如果 impl 上存在自由的 泛型参数，则无法保证这一点。

【反例】

#![allow(unused)]
fn main() {
// case 1

struct Foo;

impl<T: Default> Foo {
    // error: the type parameter `T` is not constrained by the impl trait, self
    // type, or predicates [E0207]
    fn get(&self) -> T {
        <T as Default>::default()
    }
}

// case 2
trait Maker {
    type Item;
    fn make(&mut self) -> Self::Item;
}
struct Foo<T> {
    foo: T
}
struct FooMaker;
impl<T: Default> Maker for FooMaker {
// error: the type parameter `T` is not constrained by the impl trait, self
// type, or predicates [E0207]
    type Item = Foo<T>;

    fn make(&mut self) -> Foo<T> {
        Foo { foo: <T as Default>::default() }
    }
}

// error: the type parameter `A` is not constrained by the impl trait, self type, or predicates
trait Foo {}
impl<F, A> Foo for F where F: Fn(A) {} // error
}

【正例】

#![allow(unused)]
fn main() {
// case 1
struct Foo;

// Move the type parameter from the impl to the method
impl Foo {
    fn get<T: Default>(&self) -> T {
        <T as Default>::default()
    }
}

// case 2
use std::marker::PhantomData;

trait Maker {
    type Item;
    fn make(&mut self) -> Self::Item;
}

struct Foo<T> {
    foo: T
}

// Add a type parameter to `FooMaker`
struct FooMaker<T> {
    phantom: PhantomData<T>,
}

impl<T: Default> Maker for FooMaker<T> {
    type Item = Foo<T>;

    fn make(&mut self) -> Foo<T> {
        Foo {
            foo: <T as Default>::default(),
        }
    }
}

// closue : 相关 issue:  https://github.com/rust-lang/rust/issues/25041 
trait Foo {}
impl<F, A> Foo for F where F: Fn() -> A {} // 此处 A 是 闭包trait内的一个关联类型
}

P.GEN.05 定义泛型函数时，如果该函数实现用到来自 trait 定义的相关行为，需要为泛型指定相关 trait 的限定

【描述】

泛型，在 Rust 类型系统中的语义是一种 通用量化类型（Universally-quantified type），即，泛型类型 T 的所有可能 的单态类型。

在泛型函数内部，如果使用了来自某个 trait 定义的行为，则需要为泛型指定相关的 trait 限定，来排除其他没有实现该trait 的类型。

注：Rust编译器可以检测这种情况，但是编译错误比较晦涩，本原则用来提示开发者注意这种情况。

【反例】

#![allow(unused)]
fn main() {
use std::fmt;

// println! 中 `{:?}` 为 Debug triat 定义行为
fn some_func<T>(foo: T) {
    println!("{:?}", foo); // error[E0277]: `T` doesn't implement `Debug`
}
}

【正例】

use std::fmt;

// 为泛型类型 T 指派 Debug triat 限定
fn some_func<T: fmt::Debug>(foo: T) {
    println!("{:?}", foo); 
}

struct A;

fn main() {
   some_func(5i32);
   
   // A 没有实现 Debug trait，会被排除掉
   some_func(A); // error[E0277]: `A` doesn't implement `Debug`
}

G.GEN.01 不要在泛型位置上使用内建类型

【级别】 建议

【描述】

这样做虽然会导致编译错误，但是这种错误会使开发者感到困惑，反而无法找到问题所在。

【反例】

这里 u32 会被认为是一个类型参数。

#![allow(unused)]
fn main() {
// 不符合
impl<u32> Foo<u32> {
    fn impl_func(&self) -> u32 {
        42
    }
}
}

【正例】

#![allow(unused)]
fn main() {
// 符合
impl<T> Foo<T> {
    fn impl_func(&self) -> T {
        42
    }
}
}

【Lint 检测】

G.GEN.02 使用 Rust 标准库中某些方法，要注意避免使用其泛型默认实现，而应该使用具体类型的实现

【级别】 建议

【描述】

Rust 标准库内部某些类型使用了 泛型特化（未稳定特性），比如 ToString trait。

该 trait 有一个泛型默认实现， 并且一些具体类型也实现了它，比如 char/ str / u8/ i8 等。

在实际代码中，应该选择去调用具体类型实现的 to_string() 方法，而非调用泛型的默认实现。

这一规则要求开发者对 Rust 标准库的一些方法实现有一定了解。

【反例】

#![allow(unused)]
#![warn(clippy::inefficient_to_string)]

fn main() {
// 不符合
// 闭包参数中， s 为 `&&str` 类型
//  `&&str` 就会去调用泛型的默认实现
["foo", "bar"].iter().map(|s| s.to_string() );
}

【正例】

#![allow(unused)]
#![warn(clippy::inefficient_to_string)]

fn main() {
// 符合
// 闭包参数中， s 为 `&&str` 类型，使用 `|&s|` 对参数模式匹配后，闭包体内 `s` 就变成了 `&str` 类型
// 经过这样的转换，直接调用 `&str`的 `to_string()` 方法，而如果是 `&&str` 就会去调用泛型的默认实现。 
["foo", "bar"].iter().map(|&s| s.to_string() );
}

【Lint 检测】

3.11 特质

特质就是指 trait。在 Rust 中， trait 不是具体类型，而是一种抽象接口。但是通过 impl Trait 和 dyn Trait 也可以将 trait 作为类型使用。

P.TRA.01 使用 trait 时要注意 trait 一致性规则

【描述】

使用 trait 的时候，必须要满足 trait 一致性规则，即，孤儿规则（orphans rule）：类型和trait，必须有一个是在本地crate内定义的。 当不满足孤儿规则时，可以考虑使用NewType模式来解决问题。

【正例】

#![allow(unused)]
fn main() {
// String 和 FromStr都在标准库中被定义
// 如果想给String实现FromStr，则编译器会报错，告诉你这违反孤儿规则
// （虽然标准库内已经为string实现了FromStr,这里只是示例）
// 但是通过使用NewType，我们可以间接的达成目标
// 使用这种单个元素的元组结构体包装一个类型就叫NewType模式。
pub struct PhoneNumber(String);

use std::str::FromStr;
impl FromStr for PhoneNumber {
    type Err = Box<dyn std::error::Error>;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        Ok(PhoneNumber(s.to_string()))
    }
}
}

内置 trait

Rust 标准库内置了很多 trait，在使用这些 trait 的时候也需要注意。

列表

• P.TRA.BLN.01 在实现Borrow特质时，需要注意一致性
• G.TRA.BLN.01 应该具体类型的 default() 方法代替 Default::default() 调用
• G.TRA.BLN.02 不要为迭代器实现Copy特质
• G.TRA.BLN.03 能使用派生宏（Derive）自动实现Default特质就不要用手工实现
• G.TRA.BLN.04 在使用#[derive(Hash)]的时候，避免再手工实现PartialEq
• G.TRA.BLN.05 在使用#[derive(Ord)] 的时候，避免再手工实现 PartialOrd
• G.TRA.BLN.06 不要对实现 Copy 或引用类型调用 std::mem::drop 和 std::mem::forgot
• G.TRA.BLN.07 对实现 Copy 的可迭代类型来说，要通过迭代器拷贝其所有元素时，应该使用 copied方法，而非cloned
• G.TRA.BLN.08 实现 From 而不是 Into
• G.TRA.BLN.09 一般情况下不要给 Copy 类型手工实现 Clone
• G.TRA.BLN.10 不要随便使用Deref特质来模拟继承

P.TRA.BLN.01 在实现Borrow特质时，需要注意一致性

【描述】

当你想把不同类型的借用进行统一抽象，或者当你要建立一个数据结构，以同等方式处理自拥有值（ownered）和借用值（borrowed）时，例如散列（hash）和比较（compare）时，选择 Borrow。当把某个类型直接转换为引用，选择 AsRef 。

但是使用 Borrow 的时候，需要注意一致性问题。具体请看示例。

【反例】

#![allow(unused)]
fn main() {
// 这个结构体能不能作为 HashMap 的 key？
pub struct CaseInsensitiveString(String);

// 它实现 Eq 没有问题
impl  PartialEq for CaseInsensitiveString {
    fn eq(&self, other: &Self) -> bool {
       // 但这里比较是要求忽略了 ascii 大小写
        self.0.eq_ignore_ascii_case(&other.0)
    }
}

impl Eq for CaseInsensitiveString { }

// 实现 Hash 没有问题
// 但因为 eq 忽略大小写，那么 hash 计算也必须忽略大小写
impl Hash for CaseInsensitiveString {
    fn hash<H: Hasher>(&self, state: &mut H) {
        for c in self.0.as_bytes() {
            // 不符合：没有忽略大小写
            c.to_ascii_lowercase().hash(state)
        }
    }
}
}

这种情况下，就不能为 CaseInsensitiveString 实现 Borrow，并非编译不通过，而是在逻辑上不应该为其实现 Borrow，因为 CaseInsensitiveString 实现 Eq 和 Hash 的行为不一致，而 HashMap 则要求 Key 必须 Hash 和 Eq 的实现一致。这种不一致，编译器无法检查，所以在逻辑上，就不应该为其实现 Borrow。如果强行实现，那可能会出现逻辑 Bug。

G.TRA.BLN.01 应该具体类型的 default() 方法代替 Default::default() 调用

【级别】 建议

【描述】

为了增强可读性。

【反例】

#![allow(unused)]
#![warn(clippy::default_trait_access)]
fn main() {
// 不符合
let s: String = Default::default();
}

【正例】

#![allow(unused)]
#![warn(clippy::default_trait_access)]

fn main() {
// 符合
let s = String::default();
}

【Lint 检测】

G.TRA.BLN.02 不要为迭代器实现Copy 特质

【级别】 要求

【描述】

不要为迭代器实现 Copy 特质，因为一般会存在有改变状态的迭代器，如果实现 Copy，则可能会被意外隐式复制，违反 Rust 编译器可变借用独占原则，可能会导致一些意外行为。

所以，通常可以只为迭代器实现 Clone，需要复制的时候显式拷贝，如果出现问题也容易排查。

【反例】

#![warn(clippy::copy_iterator)]

use std::marker::PhantomData;

#[derive(Debug)]
struct ABC {
    a: [i32; 3],
    b: [i32; 3],
    c: [i32; 3],
}

impl ABC {
    fn iter_mut(&mut self) -> ABCIterMut {
        ABCIterMut {
            abc: self,
            index: 0,
            _phantom: PhantomData::default(),
        }
    }

}

// 不符合：这里为迭代器 ABCIterMut<'a>  实现 Copy 
#[derive(Copy, Clone)]
struct ABCIterMut<'a> {
    abc: *mut ABC,
    index: u8,
    _phantom: PhantomData<&'a mut ABC>,
}

impl<'a> Iterator for ABCIterMut<'a> {
    type Item = &'a mut [i32; 3];
    fn next(&mut self) -> Option<Self::Item> {

        let value = unsafe {
            match self.index {
                0 => &mut (*self.abc).a,
                1 => &mut (*self.abc).b,
                2 => &mut (*self.abc).c,
                _ => return None
            }
        };
        self.index += 1;
        Some(value)
    }
}

fn main(){
    let mut abc = ABC{a: [1; 3], b: [2;3], c: [3;3]};
    let mut abc_iter_mut = abc.iter_mut();


    // 因为实现 Copy，迭代器这里会隐式复制，返回结构体内部字段可变借用
    for i in abc_iter_mut {
        // Do Something
    }

    // 因为实现 Copy，迭代器这里会隐式复制，返回结构体内部字段可变借用
    // 存在意外风险而不容易被发现
    for i in abc_iter_mut {
        // Do Something
    }

}

另外，对于标准库里的 Range<T> 就不能实现 Copy，因为它也是一个迭代器。

细节可以参考来自官方讨论： https://github.com/rust-lang/rust/pull/27186#issuecomment-123390413

【正例】

#![warn(clippy::copy_iterator)]

use std::marker::PhantomData;

#[derive(Debug)]
struct ABC {
    a: [i32; 3],
    b: [i32; 3],
    c: [i32; 3],
}

impl ABC {
    fn iter_mut(&mut self) -> ABCIterMut {
        ABCIterMut {
            abc: self,
            index: 0,
            _phantom: PhantomData::default(),
        }
    }

}

// 符合：不实现 Copy
// 在需要的时候只实现 Clone
#[derive(Clone)]
struct ABCIterMut<'a> {
    abc: *mut ABC,
    index: u8,
    _phantom: PhantomData<&'a mut ABC>,
}

impl<'a> Iterator for ABCIterMut<'a> {
    type Item = &'a mut [i32; 3];
    fn next(&mut self) -> Option<Self::Item> {

        let value = unsafe {
            match self.index {
                0 => &mut (*self.abc).a,
                1 => &mut (*self.abc).b,
                2 => &mut (*self.abc).c,
                _ => return None
            }
        };
        self.index += 1;
        Some(value)
    }
}

fn main(){
    let mut abc = ABC{a: [1; 3], b: [2;3], c: [3;3]};
    let mut abc_iter_mut = abc.iter_mut();

    // 因为只实现了 Clone
    // 需要用多次迭代器的时候，显式调用 clone() 方法，
    // 开发者可以明确地知道自己在做什么
    for i in abc_iter_mut.clone() {
        println!("{i:?}");
    }

    for i in abc_iter_mut {
        println!("{i:?}")
    }

}

【Lint 检测】

G.TRA.BLN.03 能使用派生宏（Derive）自动实现Default特质就不要用手工实现

【级别】 建议

【描述】

手工实现 Default，代码不精炼。

【反例】

#![allow(unused)]
fn main() {
struct Foo {
    bar: bool
}
// 不符合
impl std::default::Default for Foo {
    fn default() -> Self {
        Self {
            bar: false
        }
    }
}
}

【正例】

#![allow(unused)]
fn main() {
// 符合
#[derive(Default)]
struct Foo {
    bar: bool
}
}

【Lint 检测】

该lint不能用于检测泛型参数类型的 Default 手工实现。

G.TRA.BLN.04 在使用#[derive(Hash)] 的时候，避免再手工实现 PartialEq

【级别】 要求

【描述】

实现 Hash 和 Eq 必须要满足下面一个等式：

k1 == k2  -> hash(k1) == hash(k2)

即，当k1 和 k2 相等时，hash(k1)也应该和 hash(k2) 相等。 所以要求 PartialEq / Eq / Hash 的实现必须保持一致。

如果用 #[derive(Hash)] 的时候，搭配了一个手工实现的 PartialEq 就很可能出现不一致的情况。

但也有例外。

【反例】

#![allow(unused)]
fn main() {
#[derive(Hash)]
struct Foo;
// 不符合
impl PartialEq for Foo {
    ...
}
}

【正例】

#![allow(unused)]
fn main() {
// 符合
#[derive(PartialEq, Eq, Hash)]
struct Foo;
}

【例外】

#![allow(unused)]
fn main() {
// From: https://docs.rs/crate/blsttc/3.3.0/source/src/lib.rs

// Clippy warns that it's dangerous to derive `PartialEq` and explicitly implement `Hash`, but the
// `pairing::bls12_381` types don't implement `Hash`, so we can't derive it.
#![allow(clippy::derive_hash_xor_eq)]
}

【Lint 检测】

G.TRA.BLN.05 在使用#[derive(Ord)] 的时候，避免再手工实现 PartialOrd

【级别】 要求

【描述】

跟实现 Hash 和 Eq 的要求类似，对于实现 Ord 的类型来说，必须要满足下面一个等式：

k1.cmp(&k2) == k1.partial_cmp(&k2).unwrap()

所以要求与 PartialOrd 的实现必须保持一致，并确保max、min和clamp与cmp一致。

通过#[derive(Ord)] 并手动实现PartialOrd，很容易意外地使cmp和partial_cmp不一致。

但也有例外。

【反例】

#![allow(unused)]
fn main() {
#[derive(Ord, PartialEq, Eq)]
struct Foo;
// 不符合
impl PartialOrd for Foo {
    ...
}
}

【正例】

#![allow(unused)]
fn main() {
// 符合
#[derive(Ord, PartialOrd, PartialEq, Eq)]
struct Foo;

// 符合
#[derive(PartialEq, Eq)]
struct Foo;

impl PartialOrd for Foo {
    fn partial_cmp(&self, other: &Foo) -> Option<Ordering> {
       Some(self.cmp(other))
    }
}

impl Ord for Foo {
    ...
}

}

【例外】

使用 #[derive(PartialOrd)] 自动实现 PartialOrd，然后再手工实现 Ord的时候在内部调用自动实现的partial_cmp ，应该是满足 k1.cmp(&k2) == k1.partial_cmp(&k2).unwrap() 了。

#![allow(unused)]
fn main() {
// From: https://docs.rs/crate/adventjson/0.1.1/source/src/lib.rs
#[derive(Clone, Debug, PartialEq, PartialOrd)]
pub enum JsonObject
{
    /// An array of objects (e.g.: \[1,2,3\])
    Array(Vec<Self>),
    /// Key-value pairs (e.g.: {\"first\": 10, \"other\": 15})
    Obj(Vec<(String, Self)>),
    /// A number (e.g.: -0.08333)
    Number(f64),
    /// A string (e.g.: \"Test: \\\"\")
    JsonStr(String),
    /// A boolean (e.g. true)
    Bool(bool),
    /// The null-value
    Null,
}

/// Save because no not-number values are allowed in json
impl Eq for JsonObject {}

/// Save because no not-number values are allowed in json
#[allow(clippy::derive_ord_xor_partial_ord)]
impl Ord for JsonObject
{
    fn cmp(&self, other: &Self) -> Ordering
    {
        self.partial_cmp(other).unwrap()
    }
}
}

【Lint 检测】

G.TRA.BLN.06 不要对实现 Copy 或引用类型调用 std::mem::drop 和 std::mem::forgot

【级别】 要求

【描述】

std::mem::drop 函数只是利用 Rust 所有权的一个技巧，对于 实现了 Copy 的类型 或引用，是无效的。如果使用它，对导致代码可读方便产生误导作用。

另外std::mem::drop 也无法 Drop 掉 ManuallyDrop 类型。

std::mem::forgot 同理。

但是也存在例外的情况。

【反例】

#![allow(unused)]
fn main() {
// 不符合
let x: i32 = 42; // i32 implements Copy
std::mem::drop(x) // A copy of x is passed to the function, leaving the
                  // original unaffected
}

【例外】

在某些情况下，虽然不会有实际效果，但是为了提升语义，也可以使用。

下面代码中，为了防止自引用的问题，使用 drop(self) ，提升了代码语义，但实际并不会 drop。

#![allow(unused)]
fn main() {
// From: https://docs.rs/crate/dhall/0.10.1/source/src/error/builder.rs

#[allow(clippy::drop_ref)]
pub fn format(&mut self) -> String {
    if self.consumed {
        panic!("tried to format the same ErrorBuilder twice")
    }
    let this = std::mem::take(self);
    self.consumed = true;
    drop(self); // 显式 drop self，避免后面误用它
    // ...
}
}

【Lint 检测】

G.TRA.BLN.07 对实现 Copy 的可迭代类型来说，要通过迭代器拷贝其所有元素时，应该使用 copied方法，而非cloned

【级别】 建议

【描述】

copied 方法在语义层面，是针对实现 Copy 的类型，所以应该使用 copied 来增加代码可读性。

【反例】

#![allow(unused)]
#![warn(clippy::cloned_instead_of_copied)]

fn main() {
let a = [1, 2, 3];
// 不符合
let v_copied: Vec<_> = a.iter().cloned().collect();
}

【正例】

#![allow(unused)]
#![warn(clippy::cloned_instead_of_copied)]
fn main() {
let a = [1, 2, 3];
// 符合
let v_copied: Vec<_> = a.iter().copied().collect();
}

【Lint 检测】

G.TRA.BLN.08 实现 From 而不是 Into

【级别】 建议

【描述】

优先为类型实现 From 而非 Into。因为实现了 From，Into 也会被自动实现。并且在错误处理的时候，? 操作符会通过调用 From 实现自动进行错误类型转换。

但是在泛型限定上，优先 Into 。

当然，也存在例外。

【反例】

#![allow(unused)]
fn main() {
struct StringWrapper(String);
// 不符合
impl Into<StringWrapper> for String {
    fn into(self) -> StringWrapper {
        StringWrapper(self)
    }
}
}

【正例】

#![allow(unused)]
fn main() {
struct StringWrapper(String);
// 符合
impl From<String> for StringWrapper {
    fn from(s: String) -> StringWrapper {
        StringWrapper(s)
    }
}
}

【例外】

有两类情况，可以直接实现 Into。

1. Into 不提供 From 实现。在一些场景中，From 自动实现的 Into 并不符合转换需求。
2. 使用 Into 来跳过孤儿规则。

#![allow(unused)]
fn main() {
// 第一种情况。 
// From： https://github.com/apache/arrow-datafusion/blob/master/ballista/rust/core/src/serde/scheduler/from_proto.rs
#[allow(clippy::from_over_into)]
impl Into<PartitionStats> for protobuf::PartitionStats {
    fn into(self) -> PartitionStats {
        PartitionStats::new(
            foo(self.num_rows),
            foo(self.num_batches),
            foo(self.num_bytes),
        )
    }
}

// From： https://github.com/apache/arrow-datafusion/blob/master/ballista/rust/core/src/serde/scheduler/to_proto.rs
#[allow(clippy::from_over_into)]
impl Into<protobuf::PartitionStats> for PartitionStats {
    fn into(self) -> protobuf::PartitionStats {
        let none_value = -1_i64;
        protobuf::PartitionStats {
            num_rows: self.num_rows.map(|n| n as i64).unwrap_or(none_value),
            num_batches: self.num_batches.map(|n| n as i64).unwrap_or(none_value),
            num_bytes: self.num_bytes.map(|n| n as i64).unwrap_or(none_value),
            column_stats: vec![],
        }
    }
}

// 第二种情况
// 根据孤儿规则，trait 和 类型必须有一个在本地定义，所以不能为 Vec<T> 实现 From trait
struct Wrapper<T>(Vec<T>);
impl<T> From<Wrapper<T>> for Vec<T> {
    fn from(w: Wrapper<T>) -> Vec<T> {
        w.0
    }
}
// 但是通过 Into<Vec<T>> ，就可以绕过这个规则
struct Wrapper<T>(Vec<T>);
impl<T> Into<Vec<T>> for Wrapper<T> {
    fn into(self) -> Vec<T> {
        self.0
    }
}
}

【Lint 检测】

G.TRA.BLN.09 一般情况下不要给 Copy 类型手工实现 Clone

【级别】 建议

【描述】

手工为 Copy 类型实现 Clone ，并不能改变 Copy 类型的行为。除非你显式地去调用 clone()方法。

【反例】

#![allow(unused)]
#![warn(clippy::expl_impl_clone_on_copy)]

fn main() {
#[derive(Copy)]
struct Foo;
// 不符合
impl Clone for Foo {
    // ..
}
}

【正例】

#![allow(unused)]
#![warn(clippy::expl_impl_clone_on_copy)]

fn main() {
// 符合
#[derive(Copy, Clone)]
struct Foo;
}

【例外】

在有些情况下，需要手动实现 Copy 和 Clone 。 相关 issues : https://github.com/rust-lang/rust/issues/26925

use std::marker::PhantomData;

struct Marker<A>(PhantomData<A>);

// 如果使用 Derive 自动实现的话，会要求 Marker<A> 里的 A 也必须实现 Clone
// 这里通过手工给 Marker<A> 实现 Copy 和 Clone 可以避免这种限制
impl<A> Copy for Marker<A> {}
impl<A> Clone for Marker<A> {
    fn clone(&self) -> Self {
        *self
    }
}

// 不需要给 NoClone 实现 Clone
struct NoClone;
fn main() {
    let m: Marker<NoClone> = Marker(PhantomData);
    let m2 = m.clone();
}

【Lint 检测】

G.TRA.BLN.10 不要随便使用Deref特质来模拟继承

【级别】 建议

【描述】

Deref trait是专门用于实现自定义指针类型而存在的。虽然可以实现 Deref 来达到某种类似于继承的行为，但 Rust 中不推荐这样做。

这是因为 Rust 语言推崇显式的转换，而 Deref 则是 Rust 中为数不多的隐式行为。如果 Deref 被滥用，那么程序中隐式行为可能会增多，隐式的转换是 Bug 的温床。

【反例】 不要像下面这样用Deref来模拟继承。

use std::ops::Deref;

struct Foo {}

impl Foo {
    fn m(&self) {
        // ...
    }
}

struct Bar {
    f: Foo
}

impl Deref for Bar {
    type Target = Foo;

    fn deref(&self) -> &Foo {
        &self.f
    }
}

fn main() {
    let bar = Bar { f: Foo {} };
    bar.m();
}

trait 对象

trait 对象需要注意 动态安全 （dyn safe），也叫对象安全 （object safe），但官方现在倾向于 动态安全这个术语。

列表

• P.TRA.OBJ.01 根据场景合理选择使用trait对象或泛型静态分发
• P.TRA.OBJ.02 除非必要，避免自定义虚表

P.TRA.OBJ.01 根据场景合理选择使用trait对象或泛型静态分发

【描述】

trait对象存在一定运行时开销，除非必要，不要滥用，但triat对象也可以避免编译文件大小膨胀。

在性能有严格要求的情况下，可以考虑Enum或泛型静态分发代替。

【正例】

使用 Enum 代替 trait 对象。 示例来自于 enum_dispatch

trait KnobControl {
    fn set_position(&mut self, value: f64);
    fn get_value(&self) -> f64;
}

struct LinearKnob {
    position: f64,
}

struct LogarithmicKnob {
    position: f64,
}

impl KnobControl for LinearKnob {
    fn set_position(&mut self, value: f64) {
        self.position = value;
    }

    fn get_value(&self) -> f64 {
        self.position
    }
}

impl KnobControl for LogarithmicKnob {
    fn set_position(&mut self, value: f64) {
        self.position = value;
    }

    fn get_value(&self) -> f64 {
        (self.position + 1.).log2()
    }
}

fn main() {
    // 这里使用 trait 对象
    let v: Vec<Box<dyn KnobControl>> = vec![
        //set the knobs
    ];

    //use the knobs
}

用 Enum 代替：

#![allow(unused)]
fn main() {
enum Knob {
    Linear(LinearKnob),
    Logarithmic(LogarithmicKnob),
}

impl KnobControl for Knob {
    fn set_position(&mut self, value: f64) {
        match self {
            Knob::Linear(inner_knob) => inner_knob.set_position(value),
            Knob::Logarithmic(inner_knob) => inner_knob.set_position(value),
        }
    }

    fn get_value(&self) -> f64 {
        match self {
            Knob::Linear(inner_knob) => inner_knob.get_value(),
            Knob::Logarithmic(inner_knob) => inner_knob.get_value(),
        }
    }
}
}

性能有显著提高，但是牺牲了维护成本。可以借助于宏来自动生成相关代码，参见： enum_dispatch

P.TRA.OBJ.02 除非必要，避免自定义虚表

【描述】

trait 对象 dyn Trait 隐藏了复杂而又为危险的虚表实现，为我们提供了简单而又安全的动态分发。手动实现虚表的代码中充斥着大量的 unsafe，稍有不慎，就会引入 bug 。如无必要，不要自定义虚表。

如果你的设计不能使用标准的 dyn Trait 结构来表达，那么你首先应该尝试重构你的程序，并参考以下理由来决定是否使用自定义的虚表。

• 你想要为一类指针对象实现多态，并且无法忍受多级指针解引用造成的性能开销，参考 RawWaker 与 Bytes。
• 你想要自定义内存布局，比如像 C++ 中虚表一样紧凑的内存结构（虚表指针位于对象内），参考 RawTask。
• 你的 crate 需要在 no_std 环境中使用动态分发，参考 RawWaker 。
• 或者，标准的 trait object 确实无法实现你的需求。

【正例】

来自标准库中 RawWaker 的定义。

#![allow(unused)]

fn main() {
pub struct RawWaker {
    /// A data pointer, which can be used to store arbitrary data as required
    /// by the executor. This could be e.g. a type-erased pointer to an `Arc`
    /// that is associated with the task.
    /// The value of this field gets passed to all functions that are part of
    /// the vtable as the first parameter.
    data: *const (),
    /// Virtual function pointer table that customizes the behavior of this waker.
    vtable: &'static RawWakerVTable,
}
#[derive(PartialEq, Copy, Clone, Debug)]
pub struct RawWakerVTable {
    /// This function will be called when the [`RawWaker`] gets cloned, e.g. when
    /// the [`Waker`] in which the [`RawWaker`] is stored gets cloned.
    ///
    /// The implementation of this function must retain all resources that are
    /// required for this additional instance of a [`RawWaker`] and associated
    /// task. Calling `wake` on the resulting [`RawWaker`] should result in a wakeup
    /// of the same task that would have been awoken by the original [`RawWaker`].
    clone: unsafe fn(*const ()) -> RawWaker,

    /// This function will be called when `wake` is called on the [`Waker`].
    /// It must wake up the task associated with this [`RawWaker`].
    ///
    /// The implementation of this function must make sure to release any
    /// resources that are associated with this instance of a [`RawWaker`] and
    /// associated task.
    wake: unsafe fn(*const ()),

    /// This function will be called when `wake_by_ref` is called on the [`Waker`].
    /// It must wake up the task associated with this [`RawWaker`].
    ///
    /// This function is similar to `wake`, but must not consume the provided data
    /// pointer.
    wake_by_ref: unsafe fn(*const ()),

    /// This function gets called when a [`RawWaker`] gets dropped.
    ///
    /// The implementation of this function must make sure to release any
    /// resources that are associated with this instance of a [`RawWaker`] and
    /// associated task.
    drop: unsafe fn(*const ()),
}
}

来自 Bytes 的示例。

#![allow(unused)]
fn main() {
pub struct Bytes {
    ptr: *const u8,
    len: usize,
    // inlined "trait object"
    data: AtomicPtr<()>,
    vtable: &'static Vtable,
}

pub(crate) struct Vtable {
    /// fn(data, ptr, len)
    pub clone: unsafe fn(&AtomicPtr<()>, *const u8, usize) -> Bytes,
    /// fn(data, ptr, len)
    pub drop: unsafe fn(&mut AtomicPtr<()>, *const u8, usize),
}
}

3.12 错误处理

Rust 为了保证系统健壮性，将系统中出现的非正常情况划分为三大类：

1. 失败
2. 错误
3. 异常

Rust 语言针对这三类非正常情况分别提供了专门的处理方式，让开发者可以分情况去选择。

• 对于失败的情况，可以使用断言工具。
• 对于错误，Rust 提供了基于返回值的分层错误处理方式，比如 Option 可以用来处理可能存在空值的情况，而 Result 就专门用来处理可以被合理解决并需要传播的错误。
• 对于异常，Rust 将其看作无法被合理解决的问题，提供了线程恐慌机制，在发生异常的时候，线程可以安全地退出。

P.ERR.01 当传入函数的参数值因为超出某种限制可能会导致函数调用失败，应该使用断言

【描述】

当传入函数的某个参数值可能因为超出某种限制，比如超出数组长度的索引、字符串是否包含某个字符、数组是否为空等，应该使用断言。

【正例】

#![allow(unused)]
fn main() {
// From: std::vec::Vec::swap_remove
#[stable(feature = "rust1", since = "1.0.0")]
pub fn swap_remove(&mut self, index: usize) -> T {
    #[cold]
    #[inline(never)]
    fn assert_failed(index: usize, len: usize) -> ! {
        panic!("swap_remove index (is {}) should be < len (is {})", index, len);
    }

    let len = self.len();
   
    if index >= len {
        // 此处使用断言方法，虽然不是标准库内置断言宏，但也是一种断言
        assert_failed(index, len);
    }
    unsafe {
        let last = ptr::read(self.as_ptr().add(len - 1));
        let hole = self.as_mut_ptr().add(index);
        self.set_len(len - 1);
        ptr::replace(hole, last)
    }
}
}

P.ERR.02 在确定 Option<T> 和 Result<T, E>类型的值不可能是 None 或 Err 时，请用 expect 代替 unwrap()

【描述】

当需要处理的 Option<T> 和 Result<T, E> 类型的值，永远都不可能是 None 或 Err 时，虽然直接 unwrap() 也是可以的，但使用 expect 会有更加明确的语义。

expect 的语义：

我不打算处理 None 或 Err 这种可能性，因为我知道这种可能性永远不会发生，或者，它不应该发生。但是 类型系统并不知道它永远不会发生。所以，我需要像类型系统保证，如果它确实发生了，它可以认为是一种错误，并且程序应该崩溃，并带着可以用于跟踪和修复该错误的栈跟踪信息。

所以在指定 expect 输出消息的时候，请使用肯定的描述，而非否定，用于提升可读性。

【反例】

// 这个配置文件默认会跟随源码出现，所以，必定可以读取到
// 这个配置文件不应该没有被提供，如果万一出现了没有提供的情况，需要 Panic ，但这里并没有提供错误信息，对于调试或使用都没有帮助
let config = Config::read("some_config.toml").unwrap();

// or
// expect 的输出描述使用否定式内容，可读性不好
let config = Config::read("some_config.toml").expect("No configuration file provided"); 

// or

fn main() {
    use std::net::IpAddr;
    let _home: IpAddr = "127.0.0.1".parse().unwrap();
}

// or
// expect 的输出描述使用否定式内容，可读性不好
fn main() {
    use std::net::IpAddr;
    let _home: IpAddr = "127.0.0.1".parse().expect("IP addr parse failed!");
}

【正例】

// 这个配置文件默认会跟随源码出现，所以，必定可以读取到
// 这个配置文件不应该没有被提供，如果万一出现了没有提供的情况，需要 Panic 并提供错误信息方便调试，或者让使用者知道原因
// expect 里输出的描述信息，使用肯定的内容，整体代码可读性更高，更能突出 expect 的语义
let config = Config::read("some_config.toml").expect("Provide the correct configuration file"); 

// or

fn main() {
    use std::net::IpAddr;
    let _home: IpAddr = "127.0.0.1".parse().expect("Provide the correct Ip addr");
}

G.ERR.01 在处理 Option<T> 和 Result<T, E> 类型时，不要随便使用 unwrap

【级别】 建议

【描述】

当 Option<T> 和 Result<T, E>类型的值分别是 None 或 Err 时，直接对其 unwrap() 会导致程序恐慌！

【反例】

#![allow(unused)]
#![warn(clippy::unwrap_used)]

fn main() {
fn select(opt: Option<String>) {
    opt.unwrap();  // 不符合
}
// OR
fn select(opt: Result<String, ()>) {
    res.unwrap();  // 不符合
}
}

【正例】

#![allow(unused)]
#![warn(clippy::unwrap_used)]

fn main() {
fn select(opt: Option<String>) {
    opt.expect("more helpful message");  // 符合：可以用 expect 方法来处理 None 的情况
}
// OR
fn select(opt: Result<String, ()>) {
    res.expect("more helpful message");  // 符合：可以用 expect 方法来处理 Err 的情况
}
}

【Lint 检测】

G.ERR.02 不要滥用 expect，请考虑用 unwrap_or_ 系列方法代替

【级别】 建议

【描述】

使用 expect 的时候请遵循 expect 的语义，不要滥用。

expect 的语义：

我不打算处理 None 或 Err 这种可能性，因为我知道这种可能性永远不会发生，或者，它不应该发生。但是 类型系统并不知道它永远不会发生。所以，我需要像类型系统保证，如果它确实发生了，它可以认为是一种错误，并且程序应该崩溃，并带着可以用于跟踪和修复该错误的栈跟踪信息。

但是对于一些存在“副作用”的函数，在 遇到 None 或 Err 时，可能需要返回一些指定的值。这个时候用 expect 就不太符合语义。

如果你的用法完全符合 expect 语义，那么可以设置 #![allow(clippy::expect_fun_call]

【反例】

#![warn(clippy::expect_used)]
fn main(){
    let foo = Some(String::new());
    let err_code = "418";
    let err_msg = "I'm a teapot";
    // 不符合：因为要返回指定的错误码等信息，不适合 expect 语义
    foo.expect(&format!("Err {}: {}", err_code, err_msg)); 
}

【正例】

#![warn(clippy::expect_used)]
fn main(){
    let foo = Some(String::new());
    let err_code = "418";
    let err_msg = "I'm a teapot";
    // 符合
    foo.unwrap_or_else(|| panic!("Err {}: {}", err_code, err_msg));  // 你可以根据场景选择性使用 panic! 或者 不 panic!
}

【例外】

完全符合 expect 语义的使用。

#![allow(unused)]
#![allow(clippy::expect_fun_call]

fn main() {
// 这个配置文件默认会跟随源码出现，所以，必定可以读取到
// 这个配置文件不应该没有被提供，如果万一出现了没有提供的情况，需要 Panic 并提供错误信息方便调试，或者让使用者知道原因
let config = Config::read("some_config.toml").expect("Provide the correct configuration file"); 


// 或者

use std::net::IpAddr;
let _home: IpAddr = "127.0.0.1".parse().expect("Provide the correct Ip addr");

}

【Lint 检测】

3.13 内存管理

生命周期

生命周期（lifetime），也被叫做 生存期。可以理解为引用的有效范围。

列表

• P.MEM.LFT.01 生命周期参数命名尽量有意义且简洁
• P.MEM.LFT.02 通常需要显式地标注生命周期，而非利用编译器推断

P.MEM.LFT.01 生命周期参数命名尽量有意义且简洁

【描述】

生命周期参数的命名应该尽量简单，可以使用表达一定语义的缩写。

因为生命周期参数的目的是给编译器使用，用于防止函数中出现悬垂引用。

适当简单的携带语义的缩写，可以最小化对业务代码的干扰。并且在生命周期参数较多的情况下，清晰地表达具体哪个引用属于哪个生命周期。

【反例】

#![allow(unused)]
fn main() {
struct ConstraintGeneration<'a, 'b, 'c> {
    infcx: &'c InferCtxt<'b, 'c>,
    all_facts: &'a mut Option<AllFacts>,
    location_table: &'a LocationTable,
    liveness_constraints: &'a mut LivenessValues<RegionVid>,
    borrow_set: &'a BorrowSet<'c>,
    body: &'c Body<'c>,
}
}

【正例】

#![allow(unused)]
fn main() {
// 增加 'cg 意义的文档注释
/// 'cg = the duration of the constraint generation process itself.
struct ConstraintGeneration<'cg, 'cx, 'tcx> {
    infcx: &'cg InferCtxt<'cx, 'tcx>,
    all_facts: &'cg mut Option<AllFacts>,
    location_table: &'cg LocationTable,
    liveness_constraints: &'cg mut LivenessValues<RegionVid>,
    borrow_set: &'cg BorrowSet<'tcx>,
    body: &'cg Body<'tcx>,
}
}

P.MEM.Lifetime.02 通常需要显式地标注生命周期，而非利用编译器推断

【描述】

编译器对生命周期参数有两种单态化方式（生命周期参数也是一种泛型）：

• Early bound。一般情况下，'a: 'b 以及 impl<'a> 这种方式是 early bound，意味着这些生命周期参数会在当前作用域单态化生命周期实例。
• Late bound。默认的 'a 或 for<'a> 是在实际调用它们的地方才单态化生命周期实例。

在不同的场景下需要指定合适的单态化方式，才能让编译器明白开发者的意图。

在使用匿名生命周期 '_ 的时候需要注意，如果有多个匿名生命周期，比如 ('_，'_) ，每个匿名生命周期都会有自己的单独实例。

【反例】

fn main() {
    let v = vec![1, 2, 3, 4, 5, 6];
    let mut buf = Buffer::new(&v);
    // error[E0499]: cannot borrow `buf` as mutable more than once at a time
    let b1 = buf.read_bytes();
    let b2 = buf.read_bytes();
    println!("{:#?} {:#?}", b1, b2);
}

struct Buffer<'a> {
    buf: &'a [u8],
    pos: usize,
}

impl<'a> Buffer<'a> {
    fn new(b: &'_ [u8]) -> Buffer {
        Buffer { buf: b, pos: 0 }
    }
    // 不符合：此处依赖编译器推断的生命周期将导致main函数中该方法调用编译错误
    fn read_bytes(&'_ mut self) -> &'_ [u8] {
        self.pos += 3;
        &self.buf[self.pos - 3..self.pos]
    }
}

【正例】

fn main() {
    let v = vec![1, 2, 3, 4, 5, 6];
    let mut buf = Buffer::new(&v);
    let b1 = buf.read_bytes();
    let b2 = buf.read_bytes();
    println!("{:#?} {:#?}", b1, b2);
}

struct Buffer<'a> {
    buf: &'a [u8],
    pos: usize,
}

// 符合：明确标示清楚生命周期，向编译器传达开发者意图，则可正常编译
impl<'b, 'a: 'b> Buffer<'a> {
    fn new(b: &'_ [u8]) -> Buffer {
        Buffer { buf: b, pos: 0 }
    }
    // 符合：明确标示清楚输入引用和输出引用的生命周期关系是 `'a: 'b`
    fn read_bytes(&'b mut self) -> &'a [u8] {
        self.pos += 3;
        &self.buf[self.pos - 3..self.pos]
    }
}

智能指针

智能指针，在 Rust 中参与自动管理堆内容、引用计数、抽象指针语义等功能。一般实现了 Deref trait 或 Drop trait 的类型都可以看作是一种智能指针。

Box<T> 就是一个典型的智能指针，但是因为其在 Rust 中有特殊地位，所以为其单独罗列规则。

Rust 中常见的智能指针包括：

• 自动管理堆内存：Box<T>
• 引用计数：Rc<T> / Arc<T>
• 内部可变性容器：Cell<T> / RefCell<T>

列表

• P.MEM.SPT.01 使用 RefCell<T> 时宜使用 try_borrow/try_borrow_mut 方法

P.MEM.SPT.01 使用 RefCell<T> 时宜使用 try_borrow/try_borrow_mut 方法

【描述】

Rust 的 RefCell<T> 在运行时会对通过 borrow/borrow_mut 方法借用出去的不可变借用和可变借用进行检查。如果发现违反了借用规则的情况，则会 Panic。

所以在一些多线程场景下，开发者可能对细粒度的操作加了锁同步，但是没有对 RefCell<T> 进行加锁，此时宜用 try_borrow/try_borrow_mut 来代替 borrow/borrow_mut，以避免在运行时因为违反借用检查规则而出现 Panic。

【反例】

#![allow(unused)]
fn main() {
// 不符合
// 以下两个函数会让 C 函数在多线程下调用
// 运行过程中有一定几率会出现 Panic
pub extern "C" fn nic_udrv_suspend() {
    NIC_ENTITY.borrow_mut().suspend(); // suspend()需要可变引用
}

pub extern "C" fn nic_udrv_buf_recycle(buf_id: usize) {
    NIC_ENTITY.borrow().buf_recycle(buf_id); // buf_recycle()内有锁可以避免多线程竞争
}
}

【正例】

#![allow(unused)]
fn main() {
// 符合
// 以下两个函数会让 C 函数在多线程下调用
// 使用 try_borrow 或 try_borrow_mut 可以避免运行过程中出现 Panic
pub extern "C" fn nic_udrv_suspend() {
    if let Ok(entity) = NIC_ENTITY.try_borrow_mut() {
        entity.suspend(); // suspend()需要可变引用
    }
}

pub extern "C" fn nic_udrv_buf_recycle(buf_id: usize) {
    if let Ok(entity) = NIC_ENTITY.try_borrow() {
        entity.buf_recycle(buf_id); // buf_recycle()内有锁可以避免多线程竞争
    }
}
}

Box 类型

Rust 中分配堆内存必须要使用的类型，类型签名为 Box<T>。

列表

• G.MEM.BOX.01 一般情况下，不应直接对 Box<T> 进行借用
• G.MEM.BOX.02 一般情况下，不应直接对已经在堆上分配内存的类型进行 Box 装箱
• G.MEM.BOX.03 一般情况下，不应直接对栈分配类型进行 Box 装箱

G.MEM.BOX.01 一般情况下，不应直接对 Box<T> 进行借用

【级别】 建议

【描述】

借用 Box<T> 等同于直接借用 T，而 &T 要比 &Box<T> 更常用。

【反例】

#![allow(unused)]
fn main() {
// 不符合
fn foo(bar: &Box<T>) { ... }
}

【正例】

#![allow(unused)]
fn main() {
// 符合
fn foo(bar: &T) { ... }
}

【Lint 检测】

G.MEM.BOX.02 一般情况下，不应直接对已经在堆上分配内存的类型进行 Box 装箱

【级别】 建议

【描述】

像 Vec<T> / String 这样的类型（数据集）已经在堆上分配了内存，就没有必要再使用 Box 对其进行装箱操作。当然也存在例外情况。

【反例】

#![allow(unused)]
fn main() {
struct X {
    // 不符合：Vec已在堆上分配了内存
    values: Box<Vec<Foo>>,
}
}

【正例】

#![allow(unused)]
fn main() {
struct X {
    // 符合
    values: Vec<Foo>,
}
}

【例外】

用例来源：jex

#![allow(unused)]
fn main() {
#[derive(Debug)]
pub struct JQ {
    ptr: *mut jq_state,
    // We want to make sure the vec pointer doesn't move, so we can keep pushing to it.
    // 这里不想把 Vec 的指针 Move 掉，所以用 Box 装箱可以达到这个效果
    // 注：clippy::box_vec 以更名为 clippy::box_collection
    #[allow(clippy::box_vec)]
    errors: Box<Vec<JVRaw>>,
}
}

或以下情况。来源 mmtk-core

#![allow(unused)]
fn main() {
#[repr(C)]
pub struct MutatorConfig<VM: VMBinding> {
    // ...

    /// Mapping between allocator selector and spaces. Each pair represents a mapping.
    /// Put this behind a box, so it is a pointer-sized field.
    // 这里是为了让字段拥有指针一样的大小，所以装箱了
    #[allow(clippy::box_collection)]
    pub space_mapping: Box<SpaceMapping<VM>>,
  
    // ...
}
}

【Lint 检测】

G.MEM.BOX.03 一般情况下，不应直接对栈分配类型进行 Box 装箱

【级别】 建议

【描述】

此举会对性能造成不必要的影响。只有当某个栈变量太大，需要使用堆分配的情况下，或是栈变量需要逃逸的时候，才需要考虑是否对其使用 Box 装箱。

【反例】

#![allow(unused)]
fn main() {
fn foo(bar: usize) {}
// 不符合
let x = Box::new(1);
foo(*x);
println!("{}", *x);
}

【正例】

#![allow(unused)]
fn main() {
fn foo(bar: usize) {}
// 符合
let x = 1;
foo(x);
println!("{}", x);
}

【例外】

用例来源：aitch

#![allow(unused)]
fn main() {
pub trait ServeFunc {
    fn call_box(self: Box<Self>) -> Result<()>;
}

impl<F> ServeFunc for F
where
    F: FnOnce() -> Result<()>,
{
    // 特殊情况，F 是泛型，且要匹配 trait定义
    #[cfg_attr(feature = "cargo-clippy", allow(boxed_local))]
    fn call_box(self: Box<Self>) -> Result<()> {
        (*self)()
    }
}
}

【Lint 检测】

Drop 析构

在 Safe Rust 中，Drop 比较安全。在 Unsafe Rust 中则需要注意更多关于 Drop 的问题。

列表

• G.MEM.DRP.01 要注意防范内存泄漏

P.MEM.DRP.01 要注意防范内存泄漏

【描述】

Rust 语言并不保证避免内存泄漏，内存泄漏不属于 Rust 安全职责范围。使用 Rust 的时候需要注意下面情况可能会发生内存泄漏：

1. 循环引用导致没有正常调用析构函数
2. 使用 forget / leak 等函数主动跳过析构
3. 使用 std::mem::ManuallyDrop 构建数据结构而忘记析构
4. 析构函数内部发生了 panic
5. 程序中止（abort on panic）

3.14 模块

Rust 中一个文件 即一个模块，也可以通过 mod 来创建模块。多个文件放到同一个目录下，也可以成为一个模块。

模块相关有三个概念：

1. mod是 Rust 代码的“骨架”。
2. use 则是用来决定使用或导出哪个模块中的具体的类型或方法。
3. Path，则是一个命名系统，类似于命名空间。

P.MOD.01 合理控制对外接口和模块之间的可见性

【描述】

Rust提供强大的模块（module）系统，并且可以管理这些模块之间的可见性（公有（public）或私有（private））。

1、对于提供给其他crate使用的对外函数、结构体、trait等类型需要严格控制对外pub的范围，避免将内部成员对外提供。

2、对于crate内部，mod之间可见的类型，需要添加上pub(crate) 。

3、对于mod内部私有的类型，不要添加pub(crate) 或者pub。

【正例】

#![allow(unused)]
fn main() {
// lib.rs
pub mod sha512;
pub use sha512::Sha512;

// sha512.rs
pub struct Sha512 {
    inner: Sha512Inner, // inner作为内部结构体，不添加pub描述
}

}

P.MOD.02 将模块的测试移动到单独的文件，有助于增加编译速度

【描述】

将模块的测试代码 移到一个单独的文件中，并且用 `#[cfg(test)] 来条件编译 tests 的mod，这样可以减少rebuild和编译时间，在大型项目中很重要。

【正例】

#![allow(unused)]
fn main() {
src/
|--codes.rs
|--codes/test.rs
}

G.MOD.01 使用导入模块中的类型或函数，在某些情况下需要带模块名前缀

【级别】 建议

【描述】

对于标准库中，很多人都熟知的类型 ，比如 Arc/ Rc/ Cell/ HashMap 等 ， 可以导入它们直接使用。

但是对于可能引起困惑的函数，比如 std::ptr::replace 和 std::mem::replace ，在使用它们的时候，就必须得带上模块前缀。

使用一些第三方库中定义的类型或函数，也建议带上crate或模块前缀。如果太长的话，可以考虑使用 as 或 type 来定义别名。

以上考虑都是为了增强代码的可读性、可维护性。

【正例】

#![allow(unused)]
fn main() {
use std::sync::Arc;
let foo = Arc::new(vec![1.0, 2.0, 3.0]); // 直接使用 Arc
let a = foo.clone();

// 需要带上 ptr 前缀
use std::ptr;
let mut rust = vec!['b', 'u', 's', 't'];
// `mem::replace` would have the same effect without requiring the unsafe
// block.
let b = unsafe {
    // 符合
    ptr::replace(&mut rust[0], 'r')
};
}

G.MOD.02 如果是作为库供别人使用，在 lib.rs中重新导出对外类型、函数和 trait 等

【级别】 建议

【描述】

这样使用方在使用的时候，就不需要use crate::mod::mod::struct，可以直接使用use crate::struct，好处是使用方use的时候会比较方便和直观。

【正例】

#![allow(unused)]
fn main() {
// 符合
// From syn crate
pub use crate::data::{
    Field, Fields, FieldsNamed, FieldsUnnamed, Variant, VisCrate, VisPublic, VisRestricted,
    Visibility,
};
}

G.MOD.03 导入模块不要随便使用 通配符*

【级别】 建议

【描述】

使用通配符导入会污染命名空间，比如导入相同命名的函数或类型。

【反例】

#![allow(unused)]
#![warn(clippy::wildcard_imports)]
fn main() {
use crate2::*; // Has a function named foo
foo(); // Calls crate1::foo
}

【正例】

#![allow(unused)]
#![warn(clippy::wildcard_imports)]
fn main() {
use crate1::foo; // Imports a function named foo
foo(); // Calls crate1::foo
}

【例外】

#![allow(unused)]
fn main() {
use prelude::*;

#[test]
use super::*
}

【Lint 检测】

该 lint 可以通过 clippy 配置项 warn-on-all-wildcard-imports = false 来配置，用于是否禁用 prelude/ super (测试模块中) 使用通配符导入， 默认是 false。

G.MOD.04 一个项目中应该避免使用不同的模块布局风格

【级别】 建议

【描述】

Rust 支持两种 模块布局，文件夹内使用 mod.rs 或者是使用跟文件夹同名的文件名，来组织模块。

但是项目里如果混合这两种模块布局，是比较让人困惑的，最好统一为同一种风格。

上面两种 lint ，选择其中一种用于检查是否存在不同的模块布局。

【反例】

#![allow(unused)]
#![warn(clippy::self_named_module_files, clippy::mod_module_files)]

fn main() {
// 不符合：使用 `self_named_module_files`，不允许下面模块布局
#![warn(clippy::self_named_module_files)]
src/
  stuff/
    stuff_files.rs
  stuff.rs
  lib.rs

// 不符合：使用 `mod_module_files`，不允许下面模块布局
#![warn(clippy::mod_module_files)]
src/
  stuff/
    stuff_files.rs
    mod.rs
  lib.rs
}

【正例】

#![allow(unused)]
fn main() {
// 符合：使用 `self_named_module_files`，允许下面模块布局
#![warn(clippy::self_named_module_files)]
src/
  stuff/
    stuff_files.rs
    mod.rs
  lib.rs

// 符合：使用 `mod_module_files`，允许下面模块布局
#![warn(clippy::mod_module_files)]
src/
  stuff/
    stuff_files.rs
  stuff.rs
  lib.rs
}

【Lint 检测】

G.MOD.05 不要在私有模块中设置其内部类型或函数方法为 pub(crate)

【级别】 建议

【描述】

如果在私有模块中设置 pub(crate) 可能会让使用者产生误解。建议用 pub 代替。

【反例】

#![allow(unused)]
fn main() {
mod internal {
    // 不符合
    pub(crate) fn internal_fn() { }
}
}

【正例】

#![allow(unused)]
fn main() {
// 符合
mod internal {
    // 此函数在模块外部不可见，可以使用 pub 或 继续保持私有
    pub fn internal_fn() { }
}
}

【Lint 检测】

3.15 包管理

Cargo 不仅仅是包管理，它还是一个 Workflow 工具。这一节包含 Cargo 和 Crate 相关内容。

P.CAR.01 应该尽量把项目划分为合理的 crate 组合

【描述】

将整个项目按一定逻辑划分为合理的 crate，在工程方面有利于组件化。并且 crate 是 Rust 的编译单元，也有助于提升编译速度。

但需要注意，crate 之间的依赖关系应该是单向的，避免相互依赖的情况。

但 Rust 中编译时间、性能、编译大小之间，在考虑优化的时候也是需要权衡的。

内联是优化的关键，当编译单元越大，内联优化效果就越好。所以需要权衡 crate 划分的粒度。

P.CAR.02 不要滥用 Features

【描述】

Rust 的 features 提供了方便的条件编译功能。从软件工程来说，features 适合应用于可选功能。

在使用 features 的时候，应该考虑到底是不是真的需要 features。

滥用 features 会带来额外的测试和静态检查的难度，需要保证不同 features 下的测试覆盖和静态检查情况。

P.CAR.03 使用 cargo features 来代替 --cfg 条件编译参数

【描述】

cargo features 为 Rust 原生的条件编译，可用于代替 --cfg 参数且兼容性更好。

P.CAR.04 宜使用 cfg! 来代替 #[cfg]

【描述】

cfg! 和正常代码一样，会检查全部函数逻辑，而 #[cfg] 是条件编译，则会跳过一些 Dead Code。

G.CAR.01 当项目是可执行程序而非库时，建议使用 src/main.rs 和 src/lib.rs 模式

【级别】 建议

【描述】

crate 结构类似于：

src/
  -- lib.rs
  -- main.rs

或

src/
  -- lib.rs
bin/
  -- main.rs

这样的好处有：

1. 便于单元测试。
2. 有利于面向接口思考，让代码架构和逻辑更加清晰。

若编写的可执行程序比较复杂，在 main.rs 里需要依赖太多东西时，那就需要创建 Workspace 把 main.rs 独立为一个 crate，而在这个 crate 内也没有必要再拆分为 main 和 lib 了。

G.CAR.02 Crate 的 Cargo.toml 中应该包含必要的元信息

【级别】 建议

【描述】

在 Cargo.toml 中应该包含必要的元信息，以便使用者知道它的作用。 此外，若要将 crate 发布到 crates.io 上的话，这些信息也是必须的。可参考 The Cargo Book 中的相关介绍。

【反例】

# 不符合：此 `Cargo.toml` 缺失介绍(description)项。无法发布到 crates.io。
[package]
name = "clippy"
version = "0.0.212"
repository = "https://github.com/rust-lang/rust-clippy"
readme = "README.md"
license = "MIT OR Apache-2.0"
keywords = ["clippy", "lint", "plugin"]
categories = ["development-tools", "development-tools::cargo-plugins"]

【正例】

# 符合：此 `Cargo.toml` 包含必要元信息。
[package]
name = "clippy"
version = "0.0.212"
description = "A bunch of helpful lints to avoid common pitfalls in Rust"
repository = "https://github.com/rust-lang/rust-clippy"
readme = "README.md"
license = "MIT OR Apache-2.0"
keywords = ["clippy", "lint", "plugin"]
categories = ["development-tools", "development-tools::cargo-plugins"]

【Lint 检测】

G.CAR.03 Feature 命名应该避免否定式或多余的前后缀

【级别】 建议

【描述】

Feature 命名应该避免出现 no- 或 not- 之类的否定前缀，或诸如 use-，with- 前缀或 -support后缀。Feature 的目的是正向的，可选的特性，使用否定式命名和它的目的背道而驰。

【反例】

[features]
default = ["no-abc", "with-def", "ghi-support"]
no-abc = []         # 不符合：命名否定式
with-def = []       # 不符合：多余前缀
ghi-support = []    # 不符合：多余后缀

【正例】

# 符合
[features]
default = ["abc", "def", "ghi"]
abc = []
def = []
ghi = []

【Lint 检测】

G.CAR.04 Cargo.toml 中依赖包版本不应使用通配符

【级别】 要求

【描述】

依赖的包必须指定具体的语义版本。关于语义版本说明参见：The Cargo Book: SemVer Compatibility。

使用 Clippy 需要设置 #[warn(clippy::wildcard_dependencies)]。

【反例】

[dependencies]
regex = "*" # 不符合：避免项目依赖因为上游更新而自动更新

【正例】

[dependencies]
regex = "1.5" # 符合

【Lint 检测】