Consul配置热更新需手动调用viper.Unmarshal(&cfg)刷新结构体，因viper不会自动同步变更；key名必须与mapstructure标签严格一致，且ReadRemoteConfig()不可省略。
Consul 配置键名必须匹配 mapstructure 标签
Consul 的 KV 存储是扁平路径，不支持嵌套结构，但 Viper 读取 Consul 时会把 app.port 这样的路径自动转为嵌套字段。关键在于：你的结构体字段上的 mapstructure 标签值，必须和 Consul 中实际存储的 key 完全一致（包括大小写、下划线）。
常见错误现象：Consul 里存的是 app_port，结构体却写 mapstructure:"port"，结果 Configuration.App.Port 始终为空字符串。
- Consul 中建议用小写+下划线风格，例如：
app_env、server_read_timeout - 结构体字段保持 Go 风格（驼峰），但
mapstructure标签严格对应 Consul key：Env string `mapstructure:"app_env"` - Viper 默认不开启自动展开，需显式调用
viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))才能兼容环境变量与 Consul key 的转换逻辑
viper.AddRemoteProvider 后必须调用 ReadRemoteConfig
只加 viper.AddRemoteProvider("consul", "127.0.0.1:8500", "config/") 不会自动拉取配置 —— 这只是注册远程源，真正触发 HTTP 请求的是 viper.ReadRemoteConfig()。漏掉这一步，viper.Get("app.env") 返回 nil 或空值。
使用场景：服务启动初期一次性加载，或配合 viper.WatchRemoteConfigOnChannel 实现热更新。
-
ReadRemoteConfig()是同步阻塞调用，失败会 panic；生产环境应包一层if err := viper.ReadRemoteConfig(); err != nil { log.Fatal(err) } - Consul key 路径末尾是否带斜杠影响行为：
"config/"表示递归读取子路径，"config"只读单个 key - 若 Consul 启用了 ACL，需提前设置
viper.SetConfigPermissions(0600)并在 provider 初始化时传入 token
结构体嵌套字段映射失败的三个典型原因
你定义了 type Server struct { Port int `mapstructure:"server_port"` }，但 viper.Unmarshal(&cfg) 后 cfg.Server.Port 仍是 0。问题往往不在结构体本身，而在 Viper 加载链路。
- Viper 未启用
AutomaticEnv()且环境变量未覆盖时，不会 fallback 到默认值；建议在结构体字段加default:"8080"标签 - Consul 中存的是字符串
"8080"，而结构体字段是int类型 —— Viper 默认不做强制类型转换，需手动调用viper.GetInt("server_port")或改用string类型再转 - 结构体嵌套层级过深（如
A.B.C.D.Port），Viper 对超过 4 层的嵌套解析不稳定；建议控制在 3 层以内，或改用扁平 key + 单层结构体
Consul 配置热更新时结构体字段不会自动刷新
viper.WatchRemoteConfigOnChannel 能监听 Consul KV 变更并触发回调，但已绑定到结构体的值不会自动更新。你不能指望 cfg.App.Env 在 Consul 修改后“自己变”。
正确做法是在回调中重新执行 viper.Unmarshal(&cfg)，或改用 viper.Get 动态读取。
- 频繁调用
Unmarshal有性能开销，适合低频变更（如日志级别）；高频场景建议只更新受影响字段，例如cfg.Server.Port = viper.GetInt("server_port") - 注意并发安全：如果多个 goroutine 同时读
cfg，又在回调里写它，必须加sync.RWMutex - Consul 的 watch 机制不保证事件顺序，两次快速更新可能合并为一次通知；不要依赖“每次变更都精确触发一次”
配置热更新不是结构体自动同步，而是你主动响应变更并重载数据 —— 这点最容易被忽略，尤其当本地开发时以为改完 Consul 就万事大吉。
