在yargs中为默认命令添加描述的最佳实践

yargs是一个流行的Node.js命令行参数解析库，它提供了丰富的功能来构建命令行工具。在实际开发中，我们经常需要为CLI工具添加描述信息，但有时会遇到一些特殊需求。

默认命令描述的需求场景

当使用yargs构建CLI工具时，开发者可能希望：

1. 为整个工具添加一段描述性文字
2. 保持默认命令的行为不变
3. 不影响demandCommand等验证功能

常见误区

许多开发者会尝试使用.command()方法来定义默认命令的描述，但这会导致：

• 默认命令被显式定义
• demandCommand验证失效
• 需要额外处理默认命令逻辑

解决方案

yargs提供了.usage()方法，可以灵活地添加工具描述。最佳实践是：

await yargs(hideBin(process.argv))
  .strict()
  .demandCommand()
  .usage(`$0 <command>
  
The magical foobar CLI!
This tool helps you do amazing things with just a few commands.`)
  .command('foo', 'Foo', () => {}, () => {
    console.log("Foo");
  }).parseAsync()

这种方法的特点：

1. 保持默认命令行为不变
2. 不影响demandCommand验证
3. 可以添加多行描述文本
4. 描述会显示在帮助信息的顶部

进阶技巧

对于更复杂的描述需求，可以：

• 使用模板字符串保持格式整洁
• 添加版本信息或示例用法
• 结合epilogue方法添加脚注

.usage(`$0 <command>

${chalk.bold('项目名称')} v${packageJson.version}
${chalk.dim('一个强大的命令行工具')}

主要功能：
• 执行任务A
• 处理任务B
• 分析数据C`)

总结

在yargs中，.usage()方法是添加CLI工具描述的首选方式，它既保持了默认命令的原始行为，又能满足描述性需求。通过合理使用模板字符串和格式化工具，可以创建专业、易读的帮助信息。