第 2 节:clap——工业级命令行参数

一句话:第 13 章的故事搜索器,我们手写了 env::args + Config::build 解析参数。clap 是那个手写版的"工业级升级"——还免费送你 --help、报错、默认值、长短选项。

安装

cargo add clap --features derive

基本用法:一个结构体,全自动 ⭐

use clap::Parser;

#[derive(Parser, Debug)]
#[command(name = "故事搜索器", version = "1.0", about = "在文件里搜索关键词")]
struct Args {
    /// 要搜索的关键词
    query: String,

    /// 要搜索的文件路径
    file_path: String,

    /// 忽略大小写
    #[arg(short, long)]
    ignore_case: bool,

    /// 最多显示几行
    #[arg(short, long, default_value_t = 10)]
    limit: u32,
}

fn main() {
    let args = Args::parse();   // 一行:解析 + 校验 + 出错自动退出
    println!("{:?}", args);
}

三个要点:

• #[derive(Parser)]:把结构体变成"参数表"——每个字段一个参数,字段注释(///)就是 --help 里的说明
• #[arg(short, long)]:-i / --ignore-case 都能用;布尔字段自动变开关
• default_value_t = 10:缺省值——limit 不传就是 10

免费赠送:帮助和报错 ⭐

运行 cargo run -- --help:

运行输出

在文件里搜索关键词
Usage: 故事搜索器.exe [OPTIONS] <QUERY> <FILE_PATH>

Arguments:
  <QUERY>      要搜索的关键词
  <FILE_PATH>  要搜索的文件路径

Options:
  -i, --ignore-case    忽略大小写
  -l, --limit <LIMIT>  最多显示几行  [default: 10]
  -h, --help           Print help
  -V, --version        Print version

少传一个参数:

运行输出

error: the following required arguments were not provided:
  <FILE_PATH>

Usage: 故事搜索器.exe <QUERY> <FILE_PATH>

手写版要写几十行的"参数不够就报错"、帮助文档,clap 全部免费——这就是"工业级"的意义。

高频进阶:子命令 ⭐

一个程序多个命令(add/list/remove),用枚举:

use clap::{Parser, Subcommand};

#[derive(Parser)]
struct Cli {
    #[command(subcommand)]
    command: Command,
}

#[derive(Subcommand)]
enum Command {
    /// 添加宠物
    Add { name: String, cuteness: u32 },
    /// 列出所有宠物
    List,
    /// 删除宠物
    Remove { name: String },
}

fn main() {
    let cli = Cli::parse();
    match cli.command {
        Command::Add { name, cuteness } => println!("添加 {} 可爱度 {}", name, cuteness),
        Command::List => println!("列出所有"),
        Command::Remove { name } => println!("删除 {}", name),
    }
}

每个枚举变体 = 一个子命令(参数还能不同)——第 7 章"菜单程序"的命令行版。

常见误用与坑

• 忘了 --features derive:cargo add clap 默认不带 derive,#[derive(Parser)] 编译不过——安装命令带 --features derive
• 字段名转参数名:ignore_case 自动变 --ignore-case(连字符);想要别的名字用 #[arg(long = "ic")]
• Args::parse() 出错直接退出程序:错误处理交给 clap(它打印帮助并 exit(2))——需要自己接住时用 try_parse()
• 多值参数:#[arg(num_args = 1..)] 收一串;位置参数 Vec<T> 也行
• 环境变量兜底:#[arg(env = "PORT")]——参数没传就读环境变量(第 13 章 IGNORE_CASE 的自动化)