使用 clap 构建 CLI

用 clap 做声明式参数解析、子命令与帮助信息，构建可维护 CLI。

#concept #growing #dev #rust

[!info] related notes

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

前置概念：标准库 CLI、struct

后续概念：配置、日志

容易混淆：手写 args

使用 clap 构建 CLI

这个概念为什么出现

手写 args 在子命令、默认值、类型转换、帮助信息时迅速失控。
clap 是生态事实标准之一。

[!abstract] 一句话理解用结构体 + Parser derive 声明 CLI 接口，clap 生成解析、帮助与错误信息。

最小可运行示例

场景：发布工具——环境与是否 dry-run

在 Cargo 项目中添加 clap 4 的 derive 支持：

cargo add clap@4 --features derive

use clap::{Parser, ValueEnum};

#[derive(Clone, Debug, ValueEnum)]
enum Environment { Dev, Staging, Prod }

#[derive(Parser, Debug)]
#[command(name = "ship", about = "Parse release options")]
struct Args {
    /// Target environment
    #[arg(value_enum)]
    env: Environment,
    /// Request a preview without side effects
    #[arg(long)]
    dry_run: bool,
}

fn main() {
    let args = Args::parse();
    println!("parsed env={:?} dry_run={}", args.env, args.dry_run);
}

运行 cargo run -- --help 显示帮助；cargo run -- prod --dry-run 输出 parsed env=Prod dry_run=true；未知环境返回解析错误。这个例子只解析并打印，不执行发布；dry-run 的副作用隔离必须由业务层实现，布尔参数本身不会阻止写入。

结合场景再看三个关注点

帮助信息来自字段文档注释
类型安全解析
子命令用 enum

核心概念

derive vs builder API
子命令、全局参数
默认值与环境变量映射需显式配置；clap 的 env 功能还需启用 env feature
Parser::parse 负责打印并退出：帮助/版本通常为 0，参数错误通常为 2；测试或嵌入调用可用 try_parse_from 取得 Result
校验与 value_parser

工程实践

CLI 结构体与业务配置类型分离映射
错误信息对用户友好
快照测试 help 文本（可选）
shell 补全可生成

本节总结

clap 声明式 CLI
生产工具默认选项
与配置/日志衔接

自测题

为何要把 Args 映射到内部 Config？
dry-run 的价值？

参考答案

解耦解析与领域，便于测试。
安全预演副作用。

延伸阅读与资料来源

资料	类型	支撑内容
clap docs	生态	API
clap tutorial	生态	derive 教程