RustClapCLI参数解析最佳实践Skill rust-clap

---

名称: rust-clap 描述: Rust Clap CLI 参数解析最佳实践。此技能应用于编写、审查或重构使用 clap 的 Rust CLI 应用程序。触发任务涉及参数解析、CLI 设计、子命令和 Rust 中的命令行界面。

Rust Clap 最佳实践

全面最佳实践指南，用于使用 clap 构建 Rust 中的 CLI 应用程序。包含 8 个类别中的 42 条规则，按影响优先级排序，以指导 CLI 设计、参数解析和测试。

何时应用

参考这些指南当：

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

按优先级分类的规则类别

优先级	类别	影响	前缀
1	类型驱动设计	关键	type-
2	派生 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 - 使用 newtype 进行语义区分
• type-bool-flags - 对简单标志使用 bool

2. 派生 API 模式（关键）

• derive-parser-entry - 为 CLI 入口点派生 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	版本和参考信息