clientv3.new()初始化失败的根本原因是配置与etcd实际状态不匹配：endpoints缺协议/端口、tls未配grpc.withinsecure()或tls.config、dialtimeout不覆盖tls握手、watch未持续消费channel、get未用withserializable()导致读延迟等。
clientv3.New() 初始化失败，根本原因不是代码写错了
绝大多数连接问题出在 clientv3.New() 返回后“看似成功”，但首次 Put() 或 Get() 就卡住或报 context.DeadlineExceeded。这不是 client 本身 bug，而是配置与 etcd 实际状态没对齐。
- Endpoints 必须带协议和端口，例如
[]string{"http://127.0.0.1:2379"}；写成"localhost:2379"会静默降级为 http，若服务端只监听 https 就彻底失败 - 本地开发关 TLS 时，必须显式加
grpc.WithInsecure()（注意不是WithInsecureTransport()），否则连接被拒绝且无明确错误提示 - 生产环境启用 TLS 时，
tls.Config缺一不可：CA 证书、客户端证书、密钥路径全得对，漏掉ServerName字段会导致x509: certificate is valid for ... not ... -
DialTimeout只控制 TCP 建连，不包含 TLS 握手和 gRPC 初始化——启用了 TLS 的场景下，务必给业务调用的ctx单独设超时，比如context.WithTimeout(context.Background(), 3*time.Second)
Watch 配置变更却收不到事件，大概率是 channel 没持续消费
etcd 的 Watch() 是流式长连接，返回的 WatchChan 默认缓冲区大小为 100。一旦未及时读取，后续事件直接丢弃，且不会重发、不会重连。
- 必须启动独立 goroutine 持续读取：
go func() { for wr := range watchChan { /* 处理 wr */ } }()，不能只range一次就结束 - watch 前缀时，确保路径末尾不带多余斜杠：
/config/app/和/config/app是两个完全不同的 key 前缀 - 遇到
ErrCompacted表示历史 revision 被压缩，需从当前最新 revision 重新 watch；ErrCanceled说明 context 被 cancel，应重建 watch - 首次 watch 建议用
clientv3.WithLastRev()获取当前 revision，然后从该 revision + 1 开始监听，避免漏掉刚写入的配置
Get() 总是读不到最新值，别怪 etcd，先查一致性模型
默认 Get() 是 linearizable 模式（强一致，强制走 leader），延迟高但绝对可靠；而配置类读取更常用可序列化读，性能好、跨机房部署更稳，但可能短暂读到旧值。
- 高频读配置建议加
clientv3.WithSerializable()：从任意节点读，不强制走 leader，延迟低 - 刚
Put()完立刻Get()却读不到，可能是用了WithSerializable()且 follower 有复制延迟；临时调试可去掉该 option 强制走 leader - 绝不能对
resp.Kvs直接取[0]——key 不存在时它是空切片，会 panic；必须先判len(resp.Kvs) > 0 - etcd 存的是 raw bytes，
Value是[]byte；直接json.Unmarshal()失败不会报错但结果为空，建议封装UnmarshalJSONSafe()，用json.Valid()预检再解析
分布式锁释放必须用 Txn，Delete() 是危险操作
释放锁不是删掉 key 就完事。裸 Delete() 无法校验所有权，A 节点可能删掉 B 刚抢到的锁，B 还以为自己持有锁继续执行——这是典型的竞态漏洞。
- 加锁时 value 必须唯一，推荐用随机 uuid 或
os.Getpid() + nanotime，**不能设固定字符串如 "locked"** - 释放必须走
Txn().If(cmp.Value("expected_value") == true).Then(clientv3.OpDelete(key))，靠 CAS 确保只删自己设的 value - Put 必须传
leaseID，否则锁不会自动过期；加锁要检查resp.PrevKv == nil，而不是只看err == nil - 不要在
defer中无条件Delete()：panic 后 defer 不执行，或 recover 后又执行一次，导致误删
真正难的不是写对一行 Put()，而是理解 lease 续租失败时如何不脑裂、watch 断连后如何不跳 revision、Txn 条件里 value 比较怎么防碰撞——这些边界稍一松懈，就会在流量高峰或网络抖动时暴露。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
