健康检查路由必须注册在中间件之前，/health仅做进程级检查，/readyz才查DB等依赖，路径须为纯GET、响应精简、禁用日志与鉴权，推荐用/healthz避免中间件劫持。

健康检查路由必须注册在中间件之前

Gin 默认的 gin.Default() 会自动加载日志和 panic 恢复中间件，如果健康检查路由写在 Use() 之后，像 JWT 验证、权限校验这类全局中间件就会拦截 /health 请求，返回 401 或 403，导致 Kubernetes 探针失败。

正确做法是：先注册健康路由，再挂载中间件；或者用框架提供的跳过机制：

• r.GET("/health", healthHandler) 必须放在 r.Use(...) 调用之前
• 若已启用全局中间件，改用 r.NoRoute() 拦截并手动分发：

  if c.Request.URL.Path == "/health" {
      healthHandler(c)
      return
  }

• 不推荐用 r.Group().Use() 包裹健康路由——它会让中间件生效

/health 和 /readyz 路由不能共用同一 handler

很多人图省事把 liveness 和 readiness 合并在一个 /health 端点里，结果数据库连不上时 readiness 应该失败，但 liveness 还在 OK，Kubernetes 就继续转发流量，引发雪崩。

区分逻辑的关键在于检查项和超时：

Skill Weave Chains — 技能链路由引擎

开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。

下载

• /health 只做进程级检查：HTTP server 是否仍在 Accept、主 goroutine 是否存活、无外部依赖
• /readyz 才查 DB 连接池、下游 gRPC Check()、本地配置加载状态等
• /readyz 响应必须控制在 1–2 秒内，Kubernetes 默认探针超时是 1 秒，超时即判失败
• 不要在 /readyz 里触发全量缓存重建或长耗时配置重载

路径选 /health 还是 /healthz？

二者都可，但语义和兼容性有差别：/health 直观通用，/healthz 是为避开某些中间件（比如某些监控 SDK 或旧版框架）对 /health 的默认劫持。

实际选型建议：

• 新项目优先用 /healthz，避免被未知中间件干扰
• 若服务已跑在 Kubernetes 中，确认 livenessProbe 和 readinessProbe 的 httpGet.path 与代码中完全一致，大小写和尾部斜杠都不能错
• 绝对不要用 /ping 或 /status：前者无法表达“就绪”语义，后者易与 Prometheus /metrics 混淆
• 路径必须是纯 GET，禁止带 query 参数（如 /health?deep=true），Kubernetes 探针不支持传参

响应内容要精简，别加额外中间件逻辑

健康检查响应不是业务接口，不需要日志记录、响应体压缩、CORS 头或 JSON 格式化美化——这些都会增加延迟或引入失败点。

实操要点：

• 直接用 c.Status(http.StatusOK) + c.String() 最轻量；若需结构化信息，用 c.JSON(http.StatusOK, map[string]string{"status": "OK"}) 即可
• 禁用所有日志中间件对健康路径的输出——高频探测日志会快速撑爆磁盘
• 不要在 handler 里调用 c.Next() 或嵌套其他中间件
• 如果用了 promhttp.Handler() 暴露指标，/metrics 和 /health 必须分离路由组，不共享中间件栈

真正的难点不在写 handler，而在于让这个端点始终“不被干扰”——它得绕过鉴权、跳过日志、扛住每秒数十次探测，同时又不能因某次 DB 检查慢了 1.2 秒就被 Kubernetes 杀掉。路径名、注册顺序、响应头、依赖检查粒度，每个细节都在影响它的可靠性。