clientv3.new卡死或返回nil，主因是未设dialtimeout和grpc.withblock()；watch收不到变更因未用goroutine持续消费且未处理channel关闭；put后get读不到新值因读写语义未对齐raft一致性模型。
clientv3.New 初始化卡死或返回 nil，Watch 收不到变更，Put 后 Get 立即读不到新值——这些问题不是 etcd 服务端故障，而是客户端配置和使用方式不匹配 Raft 语义导致的。
clientv3.New 卡死或返回 nil 怎么办
根本原因是连接未设超时、未强制阻塞等待，导致 DNS 解析失败或 endpoint 不可达时无限 hang 住，且不报错，cli 可能为 nil，后续调用直接 panic。
-
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 监听不到变更或丢事件
Watch 是流式长连接，不是轮询。静默失败通常源于 channel 处理不健壮：关闭后继续读、缓冲区满未消费、前缀不一致、context 提前 cancel。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 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说明ctx已 cancel，应重建 watch - Watch goroutine 必须持续运行，不能只读一次就退出，否则缓冲区满后新事件会被丢弃
Put 写入后 Get 立即读不到新值
这是 Raft 日志复制与读取语义未对齐的典型表现：Put 异步刷盘，Get 默认读的是“当前已提交 revision”，但若未等响应就查，可能命中旧快照。
- 若需强一致性读，Get 时加
clientv3.WithSerializable()可降低延迟，但不保证线性一致 - 真正线性一致读需用
clientv3.WithSerializable()+clientv3.WithRev(rev)，其中rev来自上一次 Put 响应的resp.Header.Revision - Watch 初始化阶段建议先
Get一次做兜底，再用clientv3.WithRev(lastRev + 1)启动 watch，避免中间变更丢失 - 更新本地状态时，别在 watch 循环里做耗时操作（如 HTTP 请求、DB 写入），否则会卡住 channel 接收，导致事件堆积
分布式锁与选主为什么必须用 Lease + Txn
裸 Put+Delete 模拟锁本质是错的：无自动过期、无所有权校验，节点崩溃后锁永远卡死，或 A 删了 B 的锁。
- 加锁必须用
LeaseGrant创建带 TTL 的 lease，再用Put绑定LeaseID和PrevKV实现「仅当 key 不存在时写入」 - value 必须唯一（推荐
uuid或os.Getpid() + nanotime），不能用固定字符串如"locked" - 释放锁必须走
Txn().If(cmp.Value("expected_value") == true).Then(Delete())，不能裸Delete - 选主建议用
clientv3.Session，但必须设短 TTL（3–10 秒）、续租间隔 ≤ TTL/3，并监听Session.Done()做降级
所有这些坑，都源于把 etcd 当成普通 KV 存储来用，而忽略了它底层是 Raft 驱动的强一致性系统——连接、读写、监听、锁，每个环节都要对齐它的语义边界。最常被忽略的是：watch channel 关闭不报错、context 复用导致流静默终止、revision 跳变未处理、lease 续租延迟超 TTL。这些点一旦漏掉，问题就藏得深、复现难、日志少。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
