第11章命令行参数解析

课程目录第11章命令行参数解析

命令行参数解析：CLI11 库实战

说实话，命令行参数解析这事儿，看着简单，做起来坑不少。我见过太多项目，自己手写解析逻辑，结果参数一多就乱成一锅粥。今天咱们聊聊 CLI11 这个库，它是我目前在 C++ 项目里最顺手的参数解析工具。

为什么选 CLI11？

你可能用过 getopt、Boost.ProgramOptions，甚至自己写解析。我个人习惯是：能用现成的就别重复造轮子。CLI11 有几个让我特别舒服的地方：

纯头文件：就一个头文件，扔进项目就能用，不用折腾链接
现代 C++ 风格：C++11 以上，用起来很自然
自动生成帮助：你定义好参数，帮助信息自动就有了
子命令支持：像 git 那样，add、commit、push 各自一套参数

核心优势：CLI11 把参数定义和校验合在一起了。你定义参数类型、默认值、校验规则，它自动帮你做类型转换和错误提示。

快速上手：一个简单的例子

先来个最基础的。假设我们要写一个文件处理工具，需要输入文件名和输出格式：

#include <CLI/CLI.hpp>
#include <iostream>

int main(int argc, char** argv) {
    CLI::App app{"文件处理工具 v1.0"};

    std::string input_file;
    std::string output_format = "txt";
    bool verbose = false;

    app.add_option("-i,--input", input_file, "输入文件路径")->required();
    app.add_option("-f,--format", output_format, "输出格式 (txt/csv/json)");
    app.add_flag("-v,--verbose", verbose, "启用详细输出");

    CLI11_PARSE(app, argc, argv);

    std::cout << "输入文件: " << input_file << "\n";
    std::cout << "输出格式: " << output_format << "\n";
    std::cout << "详细模式: " << (verbose ? "是" : "否") << "\n";

    return 0;
}

你看，就这么几行。运行的时候：

$ ./tool -i data.txt -f csv -v
输入文件: data.txt
输出格式: csv
详细模式: 是

如果忘了加必填参数：

$ ./tool
ERROR: Option --input,--input is required
Usage: ./tool [OPTIONS] -i,--input TEXT

位置选项：
  -i,--input TEXT 输入文件路径 [必填]

选项：
  -f,--format TEXT 输出格式 (txt/csv/json) [默认: txt]
  -v,--verbose     启用详细输出
  -h,--help        显示帮助信息

嗯，这里要注意：帮助信息是自动生成的，你不需要手写任何帮助文本。CLI11 根据你定义的参数，自动排版输出。

参数校验：别让用户乱填

我在项目中遇到过最头疼的事，就是用户传了个不合法的参数值，程序崩溃了。CLI11 的校验机制能帮你提前拦住这些问题。

范围校验

int threads = 4;
app.add_option("-t,--threads", threads, "线程数")
    ->check(CLI::Range(1, 16));  // 只允许 1 到 16

用户传了 0 或 17，CLI11 直接报错：

$ ./tool -t 0
ERROR: --threads: Value 0 not in range [1, 16]

自定义校验

有时候内置校验不够用。比如要校验文件是否存在：

app.add_option("-i,--input", input_file, "输入文件")
    ->check(CLI::ExistingFile);  // 文件必须存在

我曾经踩过一个坑：用户传了个不存在的文件路径，程序读文件时直接崩溃。加上 ExistingFile 校验后，CLI11 会在解析阶段就报错，根本不会走到文件读取那一步。

正则校验

对于更复杂的格式，比如邮箱、IP 地址：

std::string email;
app.add_option("--email", email, "邮箱地址")
    ->check(CLI::Validator("^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$", "邮箱格式不正确"));

小技巧：校验规则可以叠加。比如既要范围校验，又要整数校验：->check(CLI::Range(1, 100))->check(CLI::IsNumber)。CLI11 会依次执行所有校验。

子命令：像 git 一样组织工具

如果你的工具功能比较多，子命令是最好的组织方式。比如一个数据处理工具，有导入、导出、清理三个功能：

CLI::App app{"数据处理工具"};

