Consul客户端初始化必须显式配置超时和重试，否则service.Register或Health.ServiceNodes会卡死数秒；注册须带健康检查并主动维护TTL；服务发现必须过滤passing状态节点且客户端实例应全局复用。
Consul客户端初始化必须显式配置超时和重试
不设超时的 consul.NewClient 会导致 service.Register 或 Health.ServiceNodes 卡死数秒，尤其在 Consul 临时不可用或网络抖动时，直接拖垮 Gin 服务启动流程。
必须手动构造 http.Transport 并传入 consul.Config：
-
Timeout设为3 * time.Second—— 防止阻塞主 goroutine -
KeepAlive禁用或设为短周期（如30 * time.Second）—— 避免 Consul 重启后长连接僵死 -
RetryMax: 2+RetryWaitMin: 100 * time.Millisecond—— 应对短暂连接失败 -
MaxIdleConns和MaxIdleConnsPerHost建议设为10，避免连接池耗尽
示例配置：
cfg := &consul.Config{
Address: "127.0.0.1:8500",
HttpTransport: &http.Transport{
Timeout: 3 * time.Second,
KeepAlive: 30 * time.Second,
MaxIdleConns: 10,
MaxIdleConnsPerHost: 10,
},
WaitTime: 5 * time.Second,
}
client, _ := consul.NewClient(cfg)
服务注册必须带健康检查且主动维护 TTL
只调一次 agent.ServiceRegister 是不够的。Consul 默认用 TTL 类型健康检查，但 Go 微服务若不持续上报心跳，注册项会在 TTL 过期后被自动剔除 —— 表现为“服务已注册却无法被发现”。
两种可靠做法：
- 改用
Check.HTTP：Consul 主动轮询你的/health接口，无需心跳逻辑；路径必须返回200，且响应头不能含重定向 - 若坚持用
TTL：注册时指定Check.TTL = "10s"，并另起 goroutine 每5s调用一次agent.UpdateTTL -
Check.Timeout必须显式设置（默认 10s），否则慢响应的/health会被 Consul 标记为 failing
Gin 中暴露健康端点示例：
r.GET("/health", func(c *gin.Context) {
c.Status(200)
})
服务发现必须过滤 passing 状态节点
api.Health.ServiceNodes 返回的是原始列表，混杂 passing、warning、critical 状态节点。直接取第一个或随机选，大概率命中宕机实例。
关键动作只有两个：
- 遍历结果，只保留
Node.Service.Status == "passing"的节点 - 别手写轮询/随机逻辑 —— 用
hashicorp/go-hostpool做连接池与故障剔除，或集成 gRPC 的roundrobin/pickfirstbalancer（若走 gRPC） - 每次调用前重新查 Consul（或加短缓存，如 5s），避免使用过期节点列表
过滤示例：
nodes, _, err := client.Health().ServiceNodes("user-service", "", false, nil)
if err != nil {
return nil, err
}
var passing []string
for _, n := range nodes {
if n.Service.Status == "passing" {
passing = append(passing, fmt.Sprintf("%s:%d", n.Service.Address, n.Service.Port))
}
}
Gin 调用远程服务时要隔离注册/发现逻辑
把 Consul 初始化、服务注册、节点发现全堆在 main.go 里，会导致代码耦合、测试困难、升级成本高。
推荐分层方式：
- 单独建
pkg/registry包，封装NewConsulClient、RegisterService、Discover方法，接收*gin.Engine或服务名作为参数 - 在 Gin 中间件或 handler 里按需调用
Discover("order-service")，拿到地址后再发起 HTTP/gRPC 请求 - 不要在
init()或全局变量里做服务发现 —— 启动时可能 Consul 还没 ready，应改为首次调用时懒加载 + 重试
最易被忽略的一点：Gin 的 handler 是并发执行的，所有 Consul 客户端实例（*consul.Client）必须是全局复用的单例，不能每次请求都 new 一个。
