Cli——命令行
KernLab.Loom.Cli:[CommandGroup]/[Command] 标注一次,编译期生成三件套——CLI 解析器(Run/RunAsync)、
HTTP 执行代理(TryHandleAsync 单一入口 + 编译期路由表)、JSON I/O 契约。无 Handler 派发层。
可运行 sample:
samples/Cli/Commands(解析)、samples/Cli/HttpProxy(HTTP 代理)、samples/Cli/Completion(补全候选)。
从零跑通
[CommandGroup("traffic", Description = "流量管理")]
public sealed class TrafficCommands
{
[Command("list", Description = "列出规则")]
public Task<int> List([CommandOption("--filter")] string? filter = null, CancellationToken ct = default) => ...
}
// 生成 TrafficCommandsCli —— 直接当命令行入口
int exit = await TrafficCommandsCli.RunAsync(args);
一个方法标注一次 → 命令行解析、HTTP 代理、JSON 契约三件套同时生成。
声明命令
[CommandGroup("traffic", Description = "流量管理", DefaultExitCode = 2)]
public sealed class TrafficCommands
{
[Command("list", Description = "列出规则")]
public Task<int> List(
[CommandOption("--filter", ShortName = 'f')] string? filter = null,
[CommandOption("--all")] bool all = false) => ...;
[Command("create", Description = "新建")]
public Task<int> Create([CommandBody] CreateRequest body, CancellationToken ct = default) => ...;
[Command("delete", Description = "删除", Confirm = true)] // 执行前确认(生成 -y/--yes)
public Task<int> Delete([CommandArg("id")] Guid id) => ...;
}
绑定形态:
| 标注 | 绑定 |
|---|---|
[CommandArg("id")] |
位置参数(按声明序) |
[CommandOption("--name")] |
命名选项(--name value / --flag bool / ShortName) |
[CommandBody] |
JSON 请求体(HTTP 代理形态;CLI 下从 stdin 读) |
[CommandError] |
错误码 → 输出映射 |
组级 Options |
组级全局选项(#144——沿嵌套链对子命令可见) |
方法返回 Task<int> = 退出码;组可嵌套([CommandGroup] 内再放组 → 逐级路径匹配)。
生成物
| 生成物 | 用途 |
|---|---|
<Root>Cli.g.cs |
Run/RunAsync(解析→绑定→直调)、WriteHelp、CompleteNext(补全候选)、CommandPaths |
<Root>Http.g.cs |
TryHandleAsync 单一入口 + 编译期路由表(HTTP 执行代理) |
<Root>JsonContext / <Root>JsonResults |
JSON 序列化契约(AOT 安全) |
多根组互不知晓——聚合归宿主(首 token switch / 首段路由分发)。
诊断
KLSG054-067:路径冲突/非法命令名/参数未标注/不可绑定形态/GET 带 body/标注宿主非法/参数名占用保留前缀/组选项与子命令冲突等——全默认 Error。
明示不做(诚实边界)
| 能力 | 状态 | 理由 |
|---|---|---|
互斥组 / 必选选项组(Group/RequiresAny) |
不做 | 绑定面已足够表达常见 CLI;组语义需运行期交叉校验层,v1 明示边界 |
| shell 补全脚本生成(bash/zsh/powershell) | 不做 | CompleteNext 候选 API 供宿主补全循环消费;脚本模板留后续 |