---

name: domain-cli description: “用于构建CLI工具时使用。关键词：CLI，命令行，终端，clap，structopt，参数解析，子命令，交互式，TUI，ratatui，crossterm，indicatif，进度条，彩色输出，shell补全，配置文件，环境变量，命令行，终端应用，参数解析” globs: [“**/Cargo.toml”] user-invocable: false

CLI 领域

第3层：领域约束

领域约束 → 设计影响

领域规则	设计约束	Rust 实现
用户体验	清晰的帮助和错误信息	clap 派生宏
配置优先级	命令行 > 环境变量 > 配置文件	分层配置加载
退出码	错误时返回非零值	正确的 Result 处理
标准输出/错误输出	数据 vs 错误	使用 eprintln! 输出错误
可中断性	处理 Ctrl+C	信号处理

---

关键约束

用户通信

规则：错误输出到 stderr，数据输出到 stdout
原因：支持管道输出，可脚本化
RUST：使用 eprintln! 输出错误，println! 输出数据

配置优先级

规则：命令行参数 > 环境变量 > 配置文件 > 默认值
原因：用户期望，支持覆盖能力
RUST：使用 clap + figment/config 进行分层配置

退出码

规则：任何错误时返回非零值
原因：脚本集成，自动化
RUST：main() -> Result<(), Error> 或显式 exit()

---

向下追踪 ↓

从约束到设计（第2层）：

"需要参数解析"
    ↓ m05-类型驱动：为参数派生结构体
    ↓ clap: #[derive(Parser)]

"需要配置分层"
    ↓ m09-领域：配置作为领域对象
    ↓ figment/config：分层数据源

"需要进度显示"
    ↓ m12-生命周期：进度条作为 RAII
    ↓ indicatif：ProgressBar

---

关键库

用途	库
参数解析	clap
交互式提示	dialoguer
进度条	indicatif
彩色输出	colored
终端用户界面	ratatui
终端控制	crossterm
控制台工具	console

设计模式

模式	目的	实现
参数结构体	类型安全的参数	#[derive(Parser)]
子命令	命令层次结构	#[derive(Subcommand)]
配置分层	覆盖优先级	CLI > env > file
进度	用户反馈	ProgressBar::new(len)

代码模式：CLI 结构

use clap::{Parser, Subcommand};

#[derive(Parser)]
#[command(name = "myapp", about = "我的 CLI 工具")]
struct Cli {
    /// 启用详细输出
    #[arg(short, long)]
    verbose: bool,

    #[command(subcommand)]
    command: Commands,
}

#[derive(Subcommand)]
enum Commands {
    /// 初始化新项目
    Init { name: String },
    /// 运行应用程序
    Run {
        #[arg(short, long)]
        port: Option<u16>,
    },
}

fn main() -> anyhow::Result<()> {
    let cli = Cli::parse();
    match cli.command {
        Commands::Init { name } => init_project(&name)?,
        Commands::Run { port } => run_server(port.unwrap_or(8080))?,
    }
    Ok(())
}

---

常见错误

错误	领域违规	修复方法
错误输出到 stdout	破坏管道功能	使用 eprintln!
没有帮助文本	用户体验差	#[arg(help = “…”)]
错误时 panic	退出码错误	Result + 正确处理
长时间操作无进度	用户不确定	使用 indicatif

---

追踪到第1层

约束	第2层模式	第1层实现
类型安全参数	派生宏	clap Parser
错误处理	Result 传播	anyhow + 退出码
用户反馈	进度 RAII	indicatif ProgressBar
配置优先级	构建器模式	分层数据源

---

相关技能

何时使用	参见
错误处理	m06-错误处理
类型驱动参数	m05-类型驱动
进度生命周期	m12-生命周期
异步 CLI	m07-并发