consul.NewClient 初始化就 panic 的根本原因是 Address 字段不合法：必须为带协议的完整 URL（如"http://127.0.0.1:8500"），禁止为空、nil 或缺协议；Docker 环境需适配 host.docker.internal（Mac/Win）或宿主机真实 IP（Linux）；ACL 开启时 Token 必须非空，否则静默拒绝。
consul.NewClient 初始化就 panic，地址格式必须严格
panic 几乎全因 Address 字段不合法：空、nil、或只写 "127.0.0.1:8500" 缺协议。Consul Go SDK 要求完整 URL，比如 "http://127.0.0.1:8500"。
常见踩坑点：
- Docker 内运行 Go 程序连宿主机 Consul：Mac/Win 用
"http://host.docker.internal:8500"，Linux 用宿主机真实 IP（如"http://192.168.1.100:8500"） - Consul agent 没开 HTTP 接口，或监听地址不是
127.0.0.1（比如绑了0.0.0.0但没加-client=0.0.0.0参数） - ACL 开启后，
cfg.Token必须是非空字符串；空 token ≠ 无认证，而是触发默认拒绝策略
实操建议：初始化后立刻验证连接，别等注册时才发现问题：
_, err := client.Status().Leader()
if err != nil {
log.Fatal("Consul connection failed:", err)
}
服务注册成功但查不到，健康检查字段不能为 nil
注册返回 err == nil 不代表服务可用。Consul 默认把 Check: nil 的服务标记为 critical，client.Health().Service() 默认过滤掉它——你根本看不到。
立即学习“go语言免费学习笔记（深入）”；
HTTP 健康检查最常用，但细节极易出错：
-
HTTP字段必须是完整 URL，如"http://10.0.2.15:8080/health"，不能只是路径"/health" -
Address别填"localhost"：容器或跨主机部署时，Consul agent 根本无法路由到该地址 -
Interval必须大于Timeout，否则注册直接被拒，报错"check interval must be greater than timeout" - 服务名不能含下划线（如
"user_service"），会被静默拒绝，日志只提示"Invalid service name"
TTL 类型虽简单，但必须配 TTL: "30s"（格式严格，不能是 "30" 或 "30sec"），且注册后得立刻调一次 client.Agent().UpdateTTL()，否则 30 秒后状态变 critical。
client.Health().Service() 返回空列表，passingOnly 是硬开关
这个方法默认不返回任何东西——空结果不是网络问题，而是参数语义没对齐。它默认返回所有状态节点（包括 critical、warning、已下线残留），但生产环境几乎没人要这些。
必须显式传 passingOnly: true：
services, _, err := client.Health().Service("user-service", "", true, &api.QueryOptions{
AllowStale: false,
PassingOnly: true,
})
注意两点：
-
AllowStale: false避免读到过期缓存（Consul 默认允许 stale read 提升吞吐） - 第二个参数是
tagFilter，传空字符串""表示不限 tag；若填"v1"，则只返回带该 tag 的实例 - 别依赖单次查询结果做长期决策——网络抖动可能让这次失败或超时，应结合本地缓存 + 定期刷新
Watch KV 不是长连接，轮询逻辑得自己兜底
kv.Watch 是 HTTP 轮询封装，不是 WebSocket。裸写 for 循环调用等于高频刷接口，还容易漏事件、卡死、goroutine 泄漏。
正确做法是用 watch.NewWatcher 替代：
- 它内置指数退避和自动重连
-
Watcher的ctx必须可控（比如随服务生命周期cancel），否则 goroutine 泄漏 - KV 的错误处理反直觉：
kv.Get("missing-key", nil)的error是nil，真正该判空的是返回的*api.KVPair；pair == nil可能是 key 不存在、ACL 拒绝、或路径是个目录，三者表现一致
复杂点在于：Watch 本身不保证事件不丢失，尤其在 Consul 集群短暂不可用时。真正可靠的上下线感知，需要结合 Session + 阻塞查询 + 本地状态缓存，不是靠一个 Watch 调用就能兜住的。
