Consul健康检查必须暴露独立/health端点，注册时需动态生成唯一ID并正确配置HTTP检查地址、间隔与超时，客户端调用前须过滤passing状态节点且配合超时重试。
Consul健康检查必须暴露/health端点
Gin服务启动后，Consul要能判断节点是否存活，前提是它能访问到一个稳定、低开销的健康检测接口。不能用业务路由（比如/ping）凑数，因为业务逻辑可能引入延迟或异常，导致Consul误判下线。
正确做法是单独暴露一个轻量级/health端点，只返回状态码和固定JSON，不依赖数据库、缓存或下游服务：
func main() {
r := gin.Default()
r.GET("/health", func(c *gin.Context) {
c.JSON(200, gin.H{"status": "passing"})
})
r.Run(":8080")
}
- Consul配置中
HTTP字段必须指向这个地址，例如http://127.0.0.1:8080/health -
Interval建议设为10s，太短会增加服务压力，太长（如>30s）会导致故障节点滞留时间过久 - 不要在
/health里加任何额外逻辑——哪怕只是查一次Redis，都可能让Consul把整个服务标为critical
注册时必须传入唯一ID和服务名
Consul靠ID区分同一服务的多个实例。如果所有实例都用相同ID（比如硬编码为"user-service"），Consul只会保留最后一个注册的节点，其余被覆盖，自动剔除根本无从谈起。
注册代码里要动态生成ID，常见方式是拼接IP+端口或加UUID：
id := fmt.Sprintf("user-service-%s-%d", getLocalIP(), 8080)
registration := &api.AgentServiceRegistration{
ID: id,
Name: "user-service",
Address: getLocalIP(),
Port: 8080,
Check: &api.AgentServiceCheck{
HTTP: fmt.Sprintf("http://%s:%d/health", getLocalIP(), 8080),
Interval: "10s",
Timeout: "5s",
},
}
-
Name用于服务发现查询，必须和消费者调用时用的名字一致（如consulClient.Health.Service("user-service")） -
Address填实际监听IP，别用0.0.0.0——Consul返回的地址必须能被其他服务直接访问 - 注册失败时别静默吞掉错误，至少打日志：
zap.Error(err)，否则节点“看似注册成功”实则未进Consul列表
Gin客户端调用前必须过滤passing状态
Consul的Health.Service接口返回的是全量节点（包括passing、warning、critical），Gin做负载均衡时若没筛掉非passing节点，请求照样会发到已宕机的实例上。
每次获取服务列表后，必须显式过滤：
services, _, err := consulClient.Health().Service("user-service", "", false, nil)
if err != nil {
return nil, err
}
var endpoints []string
for _, s := range services {
if s.Service.Address != "" && s.Checks.AggregatedStatus == "passing" {
endpoints = append(endpoints, fmt.Sprintf("http://%s:%d", s.Service.Address, s.Service.Port))
}
}
- 注意
AggregatedStatus字段，不是Status——前者是Consul综合所有检查项后的最终判定 - 别省略
s.Service.Address != ""判断，某些场景下Consul可能返回空地址但状态为passing - 如果用gRPC而非HTTP，这里拼的是
host:port字符串，供grpc.Dial使用
客户端轮询需配合重试与超时控制
即使Consul实时剔除了故障节点，Gin客户端仍可能因网络抖动、DNS缓存等原因短暂连上刚下线的实例。单靠服务发现不够，必须在调用层补双重保险。
推荐组合：短超时 + 有限重试 + proxy_next_upstream等效逻辑（手动实现）：
- HTTP调用用
http.Client设置Timeout: 3s，避免卡死 - 对单个endpoint失败后，从
endpoints列表中剔除它，再选下一个重试（最多1–2次） - 别用全局长连接池直连某个固定IP——连接池不会自动感知Consul状态变更，得自己维护连接健康度
最易忽略的一点：Consul健康检查周期（默认10s）和你的客户端重试间隔之间存在窗口期。如果服务秒级崩溃，这10秒内请求仍会失败，得靠客户端熔断兜底，不能全押在Consul上。
