必须显式配置 DialTimeout 和 grpc.WithBlock()，否则 clientv3.New 可能卡死或返回 nil；本地关 TLS 需加 grpc.WithInsecure()，生产环境需完整 tls.Config；Watch 需用 WithPrefix() 且路径斜杠统一，禁用 for range 直接遍历 WatchChan。
clientv3.New 初始化卡死或返回 nil 怎么办
直接原因是没加 grpc.WithBlock() 或 DialTimeout，导致连接阻塞在 DNS 解析或 endpoint 不可达时无限等待，日志无报错，cli 可能为 nil。
必须显式配置：
-
clientv3.Config{DialTimeout: 5 * time.Second}是底线，低于 3 秒易被网络抖动误判 - 一定要传
grpc.WithBlock()，否则 client 构造异步，后续Get/Watch调用可能 panic - 本地开发关 TLS 时，必须加
grpc.WithInsecure()；生产环境开 TLS 则需完整tls.Config，漏掉ServerName会报x509: certificate is valid for ... not ... -
endpoints列表要写全（如[]string{"http://etcd-0:2379", "http://etcd-1:2379"}），client 不自动发现新节点
Watch 监听不到变更或丢事件的常见原因
不是 etcd 服务端问题，而是客户端流处理不健壮：channel 关闭后继续读、没消费完缓冲区、路径前缀不一致都会导致静默失败。
关键点：
立即学习“go语言免费学习笔记（深入）”；
-
Watch必须配clientv3.WithPrefix()，且路径结尾斜杠要统一（/config/app/和/config/app是两个不同前缀） - 不能用
for range ch直接遍历 WatchChan，必须用for { select { case wresp := 并检查 <code>wresp.Err() != nil - 每次 Watch 启动前，用
context.WithTimeout(ctx, 30*time.Second)控制单次流生命周期，旧ctx不能复用 - 遇到
ErrCompacted要从当前最新 revision 重试；ErrCanceled说明 context 已 cancel，应重建 watch - Watch goroutine 必须持续运行，不能只读一次就退出，否则缓冲区满后新事件会被丢弃
Put 写入后 Get 立即读不到新值
本质是读写语义没对齐：etcd 的 Put 异步刷盘，Get 默认读的是“当前已提交 revision”，但若未等响应就查，可能命中旧快照。
安全做法：
- 写操作建议绑定
leaseID（cli.Put(ctx, key, value, clientv3.WithLease(leaseID))），防服务宕机后脏配置残留 - 读操作可加
clientv3.WithRev(resp.Header.Revision)确保读到刚写入的值，但更常用的是依赖 watch 流自动更新，而非轮询 - 不要在
Put后立刻Get，除非业务强依赖即时一致性；热更新场景下，应以 watch 事件为准 - 如果必须读最新，用
cli.Get(ctx, key, clientv3.WithSerializable())可跳过 leader 转发，但牺牲线性一致性
Viper 如何桥接 etcd 的 watch 实现热更新
Viper 本身不支持 etcd watch，必须手动监听 + 注入。常见错误是 WatchConfig() 没反应，或更新后 viper.Get() 仍返回旧值。
实操要点：
- Watch 前必须先成功调用一次
viper.ReadInConfig()，否则内存 configMap 为空，后续注入无效 - 监听路径和写入路径必须完全一致（包括前缀斜杠），且只处理
EventTypePut，忽略EventTypeDelete - 拿到
ev.Kv.Value后，先用json.Valid()校验再json.Unmarshal()，避免解析失败却静默跳过 - 注入要用
viper.ReadConfig(bytes.NewReader(ev.Kv.Value))，不是viper.Set()或viper.Unmarshal()—— 后两者不触发内部重载逻辑 - 推荐把整个配置存为单个 JSON 字符串写入一个 key（如
/config/app），比多 key 管理更可控
Watch 流中断是常态，不是异常；revision、lease、WithPrefix 这三个机制一旦漏掉任一环，热更新就会在某个边界条件下静默失效——这种问题往往压测或上线后才暴露，很难复现。
