consul.newclient一运行就panic主因是address未配置或格式错误（必须为完整url如"http://127.0.0.1:8500"）；服务注册后查不到多因健康检查缺失导致状态为critical；client.health().service()返回空常因passingonly未设true或tag不匹配。
consul.NewClient 一运行就 panic，基本是 Address 没配对或格式错；服务注册后查不到，八成是健康检查没生效；client.Health().Service() 返回空，往往因为 passingOnly 没设 true 或 tag 匹配不严。
consul.NewClient 初始化失败：地址必须完整且可达
Go 的 Consul 客户端初始化不是“连不上才报错”，而是“没给合法地址就直接崩溃”。常见错误包括：
-
Address字段为空、为nil，或只写"127.0.0.1:8500"缺少协议（必须是"http://127.0.0.1:8500"） - Docker 内运行时填
"localhost"，实际应换为"http://host.docker.internal:8500"（Mac/Win）或宿主机真实 IP（Linux） - Consul agent 没开 HTTP 接口，或监听地址不是
127.0.0.1（比如绑了0.0.0.0但未配-client参数）
实操建议：
- 显式构造配置：
cfg := &api.Config{Address: "http://127.0.0.1:8500"} - 初始化后立刻验证连接：
_, err := client.Status().Leader()
，别等注册时才发现问题 - ACL 开启后，
cfg.Token必须非空字符串，空 token ≠ 无认证，而是触发默认拒绝策略
服务注册成功但查不到：健康检查缺失或未续租
注册返回 err == nil ≠ 服务可用。Consul 默认把 Check: nil 的服务标记为 critical，UI 和 Health().Service() 都会过滤掉它。
实操建议：
- TTL 类型必须配
TTL: "30s"（格式严格，不能是"30"或"30sec"），且注册后**立刻调一次**：client.Agent().UpdateTTL("service:myapp", "", "passing") - HTTP 类型检查的
HTTP字段必须是完整 URL（如"http://10.0.2.15:8080/health"），且 Consul agent 能路由到该地址（容器内别写localhost） - Interval 必须大于 Timeout，否则注册直接被拒，报错
"check interval must be greater than timeout" - 服务名不能含下划线（如
"user_service"），会被静默拒绝，日志只提示"Invalid service name"
client.Health().Service 返回空列表：参数语义易被误解
这个方法默认不返回任何东西——除非你明确告诉它要什么。空结果不是网络问题，而是参数没对齐。
实操建议：
- 第三个参数
passingOnly默认是false，但生产中几乎总要设为true：client.Health().Service("web", "", true) - 第二个参数是 tag，不是模糊匹配字段：
Tags: []string{"v2"}注册的服务，查询时第二个参数就得填"v2"，填空字符串""表示“只匹配无 tag 的服务” - 若在非 Leader 节点查询，需加
&api.QueryOptions{AllowStale: true}，否则可能因强一致性要求返回rpc error: No cluster leader - 返回的是
[]*api.ServiceEntry，取服务地址得用s.Service.Address和s.Service.Port，不是s.Node.Address
Watch 机制容易泄漏 goroutine：不 stop 就一直占着
consulapi.WatchPlan.Run() 是阻塞调用，但它不会自动重连，也不会 panic —— 连接断开时它只是默默返回一个 error，然后 goroutine 就结束了。如果你没检查返回值，watch 就永远停了。
实操建议：
- 必须显式处理
Run()的返回值：if err := plan.Run(); err != nil { log.Printf("watch stopped: %v", err) } - Watch 的 key 是
"services/"（注意末尾斜杠），写成"service/"或"services"都收不到回调 - Handler 函数里避免耗时操作（如 DB 写入、HTTP 请求），它运行在独立 goroutine，阻塞会导致下一轮 long polling 卡住
- 服务退出前务必调
watch.Stop()，否则连接和 goroutine 持续堆积，最终 OOM
最常被忽略的一点：Consul 不会帮你猜 IP。你注册时传的 Address 是什么，它就存什么；对外暴露用哪个 IP，取决于 Consul Server 启动时的 -advertise 或配置里的 advertise_addr。本地开发不配 -advertise=127.0.0.1，注册时又留空 Address，拿到的 s.Service.Address 就是空字符串——这不是你的代码错了，是 Consul 根本不知道该对外说哪个地址。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
