贝利信息

NEWS CENTER 新闻中心

Golang Web服务如何做健康检查_健康检查接口设计

日期：2026-01-17 00:00 / 作者：P粉602998670
上一篇 下一篇
健康检查接口应返回200 OK状态码，因Kubernetes等组件将非200（尤其5xx）视为不健康；body可选但建议返回轻量JSON如{"status":"ok"}；严禁log.Fatal或panic；需有限度探测关键依赖以确保真正健康。

健康检查接口该返回什么状态码

健康检查接口必须返回 200 OK 表示服务可接受流量，任何非 200（尤其是 5xx）都会被 Kubernetes、Nginx 或 Consul 等组件判定为“不健康”，触发剔除或重试。不要用 204 No Content 或 302 —— 它们在多数探测器中等价于失败。

常见错误：返回 200 但 body 是空字符串或 {"status":"down"}，而探测器只看状态码；或误用 http.Error(w, "...", http.StatusServiceUnavailable) 却没意识到这会直接导致服务被下线。

如何判断“真正健康”而不是只检查进程存活

只返回 200 不代表数据库连得上、缓存可用、下游依赖响应正常。真正的健康检查需要做有限度的依赖探活，但必须满足：快（

典型做法是并发探测关键依赖，任一失败即返回 503 Service Unavailable，但注意超时控制和 fallback 逻辑：

func healthHandler(w http.ResponseWriter, r *http.Request) {
    ctx, cancel := context.WithTimeout(r.Context(), 80*time.Millisecond)
    defer cancel()

dbOk := checkDB(ctx)
cacheOk := checkRedis(ctx)
// 下游 API 可选，非核心依赖建议跳过或设宽松超时

if !dbOk || !cacheOk {
    w.WriteHeader(http.StatusServiceUnavailable)
    json.NewEncoder(w).Encode(map[string]bool{"db": dbOk, "redis": cacheOk})
    return
}

w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encod
e(map[string]interface{}{"status": "ok"})
}


    

  • 
checkDB 和 checkRedis 必须使用带 ctx 的方法（如 db.PingContext(ctx)），不能阻塞
    • 

  • 不要在健康检查里执行 SQL 查询或复杂计算，Ping 足够
    • 

  • 如果 Redis 临时不可用但业务可降级（如用本地内存兜底），可将 cacheOk 视为非致命，只记录日志不中断健康态
    • 



路径选 /health 还是 /healthz？


选 /healthz（或 /readyz、/livez）更稳妥。Kubernetes 原生支持 *z 后缀语义：  
- /livez：进程是否存活（如未 panic、goroutine 未卡死）  
- /readyz：是否准备好接收流量（含依赖检查）  
- /healthz 是历史别名，行为常等同于 /readyz


用 /health 容易和前端 SPA 的路由冲突（比如 Vue Router fallback 到 index.html），也和部分监控工具默认路径重叠。


    

  • Kubernetes livenessProbe 默认不校验响应 body，但 readinessProbe 建议用 /readyz

    • 

  • 如果已有服务暴露了 /health，可通过反向代理映射（如 Nginx 把 /readyz 代理到 /health），但后端代码里仍建议统一用 z 后缀
    • 

  • 避免暴露 /debug/pprof 或 /metrics 在同一路径层级，防止探测器误刷出敏感信息
    • 



为什么不能把健康检查逻辑写在中间件里


因为中间件会拦截所有请求，包括静态文件、API 路由、甚至 404 请求。一旦健康检查逻辑出错（比如依赖超时 panic），会导致整个服务的 HTTP 处理链崩溃，所有请求失败 —— 这比单个健康接口挂掉严重得多。


正确做法是注册独立路由，绕过常规中间件链：
router := gin.Default()
// 普通路由走完整中间件（鉴权、日志、recover）
router.GET("/api/users", authMiddleware(), userHandler)

// 健康检查直通，不经过 recover 或耗时中间件
router.NoRoute(func(c *gin.Context) {
if c.Request.URL.Path == "/readyz" {
healthHandler(c.Writer, c.Request)
return
}
c.Next()
})
    

  • 用 NoRoute 或显式 GET("/readyz", ...) 确保路径不被其他中间件污染
    • 

  • 不要在健康 handler 里调用 c.Abort() 或修改 c.Writer 多次，容易触发 “http: multiple response.WriteHeader calls”
    • 

  • 若用 net/http 标准库，直接 http.HandleFunc("/readyz", healthHandler) 最干净
    • 



实际部署时最容易忽略的是依赖探测的超时值——它必须显著短于探测器自身的 timeout（如 K8s probe timeoutSeconds=5，则内部 Ping 超时最多设 2s），否则会拖垮整个就绪判断流程。