健康检查接口不能只返回{"status": "ok"}，因为K8s等系统仅依赖HTTP状态码和响应时效性，不解析JSON内容；必须主动探测下游依赖并返回结构化结果（如DB、Redis状态），失败时返回503及具体错误字段，避免掩盖真实故障。
健康检查接口为什么不能只返回 {"status": "ok"}
很多团队初期用 Gin 写 /health 时直接 c.JSON(200, map[string]string{"status": "ok"})，上线后被 K8s 或 Consul 反复标记为不健康。根本原因是：K8s 的 livenessProbe 和 readinessProbe 默认要求 HTTP 状态码为 200 且响应体可解析，但更关键的是——它会校验响应时间、超时行为和错误传播逻辑。纯静态响应掩盖了数据库连接、缓存连通性等真实依赖状态。
- 必须主动探测下游依赖（如
redis.Ping()、db.Exec("SELECT 1")），失败时返回 5xx 并带具体错误字段 - 响应体建议用结构体而非 map，方便后续加字段（如
timestamp、version） - 避免在 handler 里做耗时操作（如调用外部 HTTP 接口），否则 probe 超时导致误判
gin.HandlerFunc 中如何安全执行多依赖检查并聚合结果
别把所有 ping 操作串行写在 handler 里。Gin 的 handler 是同步阻塞的，一个依赖超时会拖垮整个探针。正确做法是并发发起检查，用 context.WithTimeout 控制单个依赖上限，并统一收集错误。
func healthCheckHandler(c *gin.Context) {
ctx, cancel := context.WithTimeout(c.Request.Context(), 2*time.Second)
defer cancel()
<pre class="brush:php;toolbar:false;">type result struct {
Name string
OK bool
Error string
}
ch := make(chan result, 3)
go func() {
err := dbPing(ctx)
ch <- result{Name: "database", OK: err == nil, Error: fmt.Sprintf("%v", err)}
}()
go func() {
err := redisPing(ctx)
ch <- result{Name: "redis", OK: err == nil, Error: fmt.Sprintf("%v", err)}
}()
collect := make([]result, 0, 2)
for i := 0; i < 2; i++ {
select {
case r := <-ch:
collect = append(collect, r)
case <-ctx.Done():
collect = append(collect, result{Name: "timeout", OK: false, Error: "context deadline exceeded"})
goto done
}
}done:
allOK := true
for _, r := range collect {
if !r.OK {
allOK = false
break
}
}
if allOK {
c.JSON(200, gin.H{"status": "ok", "checks": collect})
} else {
c.JSON(503, gin.H{"status": "unhealthy", "checks": collect})
}}
立即学习“go语言免费学习笔记（深入）”；
为什么 /readyz 和 /livez 要分离，且路由不能共用中间件
K8s 的 readinessProbe 和 livenessProbe 行为不同：readiness 失败时流量被摘除，但进程继续运行；liveness 失败则直接重启容器。如果共用同一 handler，重启风暴风险极高——比如 Redis 临时抖动，/readyz 返回 503 摘流量是对的，但 /livez 若也报 503 就会触发无意义重启。
-
/readyz应检查所有依赖（DB、Redis、下游 HTTP 服务），任一失败即 503 -
/livez只检查进程自身是否存活（如 goroutine 泄漏、内存爆满），甚至可简化为只返回 200 - 绝对不要给这两个路由加
authMiddleware或rateLimit，probe 请求必须绕过所有业务中间件
Gin 注册探针路由时容易忽略的三个配置点
很多人注册完 GET /health 就以为完事了，但 K8s 探针实际发请求时会暴露隐藏问题：
- 没禁用 Gin 的
Recovery中间件：当某个依赖 panic（如空指针调用redis.Client），默认 Recovery 会吞掉 panic 并返回 500，但 K8s 无法区分这是临时错误还是进程已崩溃，建议对探针路由单独移除 Recovery：r.NoRoute(func(c *gin.Context) { /* ... */ })不适用，应显式跳过 - 没设置
Content-Type: application/json：某些旧版 Ingress（如 Nginx 0.2x）会因缺少 header 强制转码，导致 JSON 解析失败，务必显式写c.Data(200, "application/json", data) - 没处理 HEAD 请求：K8s probe 默认发 GET，但部分平台（如 OpenShift）可能发 HEAD，Gin 默认不响应 HEAD，需额外注册：
r.HEAD("/readyz", healthCheckHandler)
真正难的不是写通接口，而是让每个依赖的失败能被准确归因、不引发级联故障。比如 DB 连接池耗尽时，要区分是连接数不够（该扩容），还是慢查询堆积（该优化 SQL），这些都得靠探针返回的结构化错误字段来定位。
