Once、OnceCell、OnceLock：Rust 一次性初始化终极指南

Once、OnceCell、OnceLock：Rust 一次性初始化终极指南

在 Rust 开发中，我们经常会遇到一次性初始化的场景：比如全局配置加载、单例实例创建、资源初始化（如数据库连接、日志器）等。Rust 标准库提供了 Once、OnceCell 和 OnceLock 来解决这个问题。本文将从应用场景、核心 API、实战示例等维度，带你彻底搞懂三者的用法与选型。

为什么需要专门的一次性初始化工具？

在没有这些工具之前，我们实现一次性初始化可能会面临诸多问题：

• 用普通变量标记初始化状态，无法保证多线程安全，容易出现数据竞争；
• 用 Mutex<Option<T>> 包裹，每次访问都需要加锁，性能开销较大，且可能出现锁中毒；
• 用社区第三方库，如 lazy_static，需要引入外部依赖，且灵活性不足。

而 Once、OnceCell、OnceLock 作为标准库原生工具，既保证了线程安全（按需），又兼顾了性能，还能根据场景灵活选择，彻底解决了上述痛点。

Once / OnceCell / OnceLock 详解

三者的核心区别在于：是否存储值和是否线程安全。

Once：最基础的一次性执行（不存储值）

Once 位于 std::sync::Once，是最基础的一次性初始化工具。它不存储任何值，仅保证一段代码只被执行一次，无论多少线程同时调用，最终只会有一个线程执行目标代码，其他线程会阻塞等待直到执行完成。

use std::sync::{Once, OnceLock};

// 全局 Once 实例，用于控制日志器初始化
static INIT_LOGGER: Once = Once::new();

// 模拟日志器
struct Logger;

impl Logger {
    fn init() -> Self {
        println!("日志器初始化中...");
        // 模拟耗时操作
        std::thread::sleep(std::time::Duration::from_millis(100));
        Logger
    }
}

// 全局日志器实例
static LOGGER: OnceLock<Logger> = OnceLock::new();

fn get_logger() -> &'static Logger {
    INIT_LOGGER.call_once(|| {
        // 用 OnceLock 的 set 方法安全存储初始化后的实例
        let _ = LOGGER.set(Logger::init());
    });
    // Once 确保初始化完成，因此 unwrap 安全
    LOGGER.get().unwrap()
}

fn main() {
    // 多线程同时获取日志器，验证初始化只执行一次
    let handles: Vec<_> = (0..5).map(|_| {
        std::thread::spawn(|| {
            let logger = get_logger();
            println!("线程 {:?} 获取到日志器", std::thread::current().id());
        })
    }).collect();

    for handle in handles {
        handle.join().unwrap();
    }
}

Once 是线程安全的，底层通过原子操作实现，所以无需额外加锁。但是缺点也很明显，那就是不存储值，需要配合 OnceLock 或其他安全存储的工具来管理状态。相比直接使用 OnceCell/OnceLock 不够便捷。

OnceCell：单线程的一次性存储（不保证线程安全）

OnceCell 位于 std::cell::OnceCell，它不仅能保证一次性初始化，还能存储一个值，无需手动管理状态。但需要注意的是 OnceCell 不保证线程安全，仅适用于单线程场景。

下面的示例是单线程场景下，用 OnceCell 存储配置，避免重复加载：

use std::cell::OnceCell;

// 模拟配置结构体
#[derive(Debug)]
struct Config {
    database_url: String,
    timeout: u64,
}

impl Config {
    fn load() -> Self {
        println!("加载配置中...");
        std::thread::sleep(std::time::Duration::from_millis(100));
        Config {
            database_url: "mysql://root:123456@localhost:3306/db".to_string(),
            timeout: 30,
        }
    }
}

