SuperAPI AI 工具集

dotnet-cli-architecture

编程与开发

查看项目

更新于 10-16 09:46

技能介绍

用途:为 .NET CLI 工具提供分层架构指导,将 CLI 关注点拆为命令、处理程序、服务三层。命令层(System.CommandLine 的 RootCommand、Command、Option<T>)只负责解析参数与绑定选项;处理程序层(ICommandHandler)协调服务调用并格式化输出;服务层只含业务逻辑,不感知 CLI,便于测试与复用。适用于 .NET 8.0+、System.CommandLine 2.0 与泛型主机构建的 CLI 工具。

主要能力:遵循 clig.dev 原则,包括默认面向人类输出、提供 --json 机器可读输出、诊断与进度写 stderr、数据仅写 stdout、失败返回非零退出码、提前校验、尊重 NO_COLOR、支持 --verbose/--quiet。配置优先级由低到高为编译默认值、appsettings.json、appsettings.{Environment}.json、环境变量、CLI 参数。支持用户级配置(Linux/macOS 的 ~/.config/mycli/ 或 ~/.mycli/,Windows 的 %APPDATA%\mycli\,XDG 的 $XDG_CONFIG_HOME/mycli/)。日志通过 ClearProviders 与 AddConsole 的 LogToStandardErrorThreshold 写入 stderr,并可用 VerbosityMapping 将标志映射到日志级别。退出码约定:0 成功、1 通用错误、2 用法错误、3-9 通用类别、10+ 工具专属,且不超过 125。还涵盖 stdin 管道输入、--json 输出、进度的 stderr 输出,以及通过 CommandLineBuilder 与 TestConsole 进行进程内调用测试、捕获 stdout/stderr 并断言退出码。

限制与注意事项:不要将日志、进度、错误写入 stdout,以免破坏管道;不要把所有错误硬编码为退出码 1;不要把业务逻辑放进命令处理程序。System.CommandLine API 细节、Native AOT、CLI 分发与打包、通用 CI/CD、DI 容器内部与通用测试策略均不在本技能范围内,需参考相应其他技能。