Rust 配置管理

分层配置：默认值、文件、环境变量与校验；与 clap 及服务启动的边界。

#concept #growing #dev #rust

[!info] related notes

所属 MOC：系统与服务 · 学习路线

前置概念：Serde、clap、错误

后续概念：Docker、HTTP

容易混淆：CLI 参数

Rust 配置管理

这个概念为什么出现

服务配置来源多：默认、文件、环境变量、命令行。
需要合并顺序、类型校验与密钥不进仓库。

[!abstract] 一句话理解用强类型 Config 结构体承载配置；可约定“默认 < 文件 < 环境变量 < CLI”覆盖（必须由应用或库显式实现）；启动失败要快且信息明确。

最小可运行示例

场景：读取端口与模式

use std::env;

// 业务意图：环境变量覆盖默认端口。
// 教学点：强类型解析；默认值；错误提前。

#[derive(Debug)]
struct Config {
    port: u16,
    mode: String,
}

impl Config {
    fn from_env() -> Result<Self, String> {
        let port = env_or_default("APP_PORT", "8080")?
            .parse::<u16>()
            .map_err(|e| format!("APP_PORT: {e}"))?;
        if port == 0 {
            return Err("APP_PORT must be in 1..=65535".into());
        }
        let mode = env_or_default("APP_MODE", "dev")?;
        if !matches!(mode.as_str(), "dev" | "staging" | "prod") {
            return Err("APP_MODE must be dev, staging or prod".into());
        }
        Ok(Self { port, mode })
    }
}

fn env_or_default(name: &str, default: &str) -> Result<String, String> {
    match env::var(name) {
        Ok(value) => Ok(value),
        Err(env::VarError::NotPresent) => Ok(default.into()),
        Err(env::VarError::NotUnicode(_)) => Err(format!("{name} must be valid Unicode")),
    }
}

fn main() -> Result<(), String> {
    let cfg = Config::from_env()?;
    println!("port={} mode={}", cfg.port, cfg.mode);
    Ok(())
}

POSIX shell 运行：APP_PORT=3000 APP_MODE=prod cargo run，应输出 port=3000 mode=prod。此示例只实现环境变量覆盖默认值，没有读取 .env、配置文件或 CLI 配置层。空字符串、非法端口和非 Unicode 环境变量不能静默回退默认。

结合场景再看三个关注点

错误在启动期暴露
只打印允许公开的字段；含密钥的 Config 不应整体 Debug 输出，环境变量也不是自动保密机制
可用 config crate 做分层合并

工程实践

示例 .env.example 无秘密
校验枚举模式
配置热更新慎用
与十二因子对齐

本节总结

强类型配置
覆盖顺序
启动失败快速

自测题

为什么配置解析失败应阻止启动？
CLI 与环境变量谁优先？

参考答案

避免带错误配置半运行。
通常 CLI 最高，团队写清即可。

延伸阅读与资料来源

资料	类型	支撑内容
12-factor config	方法论	配置
config crate	生态	分层配置