clientv3.New 初始化卡死或返回 nil 是因连接配置不全：必须显式设置 grpc.WithBlock() 和 DialTimeout（至少 5 秒），开发环境关 TLS 需加 grpc.WithInsecure()，生产环境需完整 tls.Config（含 ServerName），endpoints 要写全且 Watch 路径须严格匹配（如结尾斜杠）。
clientv3.New 初始化卡死或返回 nil，基本可以断定是连接配置没写全。etcd 客户端不是“连上就完事”，它默认异步建连，不加阻塞和超时，cli 可能为 nil，后续调用直接 panic。
clientv3.New 必须带 grpc.WithBlock() 和 DialTimeout
没这两项，客户端构造不报错但不可用——DialTimeout 不设，DNS 解析失败时会卡住几十秒；不加 grpc.WithBlock()，clientv3.New 立即返回，但底层连接还在后台试连，cli 实际未就绪。
-
DialTimeout: 5 * time.Second是底线，低于 3 秒容易被本地 DNS 缓存抖动误判 - 必须显式传
grpc.WithBlock()，否则Put/Get调用可能 panic - 开发环境关 TLS 时，一定要加
grpc.WithInsecure()；生产环境则需完整tls.Config，漏掉ServerName会报x509: certificate is valid for ... not ... - endpoints 列表要写全，比如
[]string{"http://etcd-0:2379", "http://etcd-1:2379"}，客户端不会自动发现新节点
Watch 监听不到变更？先查路径和流处理
90% 的监听失效不是 etcd 服务端问题，而是客户端路径不一致或 channel 消费不健壮。/config/app/ 和 /config/app 是两个不同前缀，WithPrefix() 必须严格匹配。
- 读配置用
Get(ctx, "/config/app/", clientv3.WithPrefix())，watch 也得用同样路径 +WithPrefix()，结尾斜杠不能少 - 不能用
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
Put 后 Get 立即读不到新值？这是语义问题，不是 bug
etcd 的 Put 是异步刷盘，Get 默认读的是“当前已提交 revision”快照。如果 Put 返回后立刻 Get，可能还没 commit 完，就命中旧快照。
立即学习“go语言免费学习笔记（深入）”；
- 正确做法：Put 后等响应完成再 Get，或用
clientv3.WithRev(resp.Header.Revision)强制读刚写入的 revision - 热更新场景下，别依赖“写完立刻生效”，Watch 事件才是权威通知源
- 所有写操作建议绑定
lease，避免配置残留；LeaseGrant后需另起 goroutine 调用LeaseKeepAlive续期，否则 10s 后 key 自动删除
结构体映射 YAML 时字段名对不上？静默失败最坑人
Go 结构体字段小写、没加 yaml: tag、或用了 yaml.Unmarshal 而非 UnmarshalStrict，都会导致解析失败却不报错。
- 字段必须大写（导出），且显式加 tag，例如
RedisURL string `yaml:"redis_url"` - 嵌套结构用
map[string]interface{}，不用map[string]string，否则数字、布尔值会丢类型 - 用
yaml.UnmarshalStrict替代Unmarshal，多一个字段就 panic，早暴露配置格式问题 - 如果配置来自环境变量，
viper需提前调用viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))，否则db.host匹配不到DB_HOST
真正难的不是写几行 Put 和 Watch，而是把连接生命周期、watch 流恢复、lease 续期、配置解析容错这些细节串成闭环。多数线上故障，都出在某一处错误分支没覆盖，比如 wresp.Err() != nil 忘了处理，或者 LeaseKeepAlive goroutine 没起。
