标准做法是使用 /health 或 /healthz 路径,二者最通用且被 Kubernetes 及主流代理识别;/health 语义直观,/healthz 可避免中间件劫持;禁止使用 /status 或 /ping 等易混淆路径。

健康检查接口该挂到哪个路由路径
标准做法是用 /health 或 /healthz,Iris 默认不拦截这些路径,但要注意别和已有路由冲突。如果项目已注册了 /health 前缀的其他路由(比如 /health/db),直接挂根级 /health 会 404——Iris 路由匹配是精确优先的,不会自动 fallback。
推荐一开始就明确约定:健康检查只响应 GET /health,且不带任何 query 参数或 body。避免后续被误加中间件(比如 JWT 鉴权)导致检查失败。
用 ctx.StatusCode 和 ctx.JSON 返回结构化响应
Iris 的上下文 ctx 提供了轻量级响应方法,不需要手动设置 header 或序列化。健康检查不需复杂逻辑,直接返回状态码 + 简单 JSON 即可:
<pre class="brush:php;toolbar:false;">app.Get("/health", func(ctx iris.Context) {
ctx.StatusCode(iris.StatusOK)
ctx.JSON(map[string]string{"status": "ok", "timestamp": time.Now().UTC().Format(time.RFC3339)})
})
注意两点:
立即学习“go语言免费学习笔记(深入)”;
- 必须显式调用
ctx.StatusCode(iris.StatusOK),否则默认是 200,但某些 K8s 探针(如 livenessProbe)对非 2xx 响应会视为失败,而 Iris 在写 JSON 前若未设状态码,可能被后续中间件覆盖 - 避免在健康检查里调用数据库
ping或远程 HTTP 请求——这会让探针变慢甚至超时;真要查依赖,得单独用/health/db这类子路径,并配独立超时
如何避免中间件干扰健康检查
常见错误是把日志、鉴权、CORS 中间件全局注册,结果健康检查也被要求传 token 或被记录大量日志,既不安全又影响可观测性判断。
正确做法是绕过中间件链:
- 用
app.Get("/health", handler)直接注册,不要套在app.Use(...)后面 - 如果必须复用部分中间件(比如统一日志格式),用
app.Get("/health", myLogMiddleware, healthHandler),但确保myLogMiddleware内部对/health路径做短路处理(if ctx.Path() == "/health" { ctx.Next(); return }) - K8s 的
livenessProbe和readinessProbe默认不带Authorizationheader,别在健康检查 handler 里调ctx.GetUser这类依赖 auth 的方法
为什么不用 ctx.Text 或纯字符串响应
虽然 ctx.Text(iris.StatusOK, "ok") 更快,但多数运维工具(Prometheus exporter、K8s probe、APM)默认解析 JSON 响应体。返回纯文本会导致:
- 某些探针配置了
httpGet.expectedStatusCodes: [200]但实际校验 response body 字段,结果无法提取status - 日志系统按 JSON 格式解析时,把
"ok"当作非法 JSON 报错 - 前端监控面板无法统一渲染字段(比如取
.timestamp做延迟分析)
JSON 开销几乎可忽略,map[string]string 序列化比字符串拼接还快一点。真有性能洁癖,才考虑 ctx.WriteString 配固定 JSON 字符串,但得自己保证双引号和转义正确。
最常被忽略的是时间戳字段:用 time.RFC3339 而不是 time.Now().String(),前者能被所有语言标准库无歧义解析,后者在不同 Go 版本下格式可能微调。


















