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

健康检查接口应返回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) 却没意识到这会直接导致服务被下线。

• 始终用 w.WriteHeader(http.StatusOK) 显式设置状态码
• body 可选，但建议返回轻量 json，如 {"status":"ok","uptime_sec":12345}
• 避免在 handler 中调用 log.Fatal 或 panic，否则整个进程退出，比返回 500 更糟

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

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

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

立即学习“go语言免费学习笔记（深入）”；

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).Encode(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），否则会拖垮整个就绪判断流程。