Go go-flags 怎样把 INI 配置加载进命令参数

如果命令行程序既要支持 --port 8080，又要允许用户把配置写进 INI 文件，go-flags 已经提供了对应的解析器。核心做法是：把命令参数定义在一个结构体里，用 flags.NewParser 创建解析器，再用 flags.NewIniParser(parser).ParseFile 读取配置。INI 的 section 默认写成 [Application Options]，键名可以通过 ini-name 标签固定下来。

官方地址：https://github.com/jessevdk/go-flags/

最实用的组合是先把 INI 作为默认配置读入结构体，再调用命令行解析；这样文件负责稳定配置，命令行只覆盖本次启动需要调整的选项。若只需要一次性读取文件，也可以使用 flags.IniParse 这个便捷函数。

先把命令参数和 INI 键名放进同一个结构体

go-flags 通过反射读取字段标签。long 和 short 决定命令行写法，ini-name 决定 INI 中更稳定、可读的键名；如果不写 ini-name，解析器还会按字段名、长选项名、短选项名依次尝试匹配。

package main

import "github.com/jessevdk/go-flags"

// Options 是命令行和 INI 共用的配置对象。
type Options struct {
	Host    string   `long:"host" default:"127.0.0.1" ini-name:"listen-host" description:"监听地址"`
	Port    int      `long:"port" default:"8080" ini-name:"listen-port" description:"监听端口"`
	Debug   bool     `long:"debug" ini-name:"debug" description:"开启调试日志"`
	Profile []string `long:"profile" ini-name:"profile" description:"重复出现时保留多个配置"`
}

func main() {
	var opts Options
	parser := flags.NewParser(&opts, flags.Default)
	iniParser := flags.NewIniParser(parser)
	_ = iniParser // 后续先读取 INI，再解析命令行参数
}

这里的 Profile []string 用来展示重复键：同名键出现多次时，切片可以保留多个值。配置文件中的键名应优先使用 ini-name 约定，避免未来重命名 Go 字段后破坏已有配置。

用 IniParser 读取 Application Options

默认选项组名是 Application Options，因此最小 INI 文件可以这样写：

; app.ini：注释行可以使用分号或井号
[Application Options]
listen-host = "0.0.0.0"
listen-port = 9090
debug = true
profile = "api"
profile = "metrics"

读取文件时要检查返回错误。ParseFile 可能返回文件读取错误、字段转换错误或带文件名和行号的 flags.IniError，不要把错误直接吞掉。

func loadINI(path string, opts *Options) error {
	// 使用同一个解析器描述 Options，保证 INI 键和命令行选项共享定义。
	parser := flags.NewParser(opts, flags.Default)
	iniParser := flags.NewIniParser(parser)
	if err := iniParser.ParseFile(path); err != nil {
		// IniError 会带出文件和行号，适合直接交给启动日志。
		return err
	}
	return nil
}

如果配置文件里的值不符合字段类型，例如把 listen-port 写成无法转换为整数的文本，错误会在这里返回。section 名称还可以对应命令或分组，嵌套时使用点号命名空间。

让命令行覆盖配置文件中的默认值

很多程序需要“文件给默认值，命令行给临时覆盖”。这时要把 INI 解析放在命令行解析之前，并让命令行解析同一个结构体：

func parseOptions(args []string, configPath string) (Options, []string, error) {
	var opts Options
	parser := flags.NewParser(&opts, flags.Default)
	iniParser := flags.NewIniParser(parser)
	if err := iniParser.ParseFile(configPath); err != nil {
		return opts, nil, err
	}

	// 命令行参数在 INI 之后设置，因此同名选项可以覆盖文件值。
	rest, err := parser.ParseArgs(args)
	if err != nil {
		return opts, nil, err
	}
	return opts, rest, nil
}

在这个组合中，配置文件里的 listen-port = 9090 会先写入 opts.Port，随后传入 --port 8081 时，命令行解析再次设置该字段。要注意，INI 解析和命令行解析依赖同一个 Parser，不要为两者分别创建结构体，否则覆盖关系不会落在同一份状态上。

如果希望 INI 内容只作为解析器默认值，可将 iniParser.ParseAsDefaults 设为 true。这种模式适合还要保留结构体标签中的默认值和其他来源默认值的场景，但必须明确每个默认值的优先级，避免把“配置文件覆盖默认值”和“配置文件直接设置当前值”混为一谈。

分组、重复键和显式键名怎么处理

go-flags 的 INI section 对应选项组或命令。默认结构体对应 [Application Options]；通过 AddGroup 或 AddCommand 增加的组可以使用组名，嵌套命令使用点号连接。section 名称匹配时不区分大小写，但选项名最好保持统一小写风格。

键名匹配顺序是 ini-name、结构体字段名、long 名称、short 名称。生产配置建议总是写 ini-name，这样 Go 字段可以从 Port 调整为更具体的内部命名，而旧配置仍然稳定。对于切片或 map，可以重复写键，map 的值则遵循 go-flags 对键值分隔符的处理规则。

需要把当前配置写回 INI 时怎么做

除了读取，go-flags 还提供 Write 和 WriteFile。这适合生成配置模板、导出当前选项或保存用户调整后的配置。

func saveINI(path string, opts *Options) error {
	// 写出时复用完整 Parser，输出的 section 和 ini-name 与读取规则一致。
	parser := flags.NewParser(opts, flags.Default)
	iniParser := flags.NewIniParser(parser)
	return iniParser.WriteFile(path, flags.IniIncludeComments)
}

IniIncludeComments 会把字段描述写成配置注释。如果要连同默认值一起输出，可以组合 flags.IniIncludeDefaults；如果只想写当前非默认值，则保留默认的写出选项。保存文件失败时，WriteFile 会返回打开或写入相关错误。

启动前的速查清单

归纳起来，go-flags 的 INI 支持不是另一套独立配置模型，而是把文本 section 和键值映射到已有选项组。只要结构体标签、section 名和解析顺序固定，配置文件与命令行就能共同服务同一个参数对象。

相关问题

INI 中可以直接写 long 选项名吗？

可以，解析器会依次尝试显式 ini-name、字段名、long 名和 short 名；为了避免重命名造成歧义，长期维护的配置仍建议使用显式键名。

未知 section 会怎样？

默认情况下会返回未知选项组错误。只有明确需要兼容扩展配置时，才考虑创建带 flags.IgnoreUnknown 的解析器，并记录被忽略的内容。

为什么命令行没有覆盖 INI？

优先检查是否复用了同一个 Options 和 Parser，以及是否在 ParseFile 之后才调用 ParseArgs。分别创建解析器或反过来调用，都会让预期的覆盖关系变得不清晰。