应确保client.Health().Service()调用时传入passingOnly=true参数，否则默认返回所有状态节点（含critical等），而健康检查未通过的实例不会进入passing集合；同时需确认注册时配置了有效Check字段且HTTP探针返回200 OK。
Consul服务注册后，client.Health().Service()返回空列表怎么办
不是服务没注册成功，而是调用时漏了 passingOnly=true。Consul默认返回所有状态节点（包括critical、warning），但健康检查未通过的节点会被过滤掉——如果你没配健康检查或探针路径返回非200，它们就进不了passing集合。
- 检查注册代码是否带了
Check字段，HTTP探针必须响应200 OK，且Interval别设成1s（Consul集群可能限流） - 确认
client.Health().Service("svc-name", "", true, ...)第3个参数是true，写成false或漏传会拿到一堆不可用节点 - 用
curl http://127.0.0.1:8500/v1/health/service/svc-name?passing=true手动验证API返回，排除Go客户端封装干扰
etcd Watch监听失效，扩容节点不触发更新
裸写for range client.Watch(ctx, key)是最大陷阱。WatchChan被关闭后，下一次Recv()直接panic，整个监听逻辑就断了，新节点上线自然收不到通知。
- 每次Watch启动前，必须用
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)限定单次生命周期 - 循环体里必须显式检查
if wresp.Err() != nil，遇到context.DeadlineExceeded或rpc error: code = Canceled就退出并指数退避重试（起始100ms，上限5s） - 别依赖
client.Watch()自动重连——它只重试单次gRPC流，网络抖动后需手动重建Watch
Consul DNS解析返回旧IP，新节点流量打不进去
DNS缓存和TTL不是唯一原因。Consul的DNS接口（端口8600）默认不校验健康状态，dig user-service.service.consul可能返回已下线但未及时Deregister的节点IP。
- 强制加
@127.0.0.1 -p 8600直连本地Consul，绕过系统DNS缓存 - 查Consul UI或
curl http://127.0.0.1:8500/v1/health/service/user-service?passing=true确认返回的节点列表是否含新IP - 如果UI里有、DNS里没有，说明DNS插件没启用健康检查过滤：在Consul配置中确认
dns_config { enable_health_check = true }已开启
自测脚本跑通但线上仍路由失败
本地测试用127.0.0.1:8500能通，不代表生产环境可用。Docker容器内访问Consul，http://127.0.0.1:8500指向的是容器自身，不是宿主机。
- Linux宿主机部署：Go客户端Endpoints必须填宿主机真实IP（如
"192.168.1.100:8500"），不能写localhost或127.0.0.1 - Mac/Windows Docker Desktop：用
host.docker.internal:8500替代127.0.0.1 - 务必在客户端初始化时设置
DialTimeout: 5 * time.Second和AutoSyncInterval: 5 * time.Second，否则endpoint失联后不会主动探测恢复
最常被忽略的是健康检查本身——TCP连得上、HTTP返回200，不等于服务真能处理请求。比如Redis节点扩容后，Consul健康检查只ping了端口，但连接池未初始化，第一个请求仍会超时。自测必须包含真实业务请求链路，不能只验证发现结果。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
