健康检查接口应返回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），否则会拖垮整个就绪判断流程。
