必须区分/healthz和/readyz：/healthz仅检查进程存活（时钟、goroutine、HTTP accept），/readyz同步验证依赖（DB、Redis等）；/readyz需≤3s响应、用atomic.Bool缓存探测结果、返回503而非500。
微服务健康检查接口不能只返回 200 OK，必须区分“进程活着”和“服务真能干活”——这是线上故障排查中最常被忽视的分水岭。
为什么必须拆开 /healthz 和 /readyz
Kubernetes 的 livenessProbe 和 readinessProbe 语义完全不同，复用同一个接口会导致误判重启或流量劫持。
-
/healthz只做秒级轻量判断：时钟是否正常、goroutine 是否卡死、HTTP server 是否还在 accept 连接 -
/readyz必须同步检查依赖：数据库连通性、Redis ping、配置加载完成标志、gRPC 依赖服务 dial 状态 - 若把 DB
Ping()放进/healthz，D
B 挂了会反复重启容器，掩盖真实问题；若漏掉
/readyz，流量会打到没连上 DB 的实例上，直接雪崩
如何写一个不拖慢请求的 /readyz handler
就绪检查不是诊断工具，是流量开关。它必须快（≤3s）、可缓存、无副作用。
- 所有依赖检查必须带
context.WithTimeout(ctx, 2*time.Second)，超时立即返回失败 - 避免每次请求都
db.PingContext()—— 改为后台 goroutine 定期探测，用atomic.Bool缓存结果 - 不要在 handler 里执行 SQL 查询或 Redis
GET，PING或CONN就够了 - 如果依赖项多（DB + Redis + Kafka），用
errgroup.WithContext并发检查，但要统一超时控制
var dbReady = atomic.Bool{}
var redisReady = atomic.Bool{}
func initReadinessProbes(db sql.DB, rdb redis.Client) {
go func() {
ticker := time.NewTicker(5 time.Second)
defer ticker.Stop()
for range ticker.C {
ctx, cancel := context.WithTimeout(context.Background(), 1time.Second)
if db.PingContext(ctx) == nil {
dbReady.Store(true)
} else {
dbReady.Store(false)
}
cancel()
ctx, cancel = context.WithTimeout(context.Background(), 1*time.Second)
if rdb.Ping(ctx).Err() == nil {
redisReady.Store(true)
} else {
redisReady.Store(false)
}
cancel()
}
}()}
func readyzHandler(w http.ResponseWriter, r *http.Request) {
if !dbReady.Load() || !redisReady.Load() {
http.Error(w, "dependencies not ready", http.StatusServiceUnavailable)
return
}
w.WriteHeader(http.StatusOK)
w.Write([]byte("ready"))
}
http.Error 返回码选哪个？别用 500
健康检查失败 ≠ 服务崩溃，而是“暂时不可用”。返回错误码直接影响 K8s 行为：
-
http.StatusServiceUnavailable (503)：正确选择，告诉 K8s “别转发流量”，但不重启容器 -
http.StatusInternalServerError (500)：危险！K8s 会认为进程异常，触发livenessProbe失败并重启 -
http.StatusNotFound (404)：说明路由没注册，属于部署错误，不是健康状态问题
最易被忽略的一点：/readyz 的响应体内容本身不重要，但 HTTP 状态码和响应时间必须稳定。哪怕所有依赖都挂了，也要在 3 秒内返回 503，而不是卡住或 panic —— 否则 K8s 会因超时判定为 probe failed，行为不可控。
