rust-clap

Rust Clap 最佳实践

使用 clap 构建 Rust 命令行应用的全面最佳实践指南。包含 8 个类别中的 42 条规则，并按影响排序，为命令行应用设计、参数解析和测试提供指导。

适用场景

请在以下场景中参考这些指南：

• 设计新的 Rust 命令行应用
• 为现有命令行应用添加参数或子命令
• 验证和解析命令行输入
• 为命令行工具编写集成测试
• 改进帮助文本和用户体验

按优先级划分的规则类别

优先级	类别	影响	前缀
1	类型驱动设计	关键	type-
2	Derive API 模式	关键	derive-
3	参数配置	高	arg-
4	验证与解析	高	valid-
5	子命令架构	中高	subcmd-
6	帮助与文档	中	help-
7	错误处理	中	error-
8	测试模式	中低	test-

快速参考

1. 类型驱动设计（关键）

• type-valueenum-enums - 使用 ValueEnum 表示枚举参数
• type-option-optional - 对真正可选的参数使用 Option
• type-pathbuf-files - 对文件系统参数使用 PathBuf
• type-vec-multiple - 对包含多个值的参数使用 Vec
• type-newtype-semantic - 使用新类型区分不同语义
• type-bool-flags - 对简单标志使用 bool

2. Derive API 模式（关键）

• derive-parser-entry - 为命令行入口派生 Parser
• derive-command-metadata - 使用 Command 属性提供元数据
• derive-subcommand-enum - 使用 Subcommand 派生宏构建命令层级
• derive-args-reusable - 派生 Args 以创建可复用的参数组
• derive-doc-comments - 使用文档注释编写帮助文本
• derive-global-options - 使用 Global 设置跨子命令选项
• derive-propagate-version - 将版本信息传递给子命令

3. 参数配置（高）

• arg-default-value - 使用 default_value 设置合理的默认值
• arg-env-fallback - 使用 env 设置环境变量回退值
• arg-short-long - 同时提供短选项名和长选项名
• arg-conflicts-with - 使用 conflicts_with 设置互斥选项
• arg-requires - 使用 requires 设置依赖参数
• arg-value-name - 使用 value_name 设置描述性占位符

4. 验证与解析（高）

• valid-value-parser - 使用 value_parser 进行自定义验证
• valid-possible-values - 使用 PossibleValuesParser 限制字符串取值
• valid-fromstr-types - 为领域类型实现 FromStr
• valid-try-parse - 使用 try_parse 优雅地处理错误
• valid-num-args - 使用 num_args 限制值的数量

5. 子命令架构（中高）

• subcmd-nested-hierarchy - 为复杂的 CLI 使用嵌套子命令
• subcmd-args-struct - 使用结构体定义子命令参数
• subcmd-required-help - 要求提供子命令，否则显示帮助
• subcmd-arg-groups - 使用 ArgGroup 实现多选一要求
• subcmd-external - 使用外部子命令构建插件系统

6. 帮助与文档（中）

• help-shell-completions - 使用 clap_complete 生成 Shell 补全
• help-next-heading - 使用 next_help_heading 组织帮助信息
• help-after-help - 使用 after_help 提供示例和上下文
• help-hide-options - 在默认帮助信息中隐藏高级选项

7. 错误处理（中）

• error-exit-codes - 使用恰当的退出代码
• error-context - 为错误消息添加上下文
• error-suggestions - 启用拼写错误建议
• error-color-styles - 使用彩色输出让错误更醒目

8. 测试模式（低至中）

• test-assert-cmd - 使用 assert_cmd 进行集成测试
• test-predicates - 使用 predicates 灵活地进行断言
• test-temp-files - 使用 assert_fs 创建临时测试文件
• test-parse-from - 使用 parse_from 对解析器进行单元测试
• test-trycmd-snapshots - 使用 trycmd 进行快照测试

使用方法

阅读各参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息