Cargo集成测试如何实现仅运行一次的异步初始化代码

核心问题本质是std::sync::Once仅支持同步初始化逻辑，而异步初始化如果手动新建运行时会和测试宏自动创建的运行时产生嵌套冲突，直接用异步场景下的单次初始化原语即可解决，全程不会触发运行时嵌套问题，且能保证服务在整个集成测试流程中仅启动一次。

具体实现 #

• 替换同步的std::sync::Once为tokio::sync::OnceCell，这是Tokio运行时原生提供的线程安全异步懒初始化容器，能保证闭包内的逻辑在全局仅执行一次，且所有异步任务都可以安全等待初始化完成。
• 初始化逻辑放到测试运行时上下文内执行，不单独新建运行时，服务直接spawn到当前测试运行时，绑定随机空闲端口避免冲突。
• 所有测试用例统一从全局容器获取已启动的服务地址，直接发起真实HTTP请求，走完整的网络、路由、序列化、中间件逻辑，完全匹配生产环境的请求处理路径。

代码示例（tests/api.rs） #

use actix_web::{web, App, HttpResponse, HttpServer};
use tokio::sync::OnceCell;

// 全局静态存储服务访问地址，const初始化无额外开销
static SERVICE_ADDR: OnceCell<String> = OnceCell::const_new();

/// 获取全局测试服务地址，首次调用时会完成服务初始化，后续调用直接返回已有地址
async fn get_service_addr() -> &'static str {
    SERVICE_ADDR
        .get_or_init(|| async {
            // 此处和main函数的服务启动逻辑保持完全一致，注册所有路由、中间件、全局状态
            let server = HttpServer::new(|| {
                App::new()
                    .route("/api/health", web::get().to(|| async {
                        HttpResponse::Ok().json(serde_json::json!({"code":0,"msg":"ok"}))
                    }))
                    // 其余业务路由、中间件、全局状态注入都在这里完成
            })
            // 绑定0端口让系统自动分配空闲端口，避免测试端口冲突
            .bind(("127.0.0.1", 0))
            .expect("测试服务绑定端口失败");

            // 拿到系统分配的实际监听地址
            let bind_addr = server.addrs()[0];
            // 将服务spawn到当前测试运行时，不要await阻塞，否则服务无法对外提供访问
            tokio::spawn(server.run());

            format!("http://{}", bind_addr)
        })
        .await
}

// 测试用例直接使用actix_web::test宏即可，无需修改原有测试写法
#[actix_web::test]
async fn test_health_api() {
    let base_url = get_service_addr().await;
    // 直接用HTTP客户端发真实请求，覆盖完整的序列化、路由、中间件逻辑
    let client = reqwest::Client::new();
    let resp = client
        .get(format!("{base_url}/api/health"))
        .send()
        .await
        .expect("请求测试服务失败");
    
    assert!(resp.status().is_success());
    let resp_body: serde_json::Value = resp.json().await.unwrap();
    assert_eq!(resp_body["code"], 0);
}

#[actix_web::test]
async fn test_other_biz_api() {
    // 本次调用会直接返回已初始化的地址，不会重复启动服务
    let base_url = get_service_addr().await;
    // 其余业务接口测试逻辑
}

避坑说明 #

• 不要用std::sync::Once配合tokio::runtime::Runtime::block_on的写法，在已存在异步运行时的上下文里调用block_on会直接触发panic。
• 不要在初始化逻辑里使用#[actix_web::main]或者手动创建新的Runtime，所有异步逻辑都在测试宏自动创建的当前运行时内执行，从根源避免嵌套运行时冲突。
• 不要写死服务监听端口，用0端口让系统自动分配空闲端口，支持cargo多线程并行跑测试，不会出现端口占用报错。
• 服务随测试进程退出自动回收，无需手动添加停机逻辑，不会残留僵尸进程。如果服务依赖数据库、缓存等外部组件，建表、测试数据初始化等逻辑也可以放到get_or_init的闭包内，同样只会全局执行一次。

内容的提问来源于stack exchange，提问作者Ashok