consul.NewClient 一运行就 panic 是因配置中 Address 字段缺失或格式错误，必须为完整 URL（如 "http://127.0.0.1:8500"），且 Docker 内需用 "host.docker.internal" 等可达地址。
consul.NewClient 为什么一运行就 panic？
因为 consul.NewClient 拒绝接收 nil 或地址为空的配置，不是“连不上才报错”，而是“没给地址就直接崩溃”。很多人抄文档漏掉 Address 字段，或只写 "127.0.0.1:8500" 没带协议，结果 panic 报 "no address provided"。
-
Address必须是完整 URL，如"http://127.0.0.1:8500"（Consul 默认不启 TLS，别写 https） - Docker 内运行时，
"localhost"对 Consul agent 不可达，换成"http://host.docker.internal:8500"或宿主机真实 IP - 建议初始化后立刻调一次
client.Status().Leader()，提前暴露连接问题，别等注册时才发现 - ACL 开启后必须填
Token字段，否则注册静默失败——UI 看不到、API 返回空、也不报错
服务注册成功但 UI 里找不到？
注册返回 nil error ≠ 服务可用。Consul UI 默认只显示健康状态为 passing 的服务，而没配健康检查的服务会被自动标为 critical 并隐藏。
- 必须在
AgentServiceRegistration.Check中显式配置健康检查，Check: nil就等于告诉 Consul：“我不值得信任” - HTTP 检查地址不能写
"http://localhost:8080/health"——Consul agent 要能访问到它；Docker/K8s 场景下应填容器网络可路由的地址，比如"http://10.0.2.15:8080/health" -
Interval必须大于Timeout，否则注册直接被拒，报错"check interval must be greater than timeout" - 调试时用
curl "http://127.0.0.1:8500/v1/health/service/my-service?passing=true"看是否真返回实例，比刷 UI 更准
client.Health().Service 返回空列表？
不是代码写错了，而是语义没对齐：这个方法默认只返回健康检查通过的节点（passingOnly=true），且 tag 匹配逻辑很严格，空字符串 "" 表示“匹配无 tag 的服务”，不是“忽略 tag”。
- 刚注册完立刻查，大概率为空——第一个健康检查周期（如 5s）还没跑完，状态仍是
unknown或critical，加time.Sleep(1 * time.Second)或重试更稳妥 - 如果注册时写了
Tags: []string{"v2"}，那查询时第二个参数就得填"v2"，不能留空 - 别混淆 DNS 和 HTTP API 行为：
dig @127.0.0.1 -p 8600 my-service.service.consul查到 ≠Health().Service()返回非空，两者缓存和一致性机制不同 - 返回的是
[]*api.ServiceEntry，真正要取地址得用s.Service.Address和s.Service.Port，不是s.Node.Address
服务退出时不注销，会出什么问题？
进程被 kill 后服务还在 Consul 上挂着，流量继续打过来，下游调用全失败。这不是延迟问题，是根本性故障扩散。
立即学习“go语言免费学习笔记（深入）”；
- 必须用
signal.Notify捕获SIGINT/SIGTERM，并在 handler 里调client.Agent().Deregister() - 别依赖
defer在 main 函数末尾注销——main 返回不等于进程退出，尤其有 goroutine 在跑时 - 若用了 TTL 健康检查，注销前建议先调
client.Agent().FailTTL("service:" + serviceID)，让 Consul 立即标记为不可用，再 deregister - 注册时
ID必须全局唯一，推荐拼成"my-service-hostname-8080"，否则重启后新旧实例 ID 冲突，注销可能删错
Consul 服务发现真正的难点不在“怎么写”，而在“谁在什么时候看到什么状态”——客户端缓存、agent 同步延迟、健康检查周期、网络可达性，四者叠加起来，一个 passingOnly 参数设错，就能让整个发现链路失效。
