就绪探针必须验证下游依赖连通性而非仅返回200：/readyz应同步执行db.Ping()、redis.Ping()等带超时（≤3s）的检查，任一失败即返503；需用ReadinessChecker接口解耦，probe参数须匹配实际耗时，且Check()必须使用带超时的context。
健康检查端点本身不报错，但 Kubernetes 频繁重启 Pod，大概率是就绪探针（readinessProbe）配置与 Gin 应用实际状态脱节——比如返回 200 了，但数据库连接还没通、或 gRPC 依赖服务不可达。
就绪探针为什么不能只返回 HTTP 200
单纯在 /health 返回 {"status": "ok"} 是典型“假就绪”：Gin 进程起来了，路由注册了，HTTP 服务能响应，但下游依赖（如 PostgreSQL、Redis、Consul、其他微服务）可能完全没连上。Kubernetes 会把流量导给这个“看似健康”的实例，结果请求全部失败。
真实就绪必须包含依赖连通性验证。常见错误现象包括：
- Pod 处于
Running状态但持续503 Service Unavailable -
kubectl get pods显示READY 1/1，但kubectl logs里有大量数据库超时日志 - 滚动更新时新 Pod 上线后立刻被路由打满，随即因依赖未就绪而崩溃
实操建议：
- 就绪探针路径（如
/readyz）应调用一个独立 handler，**不复用/health**（后者可仅检查进程存活） - 该 handler 必须同步执行关键依赖的连通性检查，例如：
db.PingContext()、redis.Ping()、consul.Health().NodeHealth() - 所有检查必须设置明确超时（建议 ≤3s），避免阻塞 probe 导致 Pod 卡在
NotReady - 任意一项失败，立即返回
http.StatusServiceUnavailable (503)，不要尝试重试或降级
Gin 中实现可组合的就绪检查逻辑
硬编码一堆 Ping 调用会让 handler 耦合严重、难以测试。推荐用接口抽象检查器，按需注入：
type ReadinessChecker interface {
Name() string
Check() error
}
func NewDBChecker(db *sql.DB) ReadinessChecker {
return &dbChecker{db: db}
}
func (c *dbChecker) Name() string { return "database" }
func (c *dbChecker) Check() error { return c.db.Ping() }
在 handler 中聚合执行：
func readinessHandler(checkers []ReadinessChecker) gin.HandlerFunc {
return func(c *gin.Context) {
var errs []string
for _, chk := range checkers {
if err := chk.Check(); err != nil {
errs = append(errs, fmt.Sprintf("%s: %v", chk.Name(), err))
}
}
if len(errs) > 0 {
c.JSON(http.StatusServiceUnavailable, gin.H{"errors": errs})
return
}
c.JSON(http.StatusOK, gin.H{"status": "ready"})
}
}
使用时只需传入具体检查器实例：
- 本地开发可只注入
NewDBChecker(db)，跳过 Consul 检查 - 生产环境加上
NewConsulChecker(client)和NewGRPCHealthChecker(conn) - 每个检查器内部控制自己的超时和重试策略，不干扰 probe 整体生命周期
就绪探针配置与 Gin 的协同要点
Kubernetes 的 readinessProbe 参数不是越激进越好，必须匹配 Gin handler 的实际耗时与容错逻辑：
-
initialDelaySeconds：至少设为应用启动+依赖初始化完成所需时间（例如 DB 连接池 warm-up 可能要 5–8s），**不能依赖“快速失败”来掩盖启动慢问题** -
periodSeconds和timeoutSeconds：建议设为相同值（如5），避免 probe 超时后被 kubelet 强制中断，导致 handler 中的defer清理逻辑失效 -
failureThreshold：设为1或2即可，就绪状态本应稳定；频繁抖动说明依赖本身不可靠，该修的是服务而非 probe - 务必关闭 Gin 的
gin.ReleaseMode日志（用gin.SetMode(gin.ReleaseMode)），否则 probe 请求日志刷屏，干扰真实错误排查
最容易被忽略的是：Gin 的 Context 默认没有绑定 probe 请求的上下文取消信号。若某个 Check() 调用卡住，整个 probe 会 hang 住，触发 kubelet 杀进程。必须显式传入带 timeout 的 context.Context 到每个检查器中。
