Rust 测试体系：从单元测试到集成测试，质量保障的完整拼图

Rust 测试体系：从单元测试到集成测试，质量保障的完整拼图

一、Rust 测试不只是#[test]：编译期保障的延伸

Rust 的类型系统和所有权规则在编译期消除了大量 bug，但编译器无法验证业务逻辑的正确性。一个函数签名正确、编译通过的代码，仍然可能返回错误的结果。测试是编译期保障的延伸，它验证的是"代码做了正确的事"，而不仅仅是"代码是安全的"。

Rust 内置了测试框架，不需要额外引入依赖。#[test]标注测试函数，cargo test运行所有测试。这种开箱即用的体验降低了写测试的门槛。但 Rust 的测试体系远不止#[test]这么简单。单元测试、集成测试、文档测试、基准测试——每种测试类型有不同的组织方式和适用场景。

生产环境里，测试的痛点不是"不会写"，而是"不知道该测什么"。过度测试导致维护成本高，测试比业务代码还脆弱。测试不足导致重构时没有安全网，改一行代码就不知道哪里会崩。找到合适的测试密度，比学会测试语法难得多。

二、Rust 测试体系的分层结构

Rust 的测试体系按照粒度和隔离程度分为四个层次。

graph TD A[Rust 测试体系] --> B[文档测试 doc test] A --> C[单元测试 unit test] A --> D[集成测试 integration test] A --> E[基准测试 benchmark] B --> B1[嵌入在文档注释中] B1 --> B2[验证公开 API 示例可运行] C --> C1[与源码同文件，mod tests] C1 --> C2[可访问私有函数] C2 --> C3[验证单个函数/模块逻辑] D --> D1[独立 tests/ 目录] D1 --> D2[只能访问公开 API] D2 --> D3[验证跨模块交互] E --> E1[criterion 库] E1 --> E2[统计性能指标] E2 --> E3[检测性能回归]

文档测试是最轻量的测试形式。Rust 的文档注释中写的代码示例会被编译和运行。这保证了文档中的示例始终与代码保持同步。如果 API 变更导致示例无法编译，文档测试会失败。

单元测试放在源码文件内部的#[cfg(test)] mod tests中。#[cfg(test)]确保测试代码不会出现在生产构建中。单元测试可以访问模块内的私有函数，适合验证内部逻辑。

集成测试放在项目根目录的tests/文件夹中。每个文件是一个独立的 crate，只能通过公开 API 访问被测代码。集成测试验证的是模块间的交互，以及外部用户的使用体验。

基准测试使用criterion库，提供统计意义上的性能测量。它不只是计时，还会做回归检测——如果某次提交导致性能下降超过阈值，CI 会报错。

三、生产级测试代码：从断言到测试工具链

单元测试：验证核心逻辑

/// 配额管理器：限制单位时间内的操作次数 pub struct RateLimiter { /// 最大允许次数 max_requests: u32, /// 当前时间窗口内的已用次数 current_count: u32, /// 时间窗口长度（秒） window_secs: u64, /// 窗口起始时间 window_start: std::time::Instant, } impl RateLimiter { /// 创建新的限速器 pub fn new(max_requests: u32, window_secs: u64) -> Self { Self { max_requests, current_count: 0, window_secs, window_start: std::time::Instant::now(), } } /// 尝试请求，返回是否允许 pub fn try_acquire(&mut self) -> bool { self.reset_if_expired(); if self.current_count < self.max_requests { self.current_count += 1; true } else { false } } /// 获取当前窗口剩余配额 pub fn remaining(&self) -> u32 { self.max_requests.saturating_sub(self.current_count) } /// 如果时间窗口过期，重置计数器 fn reset_if_expired(&mut self) { if self.window_start.elapsed().as_secs() >= self.window_secs { self.current_count = 0; self.window_start = std::time::Instant::now(); } } } #[cfg(test)] mod tests { use super::*; #[test] fn test_acquire_within_limit() { let mut limiter = RateLimiter::new(3, 60); assert!(limiter.try_acquire()); assert!(limiter.try_acquire()); assert!(limiter.try_acquire()); // 超出配额，应被拒绝 assert!(!limiter.try_acquire()); } #[test] fn test_remaining_count() { let mut limiter = RateLimiter::new(5, 60); assert_eq!(limiter.remaining(), 5); limiter.try_acquire(); assert_eq!(limiter.remaining(), 4); } #[test] fn test_zero_quota() { let mut limiter = RateLimiter::new(0, 60); assert!(!limiter.try_acquire()); assert_eq!(limiter.remaining(), 0); } }

