Clap 子命令与配置文件加载

示例说明

配置来源的优先级判定需要知道值从哪来——clap 的 value_source 暴露这一点：显式命令行传参高于一切；未显式传时（默认值或环境变量兜底）允许配置文件覆盖。env 属性把环境变量声明在参数上，帮助文本自动展示变量名，运维文档零额外维护。

技术要点

• value_source 区分值的来源层级
• env 属性声明环境变量兜底
• value_parser 的 range 约束入口校验

代码解读

build_cli 的 sync 子命令带三个参数：workers 有范围校验与默认值、region 同理、dry-run 是布尔开关。load_file_overrides 解析简单键值文件；resolve 的分支——命令行显式传参直接用，否则查文件覆盖，最后回退 clap 解析值（默认或环境变量）。主分发按子命令派发。

使用建议

配置文件解析生产用 serde 加结构体校验。参数名与配置键的映射约定要文档化。子命令多时拆模块文件维护。

代码示例

use clap::{Arg, ArgAction, Command};
use std::collections::HashMap;

#[derive(Debug)]
struct SyncOptions {
    workers: u32,
    region: String,
    dry_run: bool,
}

fn build_cli() -> Command {
    Command::new("deployctl")
        .about("deployment control tool")
        .subcommand(
            Command::new("sync")
                .about("sync catalog to a region")
                .arg(
                    Arg::new("workers")
                        .short('w')
                        .long("workers")
                        .env("DEPLOY_WORKERS")
                        .default_value("4")
                        .value_parser(clap::value_parser!(u32).range(1..=64)),
                )
                .arg(
                    Arg::new("region")
                        .short('r')
                        .long("region")
                        .env("DEPLOY_REGION")
                        .default_value("eu"),
                )
                .arg(
                    Arg::new("dry-run")
                        .long("dry-run")
                        .action(ArgAction::SetTrue),
                ),
        )
        .subcommand(
            Command::new("status").about("show sync status"),
        )
}

fn load_file_overrides(path: &str) -> HashMap<String, String> {
    let mut map = HashMap::new();
    if let Ok(content) = std::fs::read_to_string(path) {
        for line in content.lines() {
            if let Some((key, value)) = line.split_once('=') {
                map.insert(key.trim().to_string(), value.trim().to_string());
            }
        }
    }
    map
}

fn resolve(matches: &clap::ArgMatches, file: &HashMap<String, String>) -> SyncOptions {
    let flag_workers: u32 = *matches.get_one("workers").unwrap_or(&4);

    // 显式传参 > 配置文件 > clap 默认值（含环境变量）
    let workers = if matches.value_source("workers")
        == Some(clap::builder::ValueSource::CommandLine)
    {
        flag_workers
    } else if let Some(from_file) = file.get("workers").and_then(|v| v.parse().ok()) {
        from_file
    } else {
        flag_workers
    };

    let region = matches
        .get_one::<String>("region")
        .cloned()
        .unwrap_or_else(|| "eu".into());

    SyncOptions {
        workers,
        region,
        dry_run: matches.get_flag("dry-run"),
    }
}

fn main() {
    let cli = build_cli();
    let matches = cli.get_matches();

    match matches.subcommand() {
        Some(("sync", sub)) => {
            let file = load_file_overrides("deployctl.conf");
            let options = resolve(sub, &file);
            println!("{options:?}");
        }
        Some(("status", _)) => println!("status: idle"),
        _ => unreachable!("clap 保证子命令必选"),
    }
}