最简路径是直接使用koanf核心库，按需引入对应provider（如file、env）和parser（如yaml、json），避免全量依赖；需注意版本匹配、加载顺序、并发安全、结构体tag用koanf而非json/yaml，以及依赖注入优于全局单例。
用 koanf 封装配置读取模块最简路径
直接用 koanf 就够了，不用自己写 parser 或 provider。它的核心设计就是「按需加载」，只引入你要的格式和来源，避免把 viper 那套全量依赖带进来。
常见错误是：装了 github.com/knadh/koanf/v2 后，直接调 k.Load() 却 panic —— 因为没装对应的 provider 和 parser。
- 读 YAML 文件：必须同时装
github.com/knadh/koanf/providers/file和github.com/knadh/koanf/parsers/yaml - 读环境变量：要装
github.com/knadh/koanf/providers/env/v2，注意路径里有/v2 - 合并多源配置时，顺序很重要：
file加载完再env覆盖，才能实现“配置文件为基、环境变量优先”
封装 config 包时如何支持热重载（非监听）
koanf 本身不提供文件监听，但你可以用 fsnotify + 手动 k.Unmarshal() 实现软重载。关键不是监听本身，而是怎么安全替换运行中的配置实例。
容易踩的坑：直接 new 一个新 koanf.Koanf 并赋值给全局变量，会导致并发读取时出现 panic: concurrent map read and map write。
- 用
sync.RWMutex保护配置实例，读用RLock，重载时用Lock - 重载流程：读新文件 → 新建临时
k→Unmarshal到 struct → 替换旧实例 →Unlock - 不要在重载时调
k.Load()，它会清空已有键；改用k.Merge()或重建
为什么别把 config 封装成单例全局变量
很多封装习惯性导出一个 var C Config 全局变量，看似方便，实则埋雷：测试难 mock、模块间隐式耦合、无法支持多配置上下文（比如单元测试中需要不同配置）。
更稳妥的做法是把 *koanf.Koanf 当作依赖注入进业务结构体：
- 定义
type App struct { cfg *koanf.Koanf }，构造时传入 - 测试时可传入 mock 的
koanf实例，或用koanf.New(…)+.Load()快速构造 - 避免在
init()里加载配置，它无法被测试控制，且可能触发过早初始化
嵌套结构体字段映射容易忽略的点
用 k.Unmarshal("app.server", &s) 解析到 struct 时，字段名必须匹配 tag，否则字段为空。koanf 默认用 koanf tag，不是 json 或 yaml。
例如：
type Server struct {
Port int `koanf:"port"`
Host string `koanf:"host"`
}
如果写成 json:"port"，Unmarshal 不会赋值，也不会报错 —— 这是最隐蔽的问题之一。
另外，koanf 对大小写敏感，默认路径分隔符是 .，但如果你用 env provider，环境变量名默认转大写下划线（如 APP_SERVER_PORT），而 YAML 里是 app.server.port，二者能自动对齐；但如果自定义分隔符或 prefix，就容易断链。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