fn main() {
    let mut config_cell = OnceCell::new();

    // 第一次获取：未初始化，执行 load 并存储
    let config1 = config_cell.get_or_init(Config::load);
    println!("第一次获取配置: {:?}", config1);

    // 第二次获取：已初始化，直接返回
    let config2 = config_cell.get_or_init(Config::load);
    println!("第二次获取配置: {:?}", config2);

    // 尝试重新设置值：失败，返回 Err
    let result = config_cell.set(Config {
        database_url: "postgres://user:pass@localhost:5432/db".to_string(),
        timeout: 60,
    });
    println!("重新设置配置: {:?}", result); // Err(Config { ... })

    // 可变引用修改（需持有 mut 引用）
    if let Some(mut config) = config_cell.get_mut() {
        config.timeout = 45;
    }
    println!("修改后配置: {:?}", config_cell.get().unwrap());
}

OnceLock：多线程的一次性存储（线程安全）

OnceLock 位于 std::sync::OnceLock，是 OnceCell 的线程安全版本。它继承了 OnceCell 的一次性存储特性，同时保证了多线程环境下的安全访问，底层结合了 Once 的线程同步机制和 UnsafeCell 的值存储能力，且不会像 Mutex 那样出现锁中毒问题。

在多线程场景下，OnceLock 是最常用的一次性初始化工具，尤其适合创建全局单例、共享资源等场景。

下面的示例是用 OnceLock 实现线程安全的单例，确保实例只被创建一次：

use std::sync::OnceLock;

// 模拟 HTTP 客户端
struct HttpClient {
    base_url: String,
    timeout: u64,
}

impl HttpClient {
    fn new(base_url: String, timeout: u64) -> Self {
        println!("HTTP 客户端初始化中...");
        std::thread::sleep(std::time::Duration::from_millis(200));
        HttpClient { base_url, timeout }
    }

    fn get(&self, path: &str) -> String {
        format!("GET {}{}", self.base_url, path)
    }
}

// 全局单例 HTTP 客户端
static HTTP_CLIENT: OnceLock<HttpClient> = OnceLock::new();

// 获取全局 HTTP 客户端
fn get_http_client() -> &'static HttpClient {
    HTTP_CLIENT.get_or_init(|| {
        HttpClient::new("https://api.example.com".to_string(), 30)
    })
}

fn main() {
    // 多线程同时获取客户端，验证初始化只执行一次
    let handles: Vec<_> = (0..10).map(|i| {
        std::thread::spawn(move || {
            let client = get_http_client();
            let response = client.get(&format!("/users/{}", i));
            println!("线程 {:?} 发送请求: {}", std::thread::current().id(), response);
        })
    }).collect();

    for handle in handles {
        handle.join().unwrap();
    }
}

OnceLock 实现了 Sync + Send 特征，所以可以安全地跨线程共享，适合作为全局静态变量。当调用 get_or_init 时，只有一个线程会执行闭包，其他线程会阻塞等待，避免重复初始化。OnceLock 与 Mutex<Option<T>> 相比，OnceLock 无需每次访问都加锁，初始化完成后读取操作无锁，性能更优，且不会因 panic 导致锁中毒。

快速选型

特性	Once	OnceCell	OnceLock
是否存储值	否（仅执行代码）	是	是
线程安全	是（仅保证代码执行一次）	否（单线程专用）	是（多线程专用）
适用场景	无值存储的一次性初始化（如全局资源启动）	单线程延迟初始化、局部一次性存储	多线程延迟初始化、全局单例、共享资源
性能	极高（仅原子操作，无值存储开销）	高（无线程同步开销）	较高（初始化时有同步开销，读取无锁）
是否需要 unsafe	是（需手动管理存储值）	否	否
核心优势	极简、轻量，专注于一次性执行	单线程场景下便捷、高效，无需同步	线程安全，原生支持全局静态变量，无锁读取

常见坑

• 将 OnceCell 用于多线程场景：OnceCell 不实现 Sync 特征，跨线程共享会触发编译错误，此时应使用 OnceLock；
• 过度依赖 Once：Once 不存储值，手动管理状态容易出错，有存储需求时优先用 OnceCell/OnceLock；
• 忽略 set 方法的返回值：set 失败时会返回传入的值，若不处理可能导致值丢失；
• 在 get_or_init 闭包中 panic：闭包 panic 后，Once/OnceCell/OnceLock 会标记为已执行，后续无法再初始化，需避免闭包 panic。

总结

根据实际场景（是否多线程、是否需要存储值）选择合适的工具，让代码更简洁、高效、安全。