3.1 Newtype 模式 on 编程那些事儿

3.1.1 语义混淆

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

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/idiomatic/leveraging-the-type-system/newtype-pattern/semantic-confusion.html

3.1.1 语义混淆

当函数接受多个同类型参数时，调用处含义不清：

 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
# struct LoginError;
fn login(username: &str, password: &str) -> Result<(), LoginError> {
 // [...]
 # Ok(())
}

fn main() {
 let password = "password";
 let username = "username";

 // 在代码库的另一处，我们误把参数对调了。
 // 最好情况是 bug，最坏情况是安全漏洞
 login(password, username);
}

Newtype 模式可以在编译期防止这类错误：

3.1.2 强制不变量

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

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/idiomatic/leveraging-the-type-system/newtype-pattern/parse-don-t-validate.html

3.1.2 强制不变量

可以利用 newtype 模式强制不变量（invariants）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
pub struct Username(String);

impl Username {
 pub fn new(username: String) -> Result<Self, InvalidUsername> {
 if username.is_empty() {
 return Err(InvalidUsername::CannotBeEmpty)
 }
 if username.len() > 32 {
 return Err(InvalidUsername::TooLong { len: username.len() })
 }
 Ok(Self(username))
 }

 pub fn as_str(&self) -> &str {
 &self.0
 }
}
# pub enum InvalidUsername {
# CannotBeEmpty,
# TooLong { len: usize },
# }

Newtype 模式结合 Rust 的模块与可见性系统，可以保证某类型的实例满足一组不变量。

3.1.3 真的封装了吗？

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

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/idiomatic/leveraging-the-type-system/newtype-pattern/is-it-encapsulated.html

3.1.3 真的封装了吗？

你必须评估 newtype 暴露的整个 API 面，才能判断不变量是否真的牢不可破。必须考虑所有可能的交互，包括可能让用户绕过校验的 trait 实现。