fastrand可复现随机数教程:如何只用一行seed()让每次运行都生成相同结果
fastrand可复现随机数教程:如何只用一行seed()让每次运行都生成相同结果
fastrand 是一款简单快速的 Rust 随机数生成器(A simple and fast random number generator),基于 WyRand 算法实现。它的核心卖点是"一行 fastrand::seed(7) 就能锁定随机序列"——只要固定 seed(种子),之后每次运行程序生成的随机数都完全一致,这正是"可复现随机数"的全部秘密。本教程面向新手,带你从原理到实战,快速掌握 fastrand 的可复现随机数用法。
为什么需要可复现随机数?
随机数最大的痛点是"出问题没法复现"。以下场景都依赖可复现随机数:
| 场景 | 说明 |
|---|---|
| 🐛 调试 Bug | 某次运行随机数据触发了崩溃,用相同种子可 100% 重现现场 |
| ✅ 单元测试 | 测试里断言随机结果的稳定性,CI 每次跑结果一致 |
| 🎮 游戏 / 模拟 | 回放对局、复现地图生成,需要完全一致的随机序列 |
| 📊 数据校验 | 对拍算法、验证随机分布是否均匀 |
一句话:随机数 + 固定种子 = 确定性的"伪"随机,既能模拟随机行为,又能随时重演。
1 分钟理解原理:seed 为什么能"锁住"随机数?
fastrand 内部使用的 Rng 本质上只是一个 64 位整数的状态机:
// Rng 结构体:内部只有一个 u64 状态
pub struct Rng(u64);
它的 with_seed 方法直接把种子写入状态(src/lib.rs#L288-L294):
pub const fn with_seed(seed: u64) -> Self {
Rng(seed)
}
每次调用 u32(..)、bool()、shuffle() 等方法时,状态按固定公式推进并产出下一个数(核心是 src/lib.rs#L147-L159 的 WyRand 步进)。
💡 所以:相同的种子 + 相同的调用顺序 = 完全相同的随机数序列。这就是可复现的全部原理,没有任何魔法。
三步上手:用全局 seed() 固定随机结果
第 1 步:添加依赖
cargo add fastrand
第 2 步:在程序开头固定种子
// 选一个任意数字作为种子
fastrand::seed(7);
// 现在每次运行都打印相同的数
println!("{}", fastrand::u32(..));
这就是 README.md#L66-L74 中的官方示例,也是 src/lib.rs#L56-L64 文档注释里的同款演示。
第 3 步:运行两次验证
连续执行两次,u32(..) 的输出必然一致。官方测试 tests/smoke.rs#L220-L231 就是这个思路:
r.seed(7);
let a = r.u64(..);
r.seed(7);
let b = r.u64(..);
assert_eq!(a, b); // 两次结果完全相同
两种固定种子的方式:全局 seed() vs Rng::with_seed()
fastrand 提供两条路径,按需求选择:
| 方式 | 写法 | 适用场景 |
|---|---|---|
| 全局函数 | fastrand::seed(7) |
简单脚本、快速原型,一行搞定 |
| 独立实例 | Rng::with_seed(7) |
需要多个独立生成器、高性能场景 |
全局方式:seed() 初始化的是当前线程的 thread-local 生成器(src/global_rng.rs#L70-L74),之后直接调用 fastrand::u32(..)、fastrand::bool() 等顶层函数即可。
独立实例方式:适合高频调用(省去线程局部状态切换),也可随时用 seed() 重置:
let mut rng = fastrand::Rng::with_seed(42);
let x = rng.u64(..);
rng.seed(42); // 重置种子,序列从头再来
let y = rng.u64(..); // y == x
实例级的重置见 src/lib.rs#L539-L543,还可以用 get_seed() 随时查看当前种子(src/lib.rs#L545-L549)。
两种方式等价性的官方验证在 tests/smoke.rs#L269-L274:with_seed(7) 的生成器和先 new() 再 seed(7) 的生成器,输出完全一致。
实战:让 shuffle 和 choice 也可复现
可复现能力覆盖所有随机函数,举两个高频用例:
🎴 可复现洗牌(src/lib.rs#L574-L580)
let mut v = vec![1, 2, 3, 4, 5];
fastrand::seed(7);
fastrand::shuffle(&mut v);
println!("{:?}", v); // 每次运行顺序都相同
🎯 可复现随机抽取
let items = ["apple", "banana", "cherry"];
fastrand::seed(7);
println!("{}", fastrand::choice(&items).unwrap());
只要种子固定、调用顺序不变,洗牌结果、抽取结果、浮点 f64()、字符串 alphanumeric() 全部可复现。
进阶技巧:用 fork 派生"子生成器"
如果多个模块各自需要随机数,又不想互相串扰,可以用 fork() 从主生成器派生独立分支(src/lib.rs#L295-L323):
let mut base = fastrand::Rng::with_seed(0x4d595df4d0f33173);
base.bool(); // 先用一次
let mut child = base.fork(); // 派生子生成器
子生成器拥有独立序列,不会与父生成器"抢"随机数。同时 Rng 实现了 Clone(src/lib.rs#L133-L138),克隆出的实例基于相同种子,序列确定可重演——这对"保存现场、事后重放"非常有用。
5 个新手常见误区(附源码定位)
-
⚠️
Rng::new()每次种子都不同Rng::new()会用系统熵生成随机种子(src/global_rng.rs#L22-L28),想要复现必须改用Rng::with_seed(7)或seed(7)。 -
⚠️ 调用顺序变了,结果就变了 种子相同,但如果在两次调用之间多加了一次
u32(..),后面所有数都会"漂移"。复现的前提是种子 + 调用序列都一致。 -
⚠️ 全局生成器是线程局部的 全局 RNG 以
thread_local存储(src/global_rng.rs#L30-L32),fastrand::seed(7)只影响当前线程。多线程场景请为每个线程分别 seed,或直接使用独立的Rng实例。 -
⚠️ fastrand 不是加密安全的 官方明确说明其基于 WyRand,"简单快速但不具备密码学安全性"(见 src/lib.rs#L1-L4)。密码、Token、密钥等场景请换用
rand+ 操作系统熵源。 -
⚠️ WASM 环境注意默认种子 在非 WASI 的 WASM 目标上,若未启用
jsfeature,全局 RNG 会回退到一个预定义固定种子(src/global_rng.rs#L227-L234)——巧合的是,这反而天然"可复现"。
快速自检清单 ✅
- [ ] 程序入口是否调用了
fastrand::seed(7)或使用了Rng::with_seed(7)? - [ ] 两次运行之间的调用顺序是否完全一致?
- [ ] 多线程时是否为每个线程分别设置了种子?
- [ ] 是否误把 fastrand 用在了密码学场景?
- ] 跑一遍官方测试确认行为:
cargo test(可复现断言见 [tests/smoke.rs#L220-L242)
总结
fastrand 让"可复现随机数"变得极其简单:全局场景一行 fastrand::seed(7),独立场景一行 Rng::with_seed(7)。原理上它只是"固定状态机起点",但足以覆盖测试复现、调试回放、游戏模拟等绝大多数需求。核心 API 集中在 src/lib.rs(Rng 与实例方法)和 src/global_rng.rs(全局函数)两个文件,配合 tests/smoke.rs 中的测试用例,你可以快速上手并验证行为是否符合预期。