Go Kong 的 passthrough 参数为什么保留后续原始输入

Go Kong 的 passthrough 会在指定的命令或位置参数边界停止继续解释后续标志，让后续输入成为交给下游的参数。它解决的是外层包装器与被包装工具争抢参数的问题。因此，进入透传范围后，--help、--format=json 或与外层同名的开关，都可能作为字符串保留下来。

项目官方地址：https://github.com/alecthomas/kong

认识透传能力与解析职责交接

这个能力适合用来理解命令行生态里的包装器设计：外层处理自己拥有的配置，下游解释自己的选项。这里讨论的是Kong已有的解析功能，不把它包装成新版本发布消息。

我更愿意把它理解为“交接解析职责”，而不是“宽松地忽略未知标志”。忽略未知标志可能会丢掉信息；透传的目的则是收集后续参数，让下一层自行决定它们是什么。是否调用下游程序，是拿到参数之后的业务行为，Kong不会因一个标签自动启动程序。

选择命令包装器的适用边界

如果一个子命令的全部剩余输入都要交给下游，我会优先选择命令级透传。官方约定要求这个命令只包含一个 []string 参数，由它收集命令之后未解析的内容。不要再往同一个透传命令里堆多个需要分别识别的位置字段。

另一种用法是在位置参数上声明 passthrough，让解析在到达该参数时停止继续识别标志。位置参数用法还有 all 和 partial 模式差异。两种声明位置不能笼统地归结为“从程序启动起所有参数都不解释”。

此外，“原始输入”指解析器接收到的参数元素，不是终端里敲下的整行字符。shell通常已经完成引号处理、变量展开等工作，再把argv交给程序。Kong没有办法从argv还原用户最初使用了单引号还是双引号。

用命令级passthrough观察参数

下面是一个只打印参数、不执行下游程序的完整例子。把它放进已配置 github.com/alecthomas/kong 依赖的Go模块，并把生成的程序命名为 argbridge。实际项目应固定适合自己的模块版本。

package main

import (
    "fmt"
    "os"
    "github.com/alecthomas/kong"
)

type CLI struct {
    Verbose bool `help:"显示外层诊断开关。"`
    Forward struct {
        // 命令级透传只保留一个字符串切片参数。
        Args []string `arg:"" optional:"" help:"交给下游的参数。"`
    } `cmd:"" passthrough:"" help:"收集参数，不启动任何程序。"`
}

func main() {
    var cli CLI
    parser, err := kong.New(&cli, kong.Name("argbridge"))
    if err != nil {
        fmt.Fprintln(os.Stderr, "定义错误:", err)
        os.Exit(1)
    }
    // 保留argv中的元素边界，不把输入拼成shell命令。
    if _, err := parser.Parse(os.Args[1:]); err != nil {
        fmt.Fprintln(os.Stderr, "参数错误:", err)
        os.Exit(1)
    }
    fmt.Printf("外层verbose=%t\n", cli.Verbose)
    for i, arg := range cli.Forward.Args {
        // %q让空格和引号等字符可辨认，输出是展示形式。
        fmt.Printf("下游参数[%d]=%q\n", i, arg)
    }
}

# --verbose位于forward之前，属于外层；其后各元素由透传命令收集。
./argbridge --verbose forward --format=json "two words" --verbose

按命令级透传规则，前面的 --verbose 设置外层字段；forward之后的三个参数元素应分别是 --format=json、two words、--verbose。最后这个同名标志属于Args，不会回头更新外层布尔值。

这个例子为了让边界容易辨认，特意把外层标志放在命令之前。本文没有执行代码，以上是规则推导的预期说明，不是实际输出记录。双引号让 two words 在常见shell中成为一个参数；引号本身通常不进入这个元素。

比较普通位置参数和partial模式

如果需求是“先解析外层选项，再从某个位置参数开始收集”，位置参数模式更合适；如果需求是“进入forward后全部属于下游”，命令级声明更直接。切换两者时，帮助文案也要说明用户应把外层选项放在哪里。

常见的 -- 也能表达结束标志解析，但不应把它与透传标签当成所有细节都相同的替换件。尤其准备把字面量双横线传给下游时，应针对所用声明位置和固定版本明确接口约定，不要在包装层随意删除所有双横线。

处理帮助参数与真实转交注意事项

若想看包装器帮助，应该在进入透传命令之前请求帮助；如果写在命令级透传范围内，帮助标志会作为下游参数保留。包装器界面最好明确区分“外层帮助”和“下游帮助”，否则用户容易误以为Kong的帮助功能坏了。

真正转交时，应保持参数切片的元素边界，不先拼成一条字符串再交给shell解释。字符串拼接会引入额外的拆词和解释问题，也容易把原本作为数据的字符变成另一层语法。本文仅展示收集过程，不授权任意执行能力。

透传不意味着数据不需要业务约束。包装器仍要决定允许哪个下游工具、参数数量和大小如何限制，以及日志是否需要隐藏敏感字段。不要把打印所有Args当成生产日志的默认策略；本文用公开演示输入，所以才逐项展示。

为什么后面的外层开关没有生效？

先看它是否已经位于透传范围内。进入命令级透传后，该开关是字符串数据，应移到命令之前才能由外层处理。

Args为什么没有保留用户输入的引号？

大多数情况下，引号由启动程序的shell解释，Kong拿到的是参数元素。需要保留字面量引号时，应按启动环境规则把引号作为参数内容传入。

开启透传后会自动执行命令吗？

不会。它负责解析和收集，后续行为由业务代码决定。先把参数边界说明清楚，再设计实际转交功能更容易维护。

技术依据：Kong官方标签说明、官方解析实现。