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] 分离执行。好的测试策略不是追求覆盖率数字，而是为重构提供安全网。