健康检查中间件

健康检查中间件用于实时监控应用及其依赖（如数据库、缓存、外部服务等）的运行状态，便于自动化运维和故障告警。

健康检查中间件典型时序图

健康检查中间件处理流程

• 健康检查中间件负责拦截所有指向 /health 的请求，并将其交由健康检查逻辑处理。

• 中间件会遍历并执行所有已注册的健康检查项（Checker），每个检查项可以是对数据库、缓存、外部服务等的健康状态检测。检查项处理器（Checker）会依次执行所有健康检查逻辑，并收集每一项的健康状态（如 healthy/unhealthy）。

• 所有健康检查项都返回健康（Healthy），中间件会向客户端返回 HTTP 200 OK，表示服务健康。有任意一项返回不健康（Unhealthy），中间件会向客户端返回 HTTP 500 Unhealthy，表示服务存在异常。

快速启动

只需 3 步即可集成健康检查服务：

import spire_web_hosting.*
import spire_web_http.*
import spire_web_healthchecks.*
import spire_extensions_healthchecks.*

main() {
    // 1. 构建Web主机
    let builder = WebHost.createBuilder()

    // 2. 注册健康检查服务
    builder.services.addHealthChecks()
        .addCheck("health"){
            println("health check")
            return HealthCheckResult.healthy()
        }
    let host = builder.build()

    // 3. 启用健康检查中间件
    host.useHealthChecks("/health")
    host.run()
}

添加依赖

需要在依赖配置文件(cjpm.toml)中添加如下依赖：

[dependencies]
  spire_web_http = { path = "../spire_web_http"}
  spire_web_hosting = { path = "../spire_web_hosting"}
  spire_web_healthchecks = { path = "../spire_web_healthchecks"}
  spire_extensions_injection = { path = "../spire_extensions_injection"}
  spire_extensions_healthchecks = {path = "../spire_extensions_healthchecks"}

自定义健康检查

可注册自定义健康检查项（checker）：

main() {
    let builder = WebHost.createBuilder()
    // 注册健康检查服务，并添加自定义检查项
    builder.services.addHealthChecks()
        // 添加自检项
        .addCheck("self"){ 
            return HealthCheckResult.healthy() 
        } 
        // 添加数据库连接检查项
        .addCheck("MySql") { 
            let dbConnected = checkDatabaseConnection() 
            if (dbConnected) { 
                return HealthCheckResult.healthy() 
            } else { 
                return HealthCheckResult.unhealthy(description: "数据库连接失败", exception: None) 
            } 
        } 

    let host = builder.build()
    // 配置健康检查中间件，监听/health端点
    host.useHealthChecks("/health")
    host.run()
    return 0
}

// 假设的数据库连接检测函数，实际应替换为真实逻辑
public func checkDatabaseConnection(): Bool {
    // 这里可以写实际的数据库ping逻辑
    return true // 示例：始终返回连接正常
}

最佳实践

• 健康检查端点建议仅暴露给内部或受控网络
• 可结合监控系统（如 K8s、Prometheus）实现定时探针，自动探活
• 合理拆分健康检查项，便于定位问题
• 可自定义健康检查路径（如/healthz、/ready 等）
• 响应内容可包含各项检查的详细状态，便于排查