Consul客户端必须显式配置HTTP超时（3–5秒）并使用127.0.0.1地址，服务注册须在Gin启动前完成且健康检查路径需可访问；本地调试应让Gin运行于主机而非Docker，服务发现需过滤passing状态节点。
Consul 客户端必须显式配置超时，否则 service.Register 会卡死
本地开发时最常见的现象是：Go 服务启动后一直 hang 在 agent.ServiceRegister，几秒甚至十几秒才报错或继续。这不是代码写错了，而是 Consul 客户端默认没设 HTTP 超时——网络不通、Consul 没启、地址写成 localhost 而非 127.0.0.1 都会导致阻塞。
必须手动构造 consul.Config，并传入带 Timeout 的 http.Transport：
cfg := &consul.Config{
Address: "127.0.0.1:8500",
HttpTransport: &http.Transport{
Timeout: 3 * time.Second,
MaxIdleConns: 10,
MaxIdleConnsPerHost: 10,
},
}
client, _ := consul.NewClient(cfg)
-
Timeout必须设为 3–5 秒，不能依赖默认值（底层是0，即无限等待） -
Address用127.0.0.1，别用localhost—— macOS 和某些 Linux 下 DNS 解析可能引入毫秒级延迟，叠加无超时就容易触发卡顿 - 本地 Consul 启动命令要加
-client=0.0.0.0，否则默认只监听127.0.0.1:8500的 loopback 接口，部分容器网络或 IPv6 环境下反而连不上
Gin 启动前必须完成 Consul 服务注册，且健康检查路径要可访问
很多人把服务注册逻辑放在 Gin 的某个中间件或路由 handler 里，结果请求来了才发现服务根本没注册成功——注册必须在 gin.Engine.Run() 之前做完，且要等注册+健康检查就绪后再开监听端口。
关键点：
- 注册时不要只填
Name和Port，必须配Check.HTTP，比如"http://127.0.0.1:8000/health"；Consul 会主动轮询这个地址，返回非 200 就标记为failing -
/health这个 endpoint 必须由 Gin 提供，且不能有鉴权、重定向、耗时 >10s（Consul 默认 HTTP 检查超时是 10s） - 注册后建议加一个简单轮询：
client.Health().ServiceNodes("your-service-name", "", false, nil)，确认返回的节点里Node.Service.Status == "passing"再继续
本地调试时避免把 Gin 服务也扔进 Docker，Consul 单独容器即可
常见错误是写一个 docker-compose.yml 把 Gin 服务和 Consul 全部跑在容器里，结果调试断点失效、日志刷不出来、go run 编译慢得无法接受。
正确分工：
- Consul、Redis、PostgreSQL 这类有状态中间件用 Docker 启动（
docker run -d --name consul -p 8500:8500 -p 8600:8600 consul agent -dev -client=0.0.0.0 -bind=0.0.0.0） - Gin 服务永远用主机进程运行：
go run main.go，这样 dlv 断点、环境变量注入、热重载（air）全都能用 - 确保 Gin 服务里读取的 Consul 地址是
127.0.0.1:8500，不是容器名或host.docker.internal（后者在 Linux 上不默认支持）
服务发现调用 Consul API 时，必须过滤 passing 状态节点
直接调用 client.Health().ServiceNodes("xxx", "", false, nil) 返回的是一堆混杂状态的节点，里面可能包含刚宕机还没被 Consul 清理掉的 critical 实例。Gin 如果拿第一个就转发，大概率 503。
安全做法是显式过滤：
nodes, _, err := client.Health().ServiceNodes("user-srv", "", false, nil)
if err != nil {
return nil, err
}
var passing []string
for _, n := range nodes {
if n.Service.Status == "passing" {
passing = append(passing, net.JoinHostPort(n.Node.Address, strconv.Itoa(n.Service.Port)))
}
}
- 别手写随机或轮询逻辑——生产环境应接入
google.golang.org/grpc/balancer/roundrobin或hashicorp/go-hostpool - 如果 Gin 要调用 gRPC 服务，注意 gRPC 的
resolver需自己实现，不能只靠 Consul 返回的 IP 列表拼接target - 本地开发阶段可以先硬编码一个
127.0.0.1:9000测试通路，再切到 Consul 动态发现，避免一上来就陷在服务发现链路里
Consul 集成里最隐蔽的坑不是注册失败，而是注册成功了、健康检查也 green 了，但服务发现查出来的节点却是 critical 状态——往往因为 Check.Timeout 比你的 /health 响应时间还短，或者 Consul 轮询时用了错误的 Host header 导致 Gin 的中间件拦截了请求。这些细节不打日志、不抓包，几乎没法定位。
