3.6 令牌类型 on 编程那些事儿

3.6.1 权限令牌

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

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/idiomatic/leveraging-the-type-system/token-types/permission-tokens.html

3.6.1 权限令牌

令牌类型很适合作为已检查权限的证明。

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


// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
mod admin {
 pub struct AdminToken(());

 pub fn get_admin(password: &str) -> Option<AdminToken> {
 if password == "Password123" { Some(AdminToken(())) } else { None }
 }
}

// 我们不必检查是否有权限，因为
// AdminToken 参数等价于这样一次检查。
pub fn add_moderator(_: &admin::AdminToken, user: &str) {}

fn main() {
 if let Some(token) = admin::get_admin("Password123") {
 add_moderator(&token, "CoolUser");
 } else {
 eprintln!("Incorrect password! Could not prove privileges.")
 }
}

本例展示用密码获取聊天客户端管理员权限，并在获得权限后授予用户版主等级的建模。AdminToken 类型充当「正确用户权限的证明」。

3.6.2 带数据的令牌类型：Mutex Guard

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

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/idiomatic/leveraging-the-type-system/token-types/mutex-guard.html

3.6.2 带数据的令牌类型：Mutex Guard

有时，令牌类型需要附加数据。Mutex guard 是代表「权限 + 数据」的令牌示例。

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


// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
use std::sync::{Arc, Mutex, MutexGuard};

fn main() {
 let mutex = Arc::new(Mutex::new(42));
 let try_mutex_guard: Result<MutexGuard<'_, _>, _> = mutex.lock();
 if let Ok(mut guarded) = try_mutex_guard {
 // 取得的 MutexGuard 是独占访问的证明。
 *guarded = 451;
 }
}

互斥锁强制对值的读/写访问互斥。我们在本课程前面已介绍过互斥锁（参见：RAII/Mutex），但这里我们专门看 MutexGuard。

3.6.3 Branded 之一：变量专用令牌

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

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/idiomatic/leveraging-the-type-system/token-types/branded-01-motivation.html

3.6.3 Branded 之一：变量专用令牌

若想把令牌绑定到特定变量，该怎么办？

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


// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
struct Bytes {
 bytes: Vec<u8>,
}
struct ProvenIndex(usize);

impl Bytes {
 fn get_index(&self, ix: usize) -> Option<ProvenIndex> {
 if ix < self.bytes.len() { Some(ProvenIndex(ix)) } else { None }
 }
 fn get_proven(&self, token: &ProvenIndex) -> u8 {
 unsafe { *self.bytes.get_unchecked(token.0) }
 }
}

fn main() {
 let data_1 = Bytes { bytes: vec![0, 1, 2] };
 if let Some(token_1) = data_1.get_index(2) {
 data_1.get_proven(&token_1); // 没问题！

 // let data_2 = Bytes { bytes: vec![0, 1] };
 // data_2.get_proven(&token_1); // 会 panic！我们能防止吗？
 }
}

若想把令牌绑定到代码中的特定变量，该怎么办？我们能在 Rust 的类型系统中做到吗？

3.6.4 Branded 之二：`PhantomData` 与生命周期子类型

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

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/idiomatic/leveraging-the-type-system/token-types/branded-02-phantomdata.html

3.6.4 Branded 之二：`PhantomData` 与生命周期子类型

思路：

用生命周期作为每个令牌的唯一品牌。
让生命周期足够不同，使它们不会隐式相互转换。

 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
use std::marker::PhantomData;

#[derive(Default)]
struct InvariantLifetime<'id>(PhantomData<&'id ()>); // 主要关注点

struct Wrapper<'a> { value: u8, invariant: InvariantLifetime<'a> }

fn lifetime_separator<T>(value: u8, f: impl for<'a> FnOnce(Wrapper<'a>) -> T) -> T {
 f(Wrapper { value, invariant: InvariantLifetime::default() })
}

fn try_coerce_lifetimes<'a>(left: Wrapper<'a>, right: Wrapper<'a>) {}

fn main() {
 lifetime_separator(1, |wrapped_1| {
 lifetime_separator(2, |wrapped_2| {
 // 我们希望这不要编译
 try_coerce_lifetimes(wrapped_1, wrapped_2);
 });
 });
}

