etcd clientv3 连接失败需先确认服务运行及监听地址（如127.0.0.1:2379），客户端显式传入带超时的context，endpoints用host:port格式；连接抖动需配置autosyncinterval和健康检查；watch必须带withrev和withprevkv并正确续订。
etcd clientv3 连接失败：context deadline exceeded 怎么办
绝大多数初学者卡在这一步——clientv3.New 直接报 context deadline exceeded，不是代码写错了，而是 etcd 服务根本没连上。
常见错误现象：本地跑 demo 时用 localhost:2379，但 etcd 实际监听的是 127.0.0.1:2379（或反过来），IPv4/IPv6 解析不一致；或者 etcd 进程根本没启动，curl http://localhost:2379/health 返回空或连接拒绝。
- 确认 etcd 进程在运行：
ps aux | grep etcd或systemctl status etcd - 检查监听地址：启动时是否加了
--listen-client-urls http://127.0.0.1:2379，而非默认的http://localhost:2379 - Go 客户端必须显式传入 context，超时不能靠默认值：
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)，用完立刻cancel() - 别用
http://前缀——clientv3.New的Endpoints字段只接受host:port格式，比如[]string{"127.0.0.1:2379"}
Put 和 Get 操作返回 rpc error: code = Unavailable
这个错误不是数据问题，是客户端和 etcd 之间 gRPC 连接断开了，而且没自动重连。
使用场景：短命脚本（如 CLI 工具）可能一次请求就退出，但长服务（如 Web API）必须处理连接抖动。clientv3 默认不自动重连失败的 endpoint，需要手动配置。
- 启用自动重试：在
clientv3.Config中设置AutoSyncInterval: 5 * time.Second，它会定期刷新 endpoint 列表 - 设置健康检查：
DialOptions: []grpc.DialOption{grpc.WithBlock()}能让New阻塞到连接就绪，但上线环境慎用——会拖慢启动 - Get/Put 前先做简单探测：
cli.Get(ctx, "")（空 key）能快速验证连通性，比 ping 更贴近真实路径 - 注意：etcd v3 不再支持 HTTP 短连接，所有操作走 gRPC，所以网络策略、TLS 配置错一个字节都会直接
Unavailable
Watch 一直收不到变更，或者收到重复事件
Watch 不是“订阅后坐等推送”，它本质是长轮询 + 本地事件缓冲，容易因 offset 错位或重连丢失事件。
参数差异很关键：WithRev 控制从哪条历史记录开始监听，WithPrevKV 决定是否带旧值——漏掉这两个，业务逻辑基本不可靠。
- 首次 Watch 必须带
clientv3.WithRev(lastRev + 1)，否则可能漏掉刚发生的变更；建议先Get一次拿到当前resp.Header.Revision - 一定要开
clientv3.WithPrevKV()，否则删键时收不到旧值，无法做幂等判断 - Watch 通道关闭后，不要直接重开新 Watch——要用
cli.Watch(ctx, key, clientv3.WithRev(resp.Header.Revision))接续，否则中间变更全丢 - 如果 Watch goroutine 没及时读通道，缓冲区满（默认 100 条）会导致连接被 server 主动断开，表现为静默中断
为什么用 clientv3 而不是 clientv2？
v2 是 REST 接口封装，v3 是原生 gRPC，二者不兼容。现在所有新项目必须用 v3，v2 在 etcd 3.6+ 已被标记为 deprecated。
性能与兼容性影响明显：v3 的批量操作（Txn）、租约（Lease）、更细粒度权限控制，v2 全都不支持；且 v2 的 HTTP 传输无压缩、无流控，高并发下容易打爆连接数。
- v2 的
Set/Get对应 v3 的Put/Get，但语义不同：v2 的目录树结构在 v3 里要靠 key 命名模拟（如/config/app/timeout） - v2 的
Wait是阻塞轮询，v3 的Watch是真流式推送，延迟低一个数量级 - 别混用：同一个 etcd 集群可同时服务 v2/v3 请求，但 v2 写的数据 v3
Get不到（key 空间隔离），这是硬分隔，不是配置问题
etcd 的坑不在语法，而在它对一致性模型的严格兑现——你写的每行 Go 代码，都在和 Raft 日志、lease TTL、revision 递增这些底层机制打交道。少一个 WithRev，少一次 cancel()，少一个健康检查，都可能让服务在凌晨三点静默失联。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
