健康检查端点设计

/health 端点的设计：检查什么、返回格式、与 Docker HEALTHCHECK 和 Kubernetes 探针的配合。

#type / concept #status / growing #tech / dev / backend

[!info] related notes

框架: Gin HTTP 框架

部署: Docker Compose 多服务开发环境

健康检查端点设计

设计原则

快速返回 — 每个依赖检查设超时，不要阻塞
不暴露敏感信息 — 不返回密码、连接字符串
区分就绪和存活 — K8s 中 /ready 和 /healthz 含义不同
返回结构化数据 — 不只是 200/500，要说明哪个依赖有问题

实现

r.GET("/api/health", func(c *gin.Context) {
    dbOK := checkDB()
    redisOK := checkRedis()

    status := 200
    if !dbOK || !redisOK {
        status = 503
    }

    c.JSON(status, gin.H{
        "status": "ok",
        "db":     map[bool]string{true: "ok", false: "unreachable"}[dbOK],
        "redis":  map[bool]string{true: "ok", false: "unreachable"}[redisOK],
    })
})

Docker HEALTHCHECK

HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD curl -f http://localhost:8080/api/health || exit 1

start-period: 容器启动宽限期，期间检查失败不算 unhealthy
retries: 连续失败 N 次才标记 unhealthy

检查什么

依赖	检查方式	必须
数据库	`db.Ping()`	✅
Redis	`redis.Ping()`	✅
AI 服务	`http.Get(aiURL + "/health")`	可选

AI 服务检查可选——如果 AI 服务挂了，后端还可以处理非 AI 相关的请求。