// 子命令：导入
CLI::App* import_cmd = app.add_subcommand("import", "导入数据");
std::string import_file;
import_cmd->add_option("file", import_file, "数据文件")->required();

// 子命令：导出
CLI::App* export_cmd = app.add_subcommand("export", "导出数据");
std::string export_format;
export_cmd->add_option("-f,--format", export_format, "导出格式");

// 子命令：清理
CLI::App* clean_cmd = app.add_subcommand("clean", "清理临时文件");
bool dry_run = false;
clean_cmd->add_flag("--dry-run", dry_run, "仅模拟运行");

// 必须指定一个子命令
app.require_subcommand(1);

CLI11_PARSE(app, argc, argv);

if (app.got_subcommand(import_cmd)) {
    std::cout << "导入文件: " << import_file << "\n";
} else if (app.got_subcommand(export_cmd)) {
    std::cout << "导出格式: " << export_format << "\n";
} else if (app.got_subcommand(clean_cmd)) {
    std::cout << "清理模式: " << (dry_run ? "模拟" : "实际执行") << "\n";
}

运行效果：

$ ./tool import data.csv
导入文件: data.csv

$ ./tool export -f json
导出格式: json

$ ./tool clean --dry-run
清理模式: 模拟

$ ./tool -h
数据处理工具
用法: ./tool [OPTIONS] SUBCOMMAND

子命令：
  import  导入数据
  export  导出数据
  clean   清理临时文件

选项：
  -h,--help  显示帮助信息

子命令的好处是：每个子命令有自己的参数空间，互不干扰。而且帮助信息也是自动生成的，每个子命令都能单独查看帮助。

注意：子命令嵌套不要太深。我见过有人嵌套了 4 层，结果用户自己都搞不清该用哪个。一般来说，两层就够了：主命令 + 子命令。如果功能实在太多，考虑拆成多个独立工具。

自动生成帮助信息

CLI11 的帮助信息是自动生成的，但你可以定制它的样式。比如修改程序名、添加版本信息：

app.name("mytool");
app.version("2.1.0");
app.description("一个强大的数据处理工具");
app.footer("更多信息请访问 https://example.com");

运行 --help 时：

mytool 2.1.0
一个强大的数据处理工具
用法: mytool [OPTIONS] SUBCOMMAND

...

更多信息请访问 https://example.com

我个人习惯把版本号放在 CMakeLists.txt 里，通过宏定义传给代码：

// CMakeLists.txt
target_compile_definitions(mytool PRIVATE VERSION="${PROJECT_VERSION}")

// main.cpp
app.version(VERSION);

这样版本号只维护一份，不会出现代码和 CMake 里版本不一致的情况。

知识体系总览

下面这张图总结了 CLI11 的核心用法：

实战中的一些经验

最后分享几个我在实际项目中积累的经验：

参数命名要一致：整个项目里，短选项尽量用单个字母，长选项用连字符分隔的单词。比如 -i 和 --input-file，不要混用下划线和连字符。
校验要尽早：CLI11 在 CLI11_PARSE 时就会执行所有校验。如果校验失败，程序根本不会执行后续逻辑。这比在代码里手动检查要安全得多。
子命令别太多：我见过一个工具定义了 20 多个子命令，用户根本记不住。如果子命令超过 5 个，考虑用分组或者拆成多个工具。
帮助信息要详细：虽然 CLI11 自动生成帮助，但参数描述要写清楚。比如 "输出格式 (txt/csv/json)" 比 "输出格式" 有用得多。

避坑指南：我曾经在项目里用 add_option 定义了一个布尔参数，结果用户传了 --flag false，CLI11 把 false 当作字符串存进去了。后来改用 add_flag，布尔参数用开关形式，再也没出过问题。

CLI11 的文档很完善，遇到具体问题可以去 GitHub 上查。记住一点：命令行工具是给用户用的，参数设计要直观，错误提示要清晰。做到这两点，你的工具就成功了一半。

📚 课程目录

命令行参数解析：CLI11 库实战

为什么选 CLI11？

快速上手：一个简单的例子

参数校验：别让用户乱填

范围校验

自定义校验

正则校验

子命令：像 git 一样组织工具

自动生成帮助信息

知识体系总览

实战中的一些经验