Go Kong 怎样让环境变量提供命令行选项默认值

用 Go Kong 做命令行工具时，常见需求是让部署环境通过环境变量提供一个“默认值”，同时保留命令行参数的临时覆盖能力。最直接的做法是在字段标签里写 env:"APP_PORT"；如果希望按旗标名批量生成环境变量，则给解析器加上 kong.DefaultEnvars("APP")。环境变量只参与默认初始化，真正的命令行参数仍可以覆盖它。

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

先把环境变量接到 Kong 的字段上

一个稳定的 CLI 通常把外部配置名写进 env 标签，把内置兜底值写进 default 标签。下面的 Port 使用显式环境变量，Verbose 则交给 DefaultEnvars 自动生成 APP_VERBOSE。

package main

import (
    "fmt"

    "github.com/alecthomas/kong"
)

type CLI struct {
    Port    int  `name:"port" env:"APP_PORT" default:"8080" help:"监听端口"`
    Verbose bool `name:"verbose" help:"输出详细日志"`
}

func main() {
    var cli CLI
    // DefaultEnvars 只为没有显式 env 标签的旗标补出 APP_ 前缀名称。
    ctx := kong.Parse(&cli, kong.DefaultEnvars("APP"))
    _ = ctx // 解析上下文可继续用于执行命令或打印帮助
    fmt.Printf("port=%d verbose=%t\n", cli.Port, cli.Verbose)
}

官方文档给出的规则是：--some.value 在 DefaultEnvars("PREFIX") 下可以生成 PREFIX_SOME_VALUE。生成动作会跳过已经声明了 env 的字段，也可以用 env:"-" 禁止自动生成。

环境变量、default 和命令行谁优先

不要把环境变量理解成“另一种命令行参数”。Kong 的字段重置阶段会先清零目标字段，然后按 env 标签列出的顺序查找环境变量；找到一个已存在的值后就用对应 Mapper 解析。若没有环境变量，才继续处理 default 标签。之后解析到的命令行参数再应用到字段上，所以临时命令行输入通常拥有更高优先级。

type CLI struct {
    Port int `name:"port" env:"APP_PORT" default:"8080" help:"监听端口"`
}

func parse() *CLI {
    var cli CLI
    // 环境变量可提供部署默认值，命令行 --port 可在本次启动时覆盖它。
    kong.Parse(&cli)
    return &cli
}

这里的关键不是再注册一个复杂的 Resolver，而是让字段的来源有明确边界：部署系统设置 APP_PORT，操作者需要临时改变端口时使用 --port 9000。如果多个环境变量写在同一个 env:"APP_PORT,PORT" 标签里，Kong 按声明顺序选择第一个已找到的名称，顺序本身就是配置协议的一部分。

真正容易踩坑的是空值和自动命名

环境变量的值始终先以字符串进入 Kong。对 string 字段，空字符串可能就是一个合法值；对 int、bool 等字段，空字符串会在 Mapper 解析阶段变成错误。因此，部署脚本不能只判断“变量名存在”，还要保证值符合字段类型。

自动命名也要有边界意识。DefaultEnvars("APP") 会把旗标名中的连字符和点转换成下划线，再拼接前缀并转成大写；它适合内部命名稳定的工具。对已经对外发布的环境变量，建议显式写 env 标签，避免后续重命名字段或调整嵌套结构时悄悄改变环境变量名。

type CLI struct {
    Port int `name:"port" env:"APP_PORT" default:"8080"`
}

func parseCLI() (*CLI, error) {
    var cli CLI
    // 让解析错误回到调用方，避免把非法 APP_PORT 当成零值继续启动。
    if _, err := kong.New(&cli); err != nil {
        return nil, err
    }
    return &cli, nil
}

上面的片段只强调构建阶段的错误边界；实际解析仍应使用 kong.Parse 或显式创建 Kong 后调用其解析方法，并对返回的上下文错误进行处理。生产代码要把“变量未设置”和“变量已设置但格式错误”区分开，否则排查时很容易把配置问题误判成业务逻辑问题。

按外部契约选择写法

1. 环境变量名已经对外约定时，显式写 env:"APP_PORT"，不要依赖结构体字段自动推导。
2. 一组内部工具需要统一前缀时，使用 DefaultEnvars("APP")，并检查旗标名变化是否会改变生成结果。
3. 只把环境变量当作默认来源；需要本次启动强制覆盖时，让用户使用命令行参数。
4. 为整数、布尔、切片等非字符串字段保留解析错误路径，并在部署配置中拒绝空值。

最终可以把 Kong 的来源关系概括为：字段标签定义契约，环境变量提供部署默认值，default 提供代码兜底，命令行负责本次调用的显式覆盖。这样配置命名、优先级和错误处理都能独立演进。

常见问题

DefaultEnvars 会覆盖显式的 env 标签吗？

不会。官方实现会跳过已经存在环境变量声明的旗标，所以显式 env 名称仍然是优先的外部契约。

环境变量和 default 同时存在时使用哪个？

只要声明的环境变量已存在，就先用它；没有找到环境变量时才退回 default。命令行参数随后可以覆盖这两类默认来源。

怎样避免字段重命名导致环境变量失效？

对已经被部署脚本使用的名称显式写 env 标签，并把名称当成兼容性契约；自动生成的名称更适合尚未对外承诺的内部工具。