Go Kong 的 Bind 与命令 Run 参数注入有什么区别

Go Kong 里的 kong.Bind(...) 和 ctx.Run(...) 都能给命令的 Run() 方法提供参数，但它们解决的不是同一个生命周期问题：Bind 在构造解析器时登记依赖，适合日志器、配置服务这类稳定对象；ctx.Run 在命令已经解析、准备执行时传入本次调用的值，适合请求级上下文、输出目标或临时运行参数。两者不是“谁功能更多”的关系，而是依赖来源和作用域不同。

官方地址：https://pkg.go.dev/github.com/alecthomas/kong

选型可以记成一句话：启动解析器时就确定、多个命令都可能用到的依赖放进 kong.Bind；只有本次执行才确定，或希望调用者明确传入的值放进 ctx.Run。命令结构本身也会自动参与注入，所以不要把同一个 CLI 根节点再重复绑定成另一份实例。

先看两种注入发生在什么时候

kong.Parse 会根据结构体和命令行参数得到一个 Context。如果在解析时传入 kong.Bind(logger)，这个值会登记到解析器的绑定集合里，钩子和后续的 Run 都可以请求它。相反，ctx.Run(runtime) 的参数只在调用该方法时加入本次执行的绑定集合，适合由上层调度器临时决定的值。

用同一个命令看 Bind 和 Run 的区别

下面的命令同时声明了一个 CLI 根节点、一个由 Bind 提供的日志器，以及一个在执行时传入的 RunOptions。代码中的注释只标出关键注入点，便于把“命令行解析”与“运行时依赖”分开。

package main

import (
    "fmt"
    "log"

    "github.com/alecthomas/kong"
)

type CLI struct {
    Verbose bool `help:"显示详细日志"`
    Serve   ServeCmd `cmd:""`
}

type ServeCmd struct {
    Port int `default:"8080" help:"监听端口"`
}

type RunOptions struct {
    DryRun bool
}

// Run 同时接收命令树父节点、Bind 值和 ctx.Run 的单次值。
func (s *ServeCmd) Run(cli *CLI, logger *log.Logger, opts RunOptions) error {
    if cli.Verbose {
        logger.Printf("准备监听端口 %d", s.Port)
    }
    if opts.DryRun {
        fmt.Printf("dry-run: port=%d\\n", s.Port)
        return nil
    }
    fmt.Printf("listen: port=%d\\n", s.Port)
    return nil
}

func main() {
    var cli CLI
    logger := log.Default()

    // Bind 在 Parse 阶段登记稳定依赖，Run 方法可以直接请求 *log.Logger。
    ctx := kong.Parse(&cli, kong.Bind(logger))

    // RunOptions 只属于这一次执行，由调用者显式传入。
    err := ctx.Run(RunOptions{DryRun: true})
    ctx.FatalIfErrorf(err)
}

这里的 *CLI 来自 Kong 的命令树父节点，不需要再次写成 kong.Bind(&cli)。*log.Logger 来自解析阶段的 kong.Bind(logger)；RunOptions 则来自 ctx.Run。三种来源都能进入 Run，但维护责任不同。

什么时候把值放进 Bind

适合放进 Bind 的通常是跨命令共享、创建时已经确定的依赖，例如日志器、配置读取器、指标注册器或一个不会因本次命令而改变的服务容器。这样做的好处是命令的 Run 签名直接表达所需依赖，测试时也可以传入替身。

如果依赖是接口，不要为了满足类型匹配把具体实现硬编码到命令里，可以用 BindTo：

type Store interface {
    Save(string) error
}

type FileStore struct{}

func (FileStore) Save(name string) error {
    // 示例只演示注入关系，真实实现应处理文件错误。
    fmt.Println("save", name)
    return nil
}

func main() {
    var cli CLI
    store := FileStore{}

    // 将具体实现绑定为 Store 接口，Run 可声明接口而非具体类型。
    ctx := kong.Parse(&cli, kong.BindTo(store, (*Store)(nil)))
    _ = ctx
}

需要按依赖图懒创建时，则考虑 kong.BindToProvider。它允许 Kong 根据已绑定参数调用提供函数；但如果对象需要请求级数据，就不要把它藏在解析器级 provider 中，应让 ctx.Run 显式携带请求级值。

什么时候把值放进 ctx.Run

ctx.Run 更像一次执行的边界。比如同一个解析上下文被测试重复运行，或者调度层根据环境选择不同的输出器，可以这样传入：

type Output struct {
    Name string
}

func (s *ServeCmd) Run(out Output) error {
    // 输出目标来自本次调用，不能假设 Parse 时已经固定。
    fmt.Println("target:", out.Name)
    return nil
}

// 伪代码：每次 Run 都可以选择不同的执行参数。
func runOnce(ctx *kong.Context, name string) error {
    return ctx.Run(Output{Name: name})
}

这种方式能让调用点看见实际运行参数，也避免把会变化的状态保存到全局变量。需要注意的是，ctx.Run 不是用来替代命令行字段的：端口、文件路径这类用户输入仍应定义在 CLI 结构体中，让 Kong 负责解析和校验。

按依赖来源做选择

最常见的坑是把两种绑定混成“全局变量注入”。实际上，Bind 适合稳定依赖，Run 适合执行参数；同名或同类型值同时存在时，应让调用处只保留一种来源，避免读者无法判断最终使用的是哪一个对象。

Go Kong 注入常见问题

Run 方法能直接拿到 CLI 根节点吗？

可以。Kong 会把选中命令路径上的父节点作为可绑定值，所以命令可以声明对应的父结构体指针，不必重复绑定同一个 CLI 实例。

Bind 只能给 Run 方法提供参数吗？

不能。官方文档同时把它用于钩子和 Run 参数；如果值只在一次调用时有效，使用 ctx.Run 会更容易看出它的作用域。

ctx.Run 传入的值会自动覆盖 Bind 的同类型值吗？

不要依赖“覆盖”来设计程序。两者都属于绑定来源，应该避免同一类型承担两个含义；需要区分时可定义专用类型或结构体，让签名表达真实依赖。

把 Kong 的绑定看成一张依赖图就不容易选错：命令树提供结构化 CLI 数据，Bind 提供解析器级稳定依赖，ctx.Run 提供本次执行参数。先按生命周期分层，再决定是否使用接口绑定，代码会比把所有值塞进一个上下文更清楚。