在 Rust 中，生命周期之间可以有子类型关系。

3.6.5 Branded 之三：实现

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

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/idiomatic/leveraging-the-type-system/token-types/branded-03-impl.html

3.6.5 Branded 之三：实现

构造 branded 类型与构造非 branded 类型不同。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
# use std::marker::PhantomData;
#
# #[derive(Default)]
# struct InvariantLifetime<'id>(PhantomData<*mut &'id ()>);
struct ProvenIndex<'id>(usize, InvariantLifetime<'id>);

struct Bytes<'id>(Vec<u8>, InvariantLifetime<'id>);

impl<'id> Bytes<'id> {
 fn new<T>(
 // 我们想在此上下文中修改的数据。
 bytes: Vec<u8>,
 // 唯一地为 `Bytes` 的生命周期打品牌的函数
 f: impl for<'a> FnOnce(Bytes<'a>) -> T,
 ) -> T {
 f(Bytes(bytes, InvariantLifetime::default()),)
 }

 fn get_index(&self, ix: usize) -> Option<ProvenIndex<'id>> {
 if ix < self.0.len() { Some(ProvenIndex(ix, InvariantLifetime::default())) }
 else { None }
 }

 fn get_proven(&self, ix: &ProvenIndex<'id>) -> u8 {
 debug_assert!(ix.0 < self.0.len());
 unsafe { *self.0.get_unchecked(ix.0) }
 }
}

动机：我们想为某类型拥有「已证明的索引」，且不希望这些索引能被同类型的不同变量使用。我们也不希望这些索引逃出作用域。

3.6.6 Branded 之四：Branded 类型实战

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

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/idiomatic/leveraging-the-type-system/token-types/branded-04-in-action.html

3.6.6 Branded 之四：Branded 类型实战

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46


// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
use std::marker::PhantomData;

#[derive(Default)]
struct InvariantLifetime<'id>(PhantomData<*mut &'id ()>);
struct ProvenIndex<'id>(usize, InvariantLifetime<'id>);

struct Bytes<'id>(Vec<u8>, InvariantLifetime<'id>);

impl<'id> Bytes<'id> {
 fn new<T>(
 // 我们想在此上下文中修改的数据。
 bytes: Vec<u8>,
 // 唯一地为 `Bytes` 的生命周期打品牌的函数
 f: impl for<'a> FnOnce(Bytes<'a>) -> T,
 ) -> T {
 f(Bytes(bytes, InvariantLifetime::default()))
 }

 fn get_index(&self, ix: usize) -> Option<ProvenIndex<'id>> {
 if ix < self.0.len() {
 Some(ProvenIndex(ix, InvariantLifetime::default()))
 } else {
 None
 }
 }

 fn get_proven(&self, ix: &ProvenIndex<'id>) -> u8 {
 self.0[ix.0]
 }
}

fn main() {
 let result = Bytes::new(vec![4, 5, 1], |mut bytes_1| {
 Bytes::new(vec![4, 2], |mut bytes_2| {
 let index_1 = bytes_1.get_index(2).unwrap();
 let index_2 = bytes_2.get_index(1).unwrap();
 bytes_1.get_proven(&index_1);
 bytes_2.get_proven(&index_2);
 // bytes_2.get_proven(&index_1); // ❌🔨
 "Computations done!"
 })
 });
 println!("{result}");
}

实现现已就绪，我们可以编写这样一个程序：作为已存在索引之证明的令牌类型不能在变量之间共享。

3.6 令牌类型 on 编程那些事儿

3.6.1 权限令牌

3.6.1 权限令牌

3.6.2 带数据的令牌类型：Mutex Guard

3.6.2 带数据的令牌类型：Mutex Guard

3.6.3 Branded 之一：变量专用令牌

3.6.3 Branded 之一：变量专用令牌

3.6.4 Branded 之二：`PhantomData` 与生命周期子类型

3.6.4 Branded 之二：PhantomData 与生命周期子类型

3.6.5 Branded 之三：实现

3.6.5 Branded 之三：实现

3.6.6 Branded 之四：Branded 类型实战

3.6.6 Branded 之四：Branded 类型实战

3.6.4 Branded 之二：`PhantomData` 与生命周期子类型