2.2.1 命名约定 on 编程那些事儿

2.2.1.1 New

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/idiomatic/foundations-api-design/predictable-api/naming-conventions/new.html

2.2.1.1 New

Rust 没有 new 关键字，new 反而是常见的前缀或整个方法名。

1
2
3
4
5
6
7
8
9


// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
impl<T> Vec<T> {
 fn new() -> Vec<T>;
}

impl<T> Box<T> {
 fn new(T) -> Box<T>;
}

Rust 没有用于初始化新值的 new 关键字，只有你调用的函数或直接填充的值。

2.2.1.2 Is

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/idiomatic/foundations-api-design/predictable-api/naming-conventions/is.html

2.2.1.2 Is

检查数据类型上的某个条件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
impl<T> Vec<T> {
 fn is_empty(&self) -> bool;
}

impl f32 {
 fn is_nan(self) -> bool;
}

impl u32 {
 fn is_power_of_two(self) -> bool;
}

对某个值的布尔条件。

2.2.1.3 Mut

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/idiomatic/foundations-api-design/predictable-api/naming-conventions/mut.html

2.2.1.3 Mut

访问式方法的后缀。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
impl<T> Vec<T> {
 fn get(&self, index: usize) -> Option<&T>;
 fn get_mut(&mut self, index: usize) -> Option<&mut T>;
}

impl<T> [T] {
 fn iter(&self) -> impl Iterator<Item = &T>;
 fn iter_mut(&mut self) -> impl Iterator<Item = &mut T>;
}

表示该方法提供对可变引用访问的后缀。

2.2.1.4 With：构造函数

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/idiomatic/foundations-api-design/predictable-api/naming-conventions/with-constructor.html

2.2.1.4 With：构造函数

作为构造函数的 with，在其余使用默认值的同时设置类型的某一个值。

with 意为“带有特定设置的 <Type>”。

2.2.1.5 With：复制并修改

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/idiomatic/foundations-api-design/predictable-api/naming-conventions/with-copy-setter.html

2.2.1.5 With：复制并修改

当值被复制，同时又以特定方式被修改时，会出现 with。

with 意为“像 <value>，但有某处不同。”

2.2.1.6 With：闭包

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/idiomatic/foundations-api-design/predictable-api/naming-conventions/with-closure.html

2.2.1.6 With：闭包

with 意为“做 X，但用这种特定方式计算。”

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
impl<T> Vec<T> {
 // 简化。若 resize 大于当前 vec 大小，用闭包填充元素。
 pub fn resize_with(&mut self, new_len: usize, f: impl FnMut() -> T);
}

mod iter {
 // 用闭包创建无限、惰性迭代器。
 pub fn repeat_with<A, F: FnMut() -> A>(repeater: F) -> RepeatWith<F>;
}

with 可作为后缀出现，表示可用某个特定函数或闭包，代替计算的“合理默认”。

2.2.1.7 Try

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/idiomatic/foundations-api-design/predictable-api/naming-conventions/try.html

2.2.1.7 Try

返回 Result 的可失败方法的前缀。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
impl TryFrom<i32> for u32 {
 type Error = TryFromIntError;

 fn try_from(value: i32) -> Result<i64, TryFromIntError>;
}

impl<T> Receiver<T> {
 fn try_recv(&self) -> Result<T, TryRecvError>;
}

可能失败并返回 Result 的方法前缀。

2.2.1.8 From

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/idiomatic/foundations-api-design/predictable-api/naming-conventions/from.html

2.2.1.8 From

构造函数，强烈暗示“类型转换”。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
impl Duration {
 fn from_days(days: u64) -> Duration;
}

impl i32 {
 fn from_ascii(src: &[u8]) -> Result<i32, ParseIntError>;
}

impl u32 {
 fn from_le_bytes(bytes: [u8; 4]) -> u32;
}

构造风格、类似 From trait 的函数前缀。

2.2.1.9 Into

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/idiomatic/foundations-api-design/predictable-api/naming-conventions/into.html

2.2.1.9 Into

把 self 转换为另一类型的方法前缀。消费 self，返回拥有所有权的值。

1
2
3
4
5
6
7
8
9


// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
pub trait IntoIterator {
 fn into_iter(self) -> Self::IntoIter;
}

impl str {
 fn into_string(self: Box<str>) -> String;
}

消费拥有所有权的值并将其变换为另一类型值的函数前缀。

2.2.1.10 To

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/idiomatic/foundations-api-design/predictable-api/naming-conventions/to.html

2.2.1.10 To

接受借用值并创建拥有所有权值的函数前缀。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
impl str {
 fn to_owned(&self) -> String;

 fn to_uppercase(&self) -> String;
}

impl u32 {
 // 接受拥有所有权的 self，因为 `u32` 实现了 `Copy`
 fn to_be(self) -> u32;
}

在不消费 self 的情况下创建新的拥有所有权值、并暗示类型转换的方法，以 to 开头命名。

2.2.1.11 As 与 Ref

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/idiomatic/foundations-api-design/predictable-api/naming-conventions/as-and-ref.html

2.2.1.11 As 与 Ref

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
impl<T> Rc<T> {
 // 在容器类型上非常常见，注意 Option 上也有。
 fn as_ref(&self) -> &T;

 fn as_ptr(&self) -> *const T;
}

impl<T> Option<T> {
 fn as_ref(&self) -> Option<&T>;

 fn as_slice(&self) -> &[T];
}

返回对所含主要数据一块的借用的方法。

2.2.1.12 By

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/idiomatic/foundations-api-design/predictable-api/naming-conventions/by.html

2.2.1.12 By

接受自定义投影或比较函数的方法组成部分。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
impl<T> [T] {
 fn sort(&mut self) where T: Ord;

 fn sort_by(&mut self, compare: impl FnMut(&T, &T) -> Ordering);

 fn sort_by_key<K, F>(&mut self, f: F)
 where
 F: FnMut(&T) -> K,
 K: Ord;
}

sort_by 接受自定义比较器函数，取代正常的 Ord 比较逻辑。

2.2.1.13 练习

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/idiomatic/foundations-api-design/predictable-api/naming-conventions/exercise.html

2.2.1.13 练习

这些名字暗示它们做什么？
这些签名该如何命名？

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
// 这些方法的类型是什么？
Option::is_some // ?
slice::get // ?
slice::get_unchecked_mut // ?
Option::as_ref // ?
str::from_utf8_unchecked_mut // ?
Rc::get_mut // ?
Vec::dedup_by_key // ?

// 具有这些类型的方法该叫什么？
fn ____(String) -> Self;
fn ____(&self) -> Option<&InnerType>; // InnerType 的细节无关紧要。
fn ____(self, String) -> Self;
fn ____(&mut self) -> Option<&mut InnerType>;

与学员一起过一遍示例中的方法，讨论函数的类型应当是什么。