Golang集成Consul实现服务注册与发现

Consul客户端初始化需显式设置Address，否则panic；服务注册必须配置HealthCheck，否则状态为critical；服务发现需注意tag匹配和PassingOnly参数；Watch和注销需配合context及shutdown清理。

Consul客户端初始化时panic: "no address provided"

这是最常卡住的第一步：consul.NewClient 要求显式传入 Address，不填或填空字符串会直接 panic。Go 的 net/http 默认不解析环境变量或配置文件，得自己读、校验、拼接。

实操建议：

• 从环境变量读取时，用 os.Getenv("CONSUL_HTTP_ADDR")，但必须检查是否为空，空则 fallback 到默认值 "http://127.0.0.1:8500"
• 不要直接拼 "http://" + host + ":" + port —— 如果 host 已含协议（比如 "https://consul.example.com"），会变成双协议头；应统一用 url.Parse 校验并标准化
• 初始化后立刻调用 client.Status().Leader() 做一次轻量连通性探测，失败时提前返回 error，别等注册时才暴露问题

服务注册时HealthCheck未生效，Consul UI里显示“critical”

注册服务时只填了 Name、Address、Port，没配 Check 字段，Consul 就认为该服务不可用，状态强制为 critical。这不是 bug，是设计逻辑：没有健康检查 = 不可信。

实操建议：

• 至少配一个 HTTP 类型检查：&api.AgentServiceCheck{HTTP: "http://localhost:8080/health", Timeout: "2s", Interval: "5s"}
• Interval 必须大于 Timeout，否则 Consul 会拒绝注册，报错 "check interval must be greater than timeout"
• 如果服务监听在 Docker 容器内，HTTP 地址不能写 localhost —— Consul Agent 在宿主机或另一容器里，要换成可路由的地址，比如 "http://host.docker.internal:8080/health" 或实际 service name

服务发现用srv, _, err := client.Health().Service("user-service", "", false, &api.QueryOptions{})总返回空列表

常见原因不是代码写错，而是 Consul 的服务匹配规则太严格："" 作为第二个参数（tag）表示“不匹配任何 tag”，但如果你注册服务时加了 tag（比如 Tags: []string{"v1"}），那就必须显式传 "v1" 或留空逻辑改用 PassingOnly: true。

实操建议：

• 调试时先去掉 tag 过滤，把第二个参数改成 ""，同时确保 PassingOnly: false，看能不能查到服务实例
• 确认服务注册成功后，手动 curl Consul API：curl "http://127.0.0.1:8500/v1/health/service/user-service?passing"，对比返回结果和 Go 代码拿到的是否一致
• 注意 client.Health().Service 返回的是 []*api.ServiceEntry，每个 ServiceEntry.Service 才是服务元信息，ServiceEntry.Node 是节点信息，别漏掉层级

goroutine 泄漏：注册/注销没配合 context 控制生命周期

Consul 的 watch 机制（比如用 client.Health().ServiceWatch）底层启动长连接 goroutine，如果服务进程退出前没主动 watch.Stop() 或没传带 cancel 的 context.Context，这些 goroutine 就一直挂着，pprof 里能看到堆积。

实操建议：

• 所有 Watch 操作都通过 context.WithCancel 包一层，在 os.Interrupt 信号处理中调用 cancel
• 服务注销要用 client.Agent().ServiceDeregister，且应在 defer 或 shutdown hook 中执行，别依赖 GC
• 本地开发时，注册服务后忘记 deregister，下次启动会因端口冲突或同名服务重复注册失败，报错 "service with same ID already registered" —— 注册前先 deregister 同 ID 服务是安全做法

Consul 集成真正的难点不在语法，而在网络拓扑和生命周期对齐：你的服务在哪跑、Consul Agent 在哪跑、健康检查路径从哪能访问到、进程退出时资源是否干净释放——这些地方一松动，就变成深夜排查的幽灵问题。