Go INI 怎样保留重复键的多个值

Go INI 读取同一节里的重复键时，关键不是把键名改成数组，而是使用带 shadow 能力的加载方式。最小写法是 ini.ShadowLoad，再通过 ValueWithShadows() 取回多个值；如果连完全相同的重复值也不能去重，则改用 LoadSources 明确打开 AllowDuplicateShadowValues。

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

同名键被覆盖时，问题通常出在加载入口

故障现场往往是一份配置里有多个后端地址：

[server]
endpoint = https://api-a.example
endpoint = https://api-b.example

如果沿用普通加载路径再调用 Key("endpoint").String()，得到的是单个字符串视图，调用方自然无法把它当成多个地址消费。这里的根因不是 Go 的切片转换失败，而是加载时没有要求 go-ini 记录同名键的 shadow 值。

ShadowLoad 让同名键不再互相覆盖

go-ini 提供了针对这个场景的 ShadowLoad。它的职责是保留同一 section 下同名键的多个原始值；读取时再从同一个 Key 上取得主值和 shadow 值：

package main

import (
	"fmt"

	ini "gopkg.in/ini.v1"
)

func main() {
	// 用原始字节加载配置，示例中同名 endpoint 代表多个后端地址。
	cfg, err := ini.ShadowLoad([]byte(`
[server]
endpoint = https://api-a.example
endpoint = https://api-b.example
`))
	if err != nil {
		// 解析失败时立即返回，避免把不完整配置交给后续逻辑。
		panic(err)
	}

	// ValueWithShadows 返回主值与 shadow 值组成的字符串切片。
	values := cfg.Section("server").Key("endpoint").ValueWithShadows()
	fmt.Println(values)
}

这里的 values 是按配置出现顺序组织的多个值。图中的“主值”和“shadow 值”属于同一个 Key 的静态存储关系，说明图只解释数据结构，不是终端运行截图。

ValueWithShadows 与 StringsWithShadows 的取值边界

ValueWithShadows() 取的是原始字符串集合，并且会忽略空值。若配置格式允许每一行还携带逗号分隔的多个地址，可以使用 StringsWithShadows(",")，它会先合并 shadow 值，再对每个值做分隔。

import (
	"fmt"

	ini "gopkg.in/ini.v1"
)

// readEndpoints 只负责读取配置，不在这里做连通性检查。
func readEndpoints(cfg *ini.File) ([]string, error) {
	key, err := cfg.Section("server").GetKey("endpoint")
	if err != nil {
		// 缺少 endpoint 时返回明确错误，让调用方决定是否使用默认地址。
		return nil, fmt.Errorf("读取 server.endpoint: %w", err)
	}

	// 每个重复键都可能包含逗号列表，例如 "a,b"；这里统一展开。
	values := key.StringsWithShadows(",")
	if len(values) == 0 {
		return nil, fmt.Errorf("server.endpoint 没有可用值")
	}
	return values, nil
}

两者不要混用语义：只想保留每行原文时用 ValueWithShadows；想把每行里的列表也展开时用 StringsWithShadows。空字符串会被前者忽略，因此“键存在”和“读到一个空地址”不是同一件事。

完全相同的重复值要不要去重

第一次修复后，另一个现象可能出现：endpoint = https://api-a.example 写了两次，返回切片里却只有一份。原因是 go-ini 默认会对 shadow 值按内容去重。如果重复次数本身有业务意义，就要同时打开两个选项：

package main

import (
	"fmt"

	ini "gopkg.in/ini.v1"
)

func loadAllOccurrences(data []byte) ([]string, error) {
	// AllowShadows 记录同名键；AllowDuplicateShadowValues 保留相同文本的重复项。
	cfg, err := ini.LoadSources(ini.LoadOptions{
		AllowShadows:               true,
		AllowDuplicateShadowValues: true,
	}, data)
	if err != nil {
		return nil, fmt.Errorf("加载 INI: %w", err)
	}

	// 读取结果仍然来自同一个 Key，调用方不需要自己扫描原始文本。
	return cfg.Section("server").Key("endpoint").ValueWithShadows(), nil
}

如果重复值只是配置合并过程中偶然产生的副本，默认去重更安全；如果你要表达“同一个地址被声明了三次”或依赖出现次数，就显式开启该选项，并在业务层决定是否继续去重。

用四个检查点防止重复键问题复发

• 加载入口：确认代码调用的是 ShadowLoad，或 LoadSources 是否设置了 AllowShadows。
• 读取方法：需要多个原始值时，不要只调用 String()；需要拆分内部列表时再选择 StringsWithShadows。
• 重复策略：先判断同值重复是否有业务含义，再决定是否打开 AllowDuplicateShadowValues。
• 配置约定：如果团队不希望依赖重复键语义，也可以改用 endpoint.1、endpoint.2 或单个逗号列表，但要在格式说明中固定下来。

最终的修复边界很清楚：ShadowLoad 负责让同名键留下来，ValueWithShadows 负责把它们读成切片，AllowDuplicateShadowValues 负责决定相同文本是否保留多次。三者分别解决保存、读取和去重，不要把它们当成同一个开关。

常见问题

只把一个字符串改成 []string 就能读到重复键吗？

不能。重复键是否被保留发生在加载阶段，必须先启用 shadow 能力，再通过对应的读取方法取得多个值。

ValueWithShadows 会返回空值吗？

它会忽略空值。如果空值本身需要表达业务状态，应在配置约定中使用明确的占位文本，或改用带序号的键名保存该状态。

什么时候应该不用重复键？

当配置需要被多种语言或多种解析器共同消费时，显式列表键通常更直观；重复键方案更适合已经确定使用 go-ini 且需要兼容既有 INI 文件的场景。