Spring Boot 如何整合 Actuator Health 实现健康检查？

Spring Boot 对健康检查的支持并非独立模块，而是通过 spring-boot-starter-actuator 提供的 HealthEndpoint 实现的。理解这一点后，整合过程会清晰很多。先看最小闭环：引入依赖、配置暴露端点、访问 /actuator/health，得到 UP 或 DOWN。这个默认状态只反映 Spring 上下文是否正常启动，并不代表数据库、Redis 或下游服务可用。为了得到可信的健康信号，必须扩展自定义 HealthIndicator，并理解多个指示器如何聚合。

健康检查的核心机制与依赖配置

Spring Boot 的健康检查能力来自 Actuator 模块。在 Maven 项目中，需要引入 spring-boot-starter-actuator 依赖。如果是 Gradle 项目，对应写法是 implementation 'org.springframework.boot:spring-boot-starter-actuator'。引入后，框架会自动注册一个 HealthEndpoint，并暴露在 /actuator/health 路径下。不过默认情况下，只有 health 端点是启用的，其他端点如 info、metrics 需要额外配置才能访问。

配置健康检查的第一步是确认端点是否暴露。在 application.yml 中可以这样写：

management:
  endpoints:
    web:
      exposure:
        include: health,info
  endpoint:
    health:
      show-details: always

这里的 show-details: always 会返回每个健康指示器的明细，适合开发调试；生产环境建议改成 when-authorized 或 never，避免泄露内部组件信息。health 端点默认会聚合所有实现了 HealthIndicator 接口的 Bean，判定规则是只要有一个 DOWN，整体状态就是 DOWN。

最小闭环完成后，访问 /actuator/health 会返回类似 JSON：

{
  "status": "UP",
  "components": {
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 250685575168,
        "free": 133456543744,
        "threshold": 10485760
      }
    },
    "ping": {
      "status": "UP"
    }
  }
}

这个默认结果只检查了磁盘空间和 ping 自身，根本没有触碰数据库或缓存。因此，要让健康检查真正反映应用依赖的外部系统，必须自己扩展 HealthIndicator。

自定义 HealthIndicator 实现业务级探测

实现一个自定义健康指示器非常简单，只需注册一个实现 HealthIndicator 接口的 Bean，并重写 health() 方法。下面以检测 MySQL 连接是否可用为例：

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Component;

@Component
public class DatabaseHealthIndicator implements HealthIndicator {

    private final JdbcTemplate jdbcTemplate;

    public DatabaseHealthIndicator(JdbcTemplate jdbcTemplate) {
        this.jdbcTemplate = jdbcTemplate;
    }

    @Override
    public Health health() {
        try {
            Integer result = jdbcTemplate.queryForObject("SELECT 1", Integer.class);
            if (result != null && result == 1) {
                return Health.up()
                        .withDetail("database", "MySQL")
                        .withDetail("ping", "ok")
                        .build();
            }
            return Health.down()
                    .withDetail("database", "MySQL")
                    .withDetail("ping", "unexpected result")
                    .build();
        } catch (Exception e) {
            return Health.down()
                    .withDetail("database", "MySQL")
                    .withDetail("error", e.getMessage())
                    .build();
        }
    }
}

这段代码中，Health.up() 和 Health.down() 分别构建健康的 UP 状态和不健康的 DOWN 状态，withDetail 方法可以附加任意键值对，这些信息会出现在 /actuator/health 的 components 字段里。需要注意的是，不要在 details 中放入密码、连接串等敏感信息，否则 show-details 开启时会直接暴露。

如果不想写独立的类，也可以使用 Spring Boot 提供的 AbstractHealthIndicator，它内部处理了异常捕获和状态判断，只需要实现 doHealthCheck 方法。对于需要异步或定时探测的场景，可以配合 ReactiveHealthIndicator，返回 Mono 或 Flux，适合 WebFlux 应用。无论哪种方式，核心思想都是把一次轻量级探活封装成可重复执行的组件。

除了数据库，还可以为 Redis、RabbitMQ、Elasticsearch 等编写类似的指示器。例如检测 Redis 连接：

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.data.redis.connection.RedisConnectionFactory;
import org.springframework.data.redis.connection.RedisConnection;
import org.springframework.stereotype.Component;

@Component
public class RedisHealthIndicator implements HealthIndicator {

    private final RedisConnectionFactory redisConnectionFactory;

    public RedisHealthIndicator(RedisConnectionFactory redisConnectionFactory) {
        this.redisConnectionFactory = redisConnectionFactory;
    }

    @Override
    public Health health() {
        try (RedisConnection connection = redisConnectionFactory.getConnection()) {
            String pong = connection.ping();
            if ("PONG".equalsIgnoreCase(pong)) {
                return Health.up().withDetail("redis", "reachable").build();
            } else {
                return Health.down().withDetail("redis", "unreachable").build();
            }
        } catch (Exception e) {
            return Health.down().withDetail("redis", e.getMessage()).build();
        }
    }
}

这些自定义指示器会被 HealthEndpoint 自动收集，多个指示器的结果最终合并为一个整体状态。如果一个指示器返回 DOWN，整个 health 就是 DOWN；只有全部 UP 时才是 UP。这种短路聚合非常适合做负载均衡或 Kubernetes 的存活探针。

健康状态聚合与生产环境注意事项

健康检查的聚合逻辑由 HealthAggregator 负责，默认实现是 OrderedHealthAggregator。它会按顺序收集所有 HealthIndicator 的结果，只要有一个状态为 DOWN，最终状态就是 DOWN。这种策略在微服务治理中非常有用，可以让服务在依赖不可用时自动摘除流量。但有时某些依赖并不是核心路径，比如一个可选的统计服务挂了，不应该让整个应用被判定为不健康。这时可以使用自定义的 HealthAggregator 调整聚合策略，或者直接通过代码将非核心依赖的状态设置为 UNKNOWN。

Spring Boot 还支持将健康检查与 Kubernetes 的 liveness 和 readiness 探针结合。Actuator 内置了 /actuator/health/liveness 和 /actuator/health/readiness 两个子端点，需要在配置中启用：

management:
  endpoint:
    health:
      probes:
        enabled: true

启用后，liveness 探针只判断应用本身是否存活，不会因为依赖组件 DOWN 而重启容器；readiness 探针则会把自定义 HealthIndicator 的状态纳入考量，适合在滚动发布时控制入口流量。这种分离能避免因短暂数据库抖动导致 Pod 被反复重启。

安全方面，health 端点通常不需要登录，但 show-details 不应永久开启。如果使用了 Spring Security，可以通过配置限制只有特定角色才能查看详细信息。例如：

management:
  endpoint:
    health:
      show-details: when-authorized

再配合 Security 的授权规则，确保只有运维账号或监控系统能够访问完整健康信息。另外，健康检查的响应时间也值得关注，不要在 HealthIndicator 中做重查询或长超时调用，否则探针可能超时导致误判。一般来说，健康检查应当轻量、快速、只做探活不做业务逻辑。

最后，如果应用包含多个健康指示器，建议按模块命名，比如 database、redis、mq、downstream-service，这样在排查问题时能从 /actuator/health 的 components 中快速定位故障源。这种结构化输出也是对可观测性的一种补充，比干巴巴的 UP 或 DOWN 有价值得多。

Spring Boot健康检查Actuator修改时间：2026-09-23 13:25:48