koanf 是一个专门用于 Go 应用程序中从各种来源和格式读取配置的库。它被设计为流行的 spf13/viper 的一个更清晰、更轻量级的替代品，具有更好的抽象性、可扩展性以及显著更少的依赖项。koanf v2 通过模块化设计，将配置的 Provider（提供者） 和 Parser（解析器） 解耦，使得配置管理更加灵活。
koanf 核心概念与安装
核心概念
koanf 的核心功能基于两个通用接口：Provider 和 Parser。
koanf.Provider：这是一个通用接口，用于提供配置，例如从文件、环境变量、S3 或 Vault 中获取配置。配置可以是以原始字节的形式返回，供解析器（Parser）处理，或者可以直接返回一个嵌套的map[string]interface{}，供 koanf 直接加载。koanf.Parser：这是一个通用接口，它接受原始字节，进行解析，并返回一个嵌套的map[string]interface{}。例如，JSON 和 YAML 解析器就属于此类。
配置一旦加载到 koanf 实例中，就可以通过一个带分隔符的键路径语法进行查询，例如 app.server.port。您可以选择任何字符作为分隔符。
安装
安装 koanf 核心库和所需的模块（Provider 和 Parser）是分开进行的，因为所有外部依赖项都与核心库分离。
# 1. 安装核心库
go get -u github.com/knadh/koanf/v2
# 2. 安装必要的 Provider(s)。例如：文件提供者
go get -u github.com/knadh/koanf/providers/file
# 3. 安装必要的 Parser(s)。例如：TOML 解析器
go get -u github.com/knadh/koanf/parsers/toml
koanf 的详细使用方法及代码示例
Koanf 允许从多个来源加载配置并将其合并到一个实例中，例如先加载文件配置，然后使用命令行标志覆盖某些值。我们初始化一个全局 koanf 实例，并使用 . 作为键路径分隔符：
import "github.com/knadh/koanf/v2"
// Global koanf instance. Use "." as the key path delimiter.
var k = koanf.New(".")
1. 从文件读取配置
使用 file.Provider 读取文件，并结合相应的 Parser（例如 json.Parser 或 yaml.Parser）将原始字节解析为嵌套 Map。
以下示例展示了如何加载 JSON 配置，然后合并加载 YAML 配置：
package main
import (
"fmt"
"log"
"github.com/knadh/koanf/v2"
"github.com/knadh/koanf/parsers/json"
"github.com/knadh/koanf/parsers/yaml"
"github.com/knadh/koanf/providers/file"
)
var k = koanf.New(".")
func main() {
// 加载 JSON 配置。
if err := k.Load(file.Provider("mock/mock.json"), json.Parser()); err != nil {
log.Fatalf("error loading config: %v", err)
}
// 加载 YAML 配置并合并到先前加载的配置中。
k.Load(file.Provider("mock/mock.yml"), yaml.Parser())
fmt.Println("parent's name is = ", k.String("parent1.name"))
fmt.Println("parent's ID is = ", k.Int("parent1.id"))
}
2. 监视配置文件变化
一些 Provider，例如 file、appconfig、vault 和 consul，暴露了 Watch() 方法，可以监视配置的更改并触发回调函数以重新加载配置。
注意： 如果在 koanf 对象执行 Load() 时发生并发的 *Get() 调用，此操作不是 goroutine 安全的，需要实现互斥锁。
// 假设已安装 file Provider 和 json Parser
func main() {
f := file.Provider("mock/mock.json")
// 首次加载
if err := k.Load(f, json.Parser()); err != nil {
log.Fatalf("error loading config: %v", err)
}
// 监视文件并获取更改时的回调。
// file provider 总是返回 nil `event`。
f.Watch(func(event interface{}, err error) {
if err != nil {
log.Printf("watch error: %v", err)
return
}
// 丢弃旧配置，加载新副本。
log.Println("config changed. Reloading ...")
k = koanf.New(".")
k.Load(f, json.Parser())
k.Print()
})
// 永久阻塞以等待文件更改。
log.Println("waiting forever. Try making a change to mock/mock.json to live reload")
<-make(chan bool)
}
3. 从命令行读取配置
对于命令行配置，可以使用 posflag.Provider（基于 spf13/pflag，一个高级命令行库）或 basicflag.Provider（基于 Go 内置的 flag 包）。
命令行标志的值可以覆盖从配置文件中加载的值。将 Koanf 实例传递给 posflag.Provider 有助于它处理默认的命令行标志值，即使这些值未出现在先前加载的配置 Map 中。
package main
import (
"fmt"
"log"
"os"
"github.com/knadh/koanf/v2"
"github.com/knadh/koanf/parsers/toml"
"github.com/knadh/koanf/providers/file"
"github.com/knadh/koanf/providers/posflag"
flag "github.com/spf13/pflag" // 使用 pflag 库
)
var k = koanf.New(".")
func main() {
f := flag.NewFlagSet("config", flag.ContinueOnError)
f.StringSlice("conf", []string{"mock/mock.toml"}, "path to one or more .toml config files")
f.String("time", "2020-01-01", "a time string")
f.Parse(os.Args[1:])
// 1. 先加载配置文件
cFiles, _ := f.GetStringSlice("conf")
for _, c := range cFiles {
if err := k.Load(file.Provider(c), toml.Parser()); err != nil {
log.Fatalf("error loading file: %v", err)
}
}
// 2. 加载命令行参数并合并，它们可以覆盖文件中的值。
if err := k.Load(posflag.Provider(f, ".", k), nil); err != nil {
log.Fatalf("error loading config: %v", err)
}
fmt.Println("time is = ", k.String("time"))
}
4. 读取环境变量作为配置
使用 env/v2 Provider。它可以根据前缀过滤环境变量，并使用 TransformFunc 来转换键和值，从而支持嵌套结构。
package main
import (
"fmt"
"log"
"strings"
"github.com/knadh/koanf/v2"
"github.com/knadh/koanf/parsers/json"
"github.com/knadh/koanf/providers/env/v2"
"github.com/knadh/koanf/providers/file"
)
// ... var k = koanf.New(".")
func main() {
// 假设已加载文件配置
if err := k.Load(file.Provider("mock/mock.json"), json.Parser()); err != nil {
log.Fatalf("error loading config: %v", err)
}
// 仅加载带有前缀 "MYVAR_" 的环境变量，并合并。
// TransformFunc 示例：MYVAR_PARENT1_CHILD1_NAME 转换为 "parent1.child1.name"
k.Load(env.Provider(".", env.Opt{
Prefix: "MYVAR_",
TransformFunc: func(k, v string) (string, any) {
// 1. 转换键名：移除前缀，转小写，将 "_" 替换为 "."
k = strings.ReplaceAll(strings.ToLower(strings.TrimPrefix(k, "MYVAR_")), "_", ".")
// 2. 转换值：例如，将包含空格的字符串转换为切片
if strings.Contains(v, " ") {
return k, strings.Split(v, " ")
}
return k, v
},
}), nil)
fmt.Println("name is =", k.String("parent1.child1.name"))
// ...
}
5. 读取原始字节作为配置
rawbytes.Provider 可以用于读取来自任意来源（例如数据库或 HTTP 响应体）的原始 []byte 切片。随后需要一个 Parser 来解析这些字节。
package main
import (
"fmt"
"github.com/knadh/koanf/v2"
"github.com/knadh/koanf/parsers/json"
"github.com/knadh/koanf/providers/rawbytes"
)
// ... var k = koanf.New(".")
func main() {
b := []byte(`{"type": "rawbytes", "parent1": {"child1": {"type": "rawbytes"}}}`)
// rawbytes Provider 提供字节，然后由 json Parser 解析。
k.Load(rawbytes.Provider(b), json.Parser())
fmt.Println("type is = ", k.String("parent1.child1.type"))
}
6. 从 Map 和 Struct 读取配置
从嵌套 Map 读取配置：
confmap.Provider 可以将预先准备好的 map[string]interface{} 加载到 koanf 实例中，这常用于加载默认值。
// 假设已导入必要的包...
k.Load(confmap.Provider(map[string]interface{}{
"parent1.name": "Default Name",
"parent3.name": "New name here",
}, "."), nil) // 使用 "." 分隔符，假定键是扁平化的
从 Struct 读取配置：
structs.Provider 可以从一个 Go 结构体中读取数据并加载到 koanf 实例中，需要提供结构体及其标签（例如 koanf）。
package main
import (
"fmt"
"github.com/knadh/koanf/v2"
"github.com/knadh/koanf/providers/structs"
)
// 定义结构体，使用 koanf 标签
type parentStruct struct {
Name string `koanf:"name"`
ID int `koanf:"id"`
Child1 childStruct `koanf:"child1"`
}
// ... other structs ...
type sampleStruct {
Type string `koanf:"type"`
Parent1 parentStruct `koanf:"parent1"`
}
func main() {
k.Load(structs.Provider(sampleStruct{
Type: "json",
Parent1: parentStruct{
Name: "parent1",
ID: 1234,
// ... populated fields ...
},
}, "koanf"), nil)
fmt.Printf("name is = `%s`\n", k.String("parent1.child1.name"))
}
7. 反序列化和序列化
反序列化 (Unmarshalling)
koanf.Unmarshal() 方法可以将 koanf 实例中的值基于结构体字段标签（例如 koanf）扫描到一个结构体中。
// 假设已加载配置到 k 实例
type childStruct struct {
Name string `koanf:"name"`
Type string `koanf:"type"`
GrandChild struct {
Ids []int `koanf:"ids"`
On bool `koanf:"on"`
} `koanf:"grandchild1"`
}
var out childStruct
// 快速反序列化。
k.Unmarshal("parent1.child1", &out)
// 使用高级配置进行反序列化
out = childStruct{}
k.UnmarshalWithConf("parent1.child1", &out, koanf.UnmarshalConf{Tag: "koanf"})
扁平路径反序列化
如果需要将来自各种嵌套结构的键反序列化到一个扁平的目标结构体中，可以使用 UnmarshalConf.FlatPaths: true 标志。
type rootFlat struct {
Type string `koanf:"type"`
Parent1Name string `koanf:"parent1.name"` // 结构体字段使用完整路径
// ...
}
var o1 rootFlat
// Unmarshal the whole root with FlatPaths: True.
k.UnmarshalWithConf("", &o1, koanf.UnmarshalConf{Tag: "koanf", FlatPaths: true})
序列化 (Marshalling)
使用 k.Marshal(parser) 可以将 koanf 实例序列化回字节（例如 JSON 或 YAML 格式）。
parser := json.Parser()
b, _ := k.Marshal(parser)
fmt.Println(string(b))
8. 合并顺序与键大小写敏感性
键大小写敏感性
koanf 中的配置键是区分大小写的。例如，app.server.port 和 APP.SERVER.port 被视为不同的键。
合并顺序和行为
koanf 不对从各种 Provider 加载配置施加任何强制顺序。
合并顺序： 每次连续的 Load() 或 Merge() 都会将新配置合并到现有配置中。这意味着您可以按任何顺序加载配置，例如先加载环境变量，然后是文件，最后是命令行变量。
默认合并行为： 默认情况下（使用 koanf.New(delim) 创建实例），最新加载的配置会与前一个配置合并。当合并嵌套 Map 时，koanf 会递归地合并键；而静态值（如切片、字符串等）则会被覆盖。
例如，如果两个配置源具有相同的键，后加载的源将覆盖前者的类型和值。
严格合并： 如果不希望覆盖类型，可以通过 koanf.Conf{Delim: ".", StrictMerge: true} 启用严格合并。在这种情况下，如果配置尝试覆盖先前加载的配置类型，Load 将返回错误。
var conf = koanf.Conf{
Delim: ".",
StrictMerge: true, // 启用严格合并
}
var k = koanf.NewWithConf(conf)
func main() {
// ... load yaml
// 如果 JSON 配置中的键类型与 YAML 中的不兼容（例如，YAML 中是整数，JSON 中是 float64），
// 且 StrictMerge 为 true，则 Load 可能会失败。
if err := k.Load(file.Provider(jsonPath), json.Parser()); err != nil {
// 如果发生严格合并错误，程序将在此处退出
log.Fatalf("error loading config: %v", err)
}
}
自定义合并策略： 默认的合并行为可以通过 koanf.WithMergeFunc 选项提供的自定义合并函数来更改。
重要细节和设计哲学
- 键的区分大小写：koanf 中的配置键是区分大小写的。例如，
app.server.port和APP.SERVER.port被视为不同的键。 - 加载顺序灵活：koanf 不强制规定加载配置的顺序。您可以先加载环境变量，再加载文件，最后加载命令行变量，或者任何您需要的顺序。
- 可扩展性：自定义 Providers 和 Parsers 的编写非常简单，它们只需要实现返回嵌套
map[string]interface{}或原始字节的通用接口。
koanf 就像一个配置数据的“集线器”或“搅拌机”，它不关心配置从哪里来（Provider），也不关心配置是什么格式（Parser），它只负责将这些不同来源、不同格式的数据按照您的意愿，有序地合并到一个统一的、可查询的结构中。
