clientv3.New 初始化失败常见原因包括：Endpoints 缺少协议和端口、启用 TLS 未传 tls.Config、集群单点故障未自动容灾、未调用 defer cli.Close() 导致 fd 耗尽。
clientv3.New 初始化失败的常见原因
连不上 etcd 不报“连接拒绝”，只在 Put 或 Get 时暴露为 context.DeadlineExceeded 或 rpc error: code = Unavailable。问题往往出在初始化阶段就被 silently 忽略了。
-
Endpoints必须带协议和端口，比如[]string{"http://127.0.0.1:2379"}；写成"127.0.0.1:2379"会静默降级为 http，若服务端只开 https 就彻底失败 - 启用了 TLS 却没传
tls.Config，哪怕测试用也要显式加&tls.Config{InsecureSkipVerify: true} - 集群模式下只填了一个 endpoint，而它刚好宕机——clientv3 默认不自动 failover 到其他节点，得靠自己重试或轮询
- 忘记调
defer cli.Close()，长期运行程序会出现 fd 耗尽
Put 写入没生效，但也不报错
不是逻辑写错了，是根本没写进去。etcd v3 的 Put 是强一致提交，但不会重试、不抛连接异常，只依赖 context 和底层 gRPC 状态。
- 别用
context.Background()直接调cli.Put()，必须套一层超时：ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second) - 必须显式判断
err != nil，即使resp非空，err为真就代表写入失败 - key 路径严格区分大小写和前缀，
/config/db/host和config/db/host是两个 key，缺开头的/就读不到 - etcd 不需要父路径存在，
Put自动创建中间层级，不用先mkdir类操作
Get 读不到最新值或返回空
读取行为受一致性模型控制，默认是 linearizable（强制走 leader），但代价是延迟高；配置类场景更常用可序列化读，更快也够用。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 高频读配置建议加
clientv3.WithSerializable()：从任意节点读，性能好，跨机房部署不易抖动 - 绝对不能对
resp.Kvs直接取[0]，key 不存在时它是空切片，会 panic - 不要把
Get结果缓存在全局变量里长期复用——etcd 不推变更，得靠Watch或轮询 - 如果刚
Put完立刻Get却读不到，检查是否用了WithSerializable()且服务端有 follower 延迟；临时调试可去掉该 option 强制走 leader
Watch 收不到变更事件
watch 不是注册一次就完事，它是个长连接流，卡在任一环节都会静默丢事件。
立即学习“go语言免费学习笔记（深入）”；
- watch 启动后必须立刻起 goroutine 消费：
go func() { for wr := range watchChan { /* 处理 */ } }()，否则 channel 缓冲满（默认 100 条）就阻塞后续事件 - 默认从“当前 revision + 1”开始监听，如果配置在 watch 建立前就被改过，那条更新就永远收不到；稳妥做法是先
Get拿到resp.Header.Revision，再用clientv3.WithRev(rev)启动 watch - watch 连接断开时，
WatchChan会关闭，但不报错——你得在for wr, ok := range watchChan中检查ok == false并主动重建 - 别在 watch 循环里做耗时操作（如 HTTP 请求、DB 写入），否则 channel 接收被卡住，新事件堆积后可能被丢弃
实际用起来最易忽略的是 revision 衔接和 channel 消费节奏——watch 不是“设好就自动工作”的黑盒，它要求你既管建，也管收，还管断线重连。稍一松懈，配置热更新就变成“看起来在跑，其实早断了”。