集成测试：验证跨模块交互

// tests/api_integration.rs use my_crate::{RateLimiter, RequestHandler}; /// 测试限速器与请求处理器的集成 #[test] fn test_rate_limiter_with_handler() { let limiter = std::sync::Mutex::new(RateLimiter::new(2, 60)); let handler = RequestHandler::new(); // 模拟两次请求应成功 { let mut guard = limiter.lock().unwrap(); assert!(guard.try_acquire()); assert!(guard.try_acquire()); } // 第三次请求应被限速 let result = handler.handle_request("/api/data", &limiter); assert!(result.is_err()); assert!(result.unwrap_err().to_string().contains("限速")); }

文档测试：保证示例可运行

/// 计算两个数的最大公约数 /// /// # Examples /// /// ``` /// use my_crate::gcd; /// assert_eq!(gcd(12, 8), 4); /// assert_eq!(gcd(7, 13), 1); /// ``` pub fn gcd(a: u64, b: u64) -> u64 { let mut a = a; let mut b = b; while b != 0 { let temp = b; b = a % b; a = temp; } a }

四、测试策略的权衡与常见误区

测试密度的选择：核心业务逻辑（如计费、权限、状态机）需要高密度测试，覆盖各种边界条件。胶水代码（如 HTTP handler、配置加载）测试密度可以低一些，因为它们的正确性依赖框架保证。一个经验值是：核心模块的测试代码量应与业务代码量持平，胶水代码的测试代码量可以是业务代码的 30%-50%。

Mock 的使用边界：Rust 的 mock 生态不如 Java/Python 成熟。mockall是最常用的 mock 库，但它需要为被 mock 的 trait 生成代码，对泛型 trait 的支持有限。一个替代方案是定义轻量的 fake 实现，而不是用 mock 框架。比如测试数据库交互时，用内存 HashMap 代替真实数据库，比 mock 每个方法调用更可靠。

异步测试的坑：#[tokio::test]为每个测试创建独立的 tokio 运行时。如果测试涉及共享资源（如临时文件、端口），需要确保测试之间不会冲突。tempfile库可以创建唯一的临时目录，避免并发测试的文件冲突。

测试执行速度：随着测试数量增长，cargo test的执行时间会变长。将慢速测试（涉及 IO、网络、数据库）标注为#[ignore]，日常开发只跑快速测试，CI 中用cargo test -- --include-ignored跑全量。另一个优化是开启测试并行度：cargo test -- --test-threads=4。

一个常犯的错误：在测试中使用assert!(expr)而不是assert_eq!(expected, actual)。前者失败时只显示"assertion failed"，后者会打印期望值和实际值。调试信息越充分，定位问题越快。同理，assert_ne!比assert!(!=)更有用。

五、总结

Rust 的测试体系分为文档测试、单元测试、集成测试和基准测试四个层次，各有适用场景。文档测试保证示例可运行，单元测试验证内部逻辑，集成测试验证跨模块交互，基准测试检测性能回归。测试密度应根据代码重要性调整，核心逻辑高密度，胶水代码低密度。Mock 在 Rust 中不如其他语言方便，轻量 fake 实现是更实用的替代方案。异步测试需要注意资源隔离，慢速测试应标注#[ignore]分离执行。好的测试策略不是追求覆盖率数字，而是为重构提供安全网。