Rust Crate 可配置变量的定义与对外暴露实现方案咨询

以下是三种生产环境常用的实现方式，可根据你的配置场景选择：

方案1：编译期通过环境变量配置（最常用的静态配置方案） #

适合不需要运行时修改、要编译期固化的全局配置，支持任意类型的自定义值

• 实现逻辑：通过build.rs构建脚本读取用户设置的环境变量，做类型校验后生成常量代码嵌入到 crate 中
• 实现步骤：
  1. 在 crate 根目录新建build.rs，参考代码如下（注意将CRATE_NAME替换为你的 crate 名称，避免环境变量冲突）：

  use std::env;
  use std::fs::write;
  use std::path::Path;
  
  fn main() {
      // 通知 Cargo 环境变量变化时重新运行构建脚本
      println!("cargo:rerun-if-env-changed=CRATE_NAME_WAIT_TIME");
      // 读取环境变量，设置默认值为30，同时做类型校验
      let wait_time = env::var("CRATE_NAME_WAIT_TIME")
          .unwrap_or_else(|_| "30".to_string())
          .parse::<u64>()
          .expect("CRATE_NAME_WAIT_TIME must be a valid unsigned integer");
      // 生成常量代码到 Cargo 输出目录
      let out_dir = env::var("OUT_DIR").unwrap();
      let dest_path = Path::new(&out_dir).join("generated_config.rs");
      write(dest_path, format!("pub const WAIT_TIME: u64 = {};\n", wait_time)).unwrap();
  }
  

  2. 在你的 crate 代码中引入生成的常量：

  // 在 src/lib.rs 顶部加入这行引入生成的配置
  include!(concat!(env!("OUT_DIR"), "/generated_config.rs"));
  
  // 业务代码中直接使用常量即可，无运行时开销
  pub fn do_something() {
      std::thread::sleep(std::time::Duration::from_secs(WAIT_TIME));
  }
  

  3. 你的 crate 用户编译时只需设置对应环境变量即可自定义配置：

  # Linux/macOS 下使用示例
  CRATE_NAME_WAIT_TIME=60 cargo build
  # Windows PowerShell 下使用示例
  $env:CRATE_NAME_WAIT_TIME=60; cargo build
  

方案2：运行期通过初始化接口配置 #

适合需要运行时动态修改、或者希望降低用户使用门槛的场景

• 实现逻辑：对外暴露配置结构体和初始化接口，内部用线程安全的全局存储保存配置
• 实现示例：

  use std::sync::RwLock;
  
  // 对外暴露的配置结构体
  #[derive(Debug, Clone, Copy)]
  pub struct CrateConfig {
      pub wait_time: u64,
      pub enable_log: bool,
      // 其他配置字段按需添加
  }
  
  // 提供默认配置，降低用户使用成本
  impl Default for CrateConfig {
      fn default() -> Self {
          Self {
              wait_time: 30,
              enable_log: false,
          }
      }
  }
  
  // 内部全局配置存储，RwLock 保证线程安全
  static GLOBAL_CONFIG: RwLock<CrateConfig> = RwLock::new(CrateConfig::default());
  
  // 对外暴露的初始化接口，用户只需在调用其他接口前执行一次即可
  pub fn init(config: CrateConfig) {
      let mut write_guard = GLOBAL_CONFIG.write().expect("Failed to write global config");
      *write_guard = config;
  }
  
  // 内部用的读取配置辅助方法
  pub(crate) fn get_config() -> CrateConfig {
      *GLOBAL_CONFIG.read().expect("Failed to read global config")
  }
  

• 用户使用示例：

  use your_crate::{init, CrateConfig};
  
  fn main() {
      // 初始化自定义配置
      init(CrateConfig {
          wait_time: 60,
          ..Default::default()
      });
      // 后续调用 crate 其他接口就会使用自定义配置
  }
  

方案3：Feature 开关映射固定值（可选配置项较少时使用） #

如果你的配置只有少量固定可选值，也可以用原生 Feature 间接实现

• 实现步骤：
  1. 在Cargo.toml中定义对应 Feature：

  [features]
  default = ["wait_time_30"]
  wait_time_30 = []
  wait_time_60 = []
  wait_time_120 = []
  

  2. 在代码中用cfg宏匹配 Feature 生成对应常量：

  #[cfg(feature = "wait_time_30")]
  pub const WAIT_TIME: u64 = 30;
  #[cfg(feature = "wait_time_60")]
  pub const WAIT_TIME: u64 = 60;
  #[cfg(feature = "wait_time_120")]
  pub const WAIT_TIME: u64 = 120;
  

• 用户只需在依赖中开启对应 Feature 即可配置，无需修改编译参数，缺点是不支持任意值输入。

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