Go Kong 怎样把结构体嵌套字段映射为子命令

如果你把 Kong 的结构体嵌套写出来，却发现帮助信息里只有一堆 flag，没有预期的子命令，通常不是嵌套层级太深，而是命令节点缺少 cmd:"" 标签。Kong 会根据 Go 类型和标签建立命令行结构：普通字段默认映射为 flag，标记为 cmd 的结构体字段才会成为命令节点。

官方文档：https://pkg.go.dev/github.com/alecthomas/kong

把结构体映射成子命令的关键是：每一级命令都在对应的嵌套结构体字段上加 cmd:""，叶子命令再用 Run() error 承接业务逻辑。全局参数放在根节点，某个命令专用的参数放在该命令结构体内。

症状先看清：嵌套字段为什么没有成为命令

典型场景是想得到 tool project create，代码却只声明了 Project 和 Create 两个普通结构体字段。Kong 看到没有 cmd 标签，就会按普通数据字段继续解析；字段中的可映射值可能表现为 flag，而不是命令路径。

排查时先回答三个问题：这个字段是不是结构体命令节点？它是否显式使用了 cmd:""？叶子节点是否有参数或 Run() error？不要先用字符串拼接去补救命令名称，先把类型树修正。

用 cmd 标签建立一级和二级命令

下面的结构把根命令、一级命令和二级命令分开。外层的 Project 与内层的 Create 都带 cmd:""，因此它们会形成连续的命令路径。字段名会参与生成默认命令名，如需更明确的名称，可以使用 name 标签。

package main

import (
    "fmt"

    "github.com/alecthomas/kong"
)

// CreateCmd 是叶子命令，专门承接 project create 的参数。
type CreateCmd struct {
    Name string `arg:"" name:"name" help:"项目名称"`
}

// ProjectCmd 是一级命令，内部字段继续用 cmd 标签声明子命令。
type ProjectCmd struct {
    Create CreateCmd `cmd:"" help:"创建一个项目"`
}

// CLI 的根字段放全局参数，Project 负责形成一级命令。
type CLI struct {
    Debug   bool       `help:"输出调试信息"`
    Project ProjectCmd `cmd:"" help:"项目相关操作"`
}

// Run 只属于叶子命令，参数已经由 Kong 写入 CreateCmd。
func (c *CreateCmd) Run() error {
    fmt.Printf("create project: %s\\n", c.Name)
    return nil
}

func main() {
    var cli CLI

    // Parse 建立命令树并把命令行参数写入 cli。
    ctx := kong.Parse(&cli)
    // Run 会调用当前选中的叶子命令方法，并返回业务错误。
    if err := ctx.Run(); err != nil {
        ctx.FatalIfErrorf(err)
    }
}

这段定义对应的路径是 project create 。Debug 没有 cmd 或 arg 标签，所以它是根级 flag；Name 带 arg，因此是 create 的位置参数。

触发条件：参数放错节点就会产生错觉

命令树正确以后，第二个常见误区是把参数放在错误的结构体里。一个字段只应该出现在它实际生效的节点：所有命令都需要的选项放在根结构体；只有 project 使用的选项放在 ProjectCmd；只服务 create 的输入放在 CreateCmd。

如果把 Name 放到根节点，Kong 就无法把它自然表达成 create 的位置参数；如果把只用于 create 的 flag 放在 ProjectCmd，兄弟命令也可能看到这个选项。先按命令边界分配字段，再决定是否需要 prefix 或 embed。

根因：cmd 决定节点，字段名只负责默认命名

这里最容易混淆的是“嵌套”和“命令”不是同一件事。Go 的嵌套结构体只提供了数据组织方式；Kong 是否把它视为命令节点，要看 cmd 标签。字段名通常只提供默认名称，不能替代命令标签。

因此可以把映射关系记成一句话：

• 结构体字段没有 cmd：继续作为普通字段或 flag 参与映射。
• 结构体字段有 cmd:""：生成一个命令节点，可以继续嵌套。
• 字段有 arg:""：成为该节点的位置参数，默认是必填的。
• 叶子结构体有 Run() error：选中该节点后，可交给 Context.Run() 执行。

修复动作：用 Run 方法承接叶子命令

小工具可以根据 ctx.Command() 做字符串分支，但命令树一旦调整，字符串也可能随之改变。更稳定的方式是让每个叶子命令实现自己的 Run() error，解析完成后调用 ctx.Run()。这样命令结构负责声明，业务方法负责执行，二者边界更清楚。

如果叶子命令还需要共享配置，可以通过 Run 方法参数、kong.Bind 或上下文绑定注入；不要为了传一个全局值，把所有参数复制到每个子命令结构体中。这样既保持命令帮助信息简洁，也避免多个节点出现同名但含义不同的字段。

防复发：用帮助输出检查命令树

修改结构体后，先查看顶层帮助，再查看子命令帮助。重点不是比对某一段完整输出，而是确认层级和归属：

1. 顶层帮助中能看到 project，而不是只看到 project 的字段列表。
2. project 的帮助中能看到 create，且只出现该分支需要的参数。
3. create 的帮助中能看到位置参数 或预期的 flag。
4. 实际调用 ctx.Run() 后，业务代码只在选中的叶子命令上执行。

还要特别注意默认命令标签：Kong 支持用 default:"1" 让没有进一步参数时选择某个命令，也支持 default:"withargs" 让命令在存在可匹配参数时成为默认分支。默认命令会改变用户输入的解析路径，最好只在兄弟命令不会产生歧义时采用。

最后整理：一张表记住嵌套映射

所以，Go Kong 把嵌套结构体映射为子命令的最小修复不是增加更多解析代码，而是把命令边界写回类型：命令节点加 cmd，参数放在正确层级，叶子节点用 Run 执行。按这个顺序检查，通常就能快速定位“结构体已经嵌套但帮助里没有子命令”的问题。

相关问题

• Kong 的普通字段为什么会自动变成 flag？
• 怎样给 Kong 子命令添加可选的位置参数？
• 多个子命令需要共享配置时，应该使用 Bind 还是复制字段？
• 什么时候适合用 default:"1" 设置默认命令？