cli-building

CLI 构建

采用现代模式和最佳实践构建命令行界面的指南。

适用场景

• 创建新的 CLI 工具或命令
• 构建交互式终端应用
• 为现有项目添加命令
• 实现命令行界面
• 使用 CLI 框架

核心原则

• 异步优先：所有 I/O 操作都应使用 async/await，避免阻塞操作
• 可组合命令：命令应模块化且可复用，并使用命令组合
• 策略模式：对于分支工作流或基于任务的命令，使用策略模式
• 输出格式：正确格式化输出，并支持 Unicode 符号和颜色

框架选择

TypeScript/JavaScript

stricli（@bloomberg/stricli，推荐用于现代异步优先的 CLI）：

• 从设计之初就支持 async/await
• 类型安全的命令定义，并支持完整的类型推断
• 延迟加载以提升启动性能
• 零依赖

oclif（替代方案）：

• 成熟的框架，功能丰富
• 插件系统
• 适用于复杂的 CLI

Python

cyclopts（异步优先场景推荐）：

• 现代的异步优先 CLI 框架
• 类型安全，异步支持出色
• API 设计简洁

typer（提供完整异步支持时使用）：

• 基于 Python 类型提示
• 简洁直观
• 适用于简单到中等复杂度的 CLI

命令架构

可组合命令

将命令设计为可复用的模块：

• 共享命令实用工具
• 命令中间件
• 可复用的命令模块
• 命令组合模式

策略模式

在以下场景中使用策略模式：

• 工作流分支
• 基于任务的命令
• 动态命令路由
• 条件命令执行

输出格式

• 不使用表情符号：除非明确要求，否则不要使用表情符号
• Unicode 符号：使用 Unicode 符号（✓、✗、→、⚠）作为状态指示符
• 颜色支持：使用颜色库，绝不硬编码 ANSI 代码
• NO_COLOR：始终遵循 NO_COLOR 环境变量
• 格式化：使用格式化提升可读性（粗体、暗色等）

异步模式

异步优先设计

所有 I/O 都应采用异步方式：

• 文件操作：使用异步文件 API
• 网络请求：使用异步 HTTP 客户端
• 进程执行：使用异步进程 API
• 数据库操作：使用异步数据库客户端

错误处理

妥善处理异步错误：

• 使用带 await 的 try/catch
• 处理 Promise 拒绝
• 提供清晰的错误消息
• 使用适当的退出码退出

命令结构

基本命令

// stricli example
import { createCli } from '@bloomberg/stricli';

async function myCommand() {
  // Async implementation
}

const cli = createCli({
  name: 'my-cli',
  commands: {
    'my-command': myCommand
  }
});

cli.run();

# cyclopts example
from cyclopts import App

app = App()

@app.default
async def my_command():
    # Async implementation
    pass

if __name__ == '__main__':
    app()

最佳实践

1. 默认采用异步：所有操作都应为异步
2. 可组合设计：构建可复用的命令模块
3. 策略模式：用于工作流分支
4. 正确格式化：使用 Unicode 符号和颜色，并支持 NO_COLOR
5. 错误处理：提供清晰的错误消息和退出码
6. 类型安全：使用 TypeScript 类型或 Python 类型提示
7. 测试：单独测试各个命令

参考资料

如需详细指南，请参阅：

• references/async-patterns.md - Async/await 最佳实践
• references/composable-commands.md - 命令组合模式
• references/strategy-pattern.md - 工作流策略模式
• references/output-formatting.md - 输出格式指南
• references/frameworks.md - 框架比较与选择