spring-boot-actuator 是 Spring Boot 提供的 应用监控与监控组件，通过暴露一系列 HTTP 端点（Endpoint），帮助开发者实时了解应用的运行状态、健康状况、配置信息、性能指标等，是微服务架构中实现应用可观测性的核心工具之一。

一、核心定位

在分布式系统中，需要对应用的运行状态进行实时监控（如是否存活、内存使用情况、接口调用量等），以便及时发现问题。spring-boot-actuator 的核心价值在于：

• 提供标准化的监控端点，无需手动开发监控接口；
• 支持与监控系统（如 Prometheus、Grafana、ELK）集成，实现指标收集与可视化；
• 提供健康检查能力，便于容器编排工具（如 Kubernetes）或服务注册中心（如 Nacos）判断应用是否可用。

二、核心功能

spring-boot-actuator 提供了丰富的端点（Endpoint），涵盖应用健康、配置、指标、日志等多个维度。常用端点如下：

端点路径	描述	默认是否暴露（HTTP）
/actuator/health	应用健康状态检查，可集成数据库、缓存等组件的健康检查。	是（仅 health 路径）
/actuator/info	应用自定义信息（如版本号、作者等），需手动配置。	是（仅 info 路径）
/actuator/metrics	应用运行指标（如 JVM 内存、GC 次数、HTTP 请求数等）。	否
/actuator/env	应用环境变量与配置属性（如 application.yml 中的配置、系统环境变量）。	否
/actuator/configprops	所有 @ConfigurationProperties 注解绑定的配置属性。	否
/actuator/loggers	查看和动态修改日志级别（如临时将 com.example 包日志级别改为 DEBUG）。	否
/actuator/httptrace	最近 HTTP 请求的追踪信息（默认记录 100 条，需配合 HttpTraceRepository）。	否
/actuator/shutdown	优雅关闭应用（需开启配置）。	否

三、基本使用

1. 引入依赖

在 Spring Boot 项目中添加 spring-boot-actuator 依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

2. 配置端点暴露

默认情况下，只有 /actuator/health 和 /actuator/info 端点通过 HTTP 暴露。如需暴露其他端点，需在 application.yml 中配置：

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,env  # 暴露的端点（* 表示所有端点）
        exclude: shutdown  # 排除不暴露的端点（若 include 为 * 时使用）
  endpoint:
    health:
      show-details: always  # 显示健康检查的详细信息（默认只显示状态）
    shutdown:
      enabled: true  # 开启优雅关闭端点（默认关闭）

3. 常用端点示例

（1）健康检查（/actuator/health）

默认返回应用的整体健康状态（UP 或 DOWN）：

{
  "status": "UP",
  "components": {
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 107374182400,
        "free": 53687091200,
        "threshold": 10485760
      }
    },
    "db": {  // 若集成数据库，会自动添加数据库健康检查
      "status": "UP",
      "details": {
        "database": "MySQL",
        "validationQuery": "SELECT 1"
      }
    }
  }
}

• 健康检查支持自动集成常见组件（如数据库、Redis、Elasticsearch 等），也可自定义健康检查逻辑（实现 HealthIndicator 接口）。

（2）自定义信息（/actuator/info）

通过配置 info 前缀的属性，自定义返回信息：

info:
  app:
    name: order-service
    version: 1.0.0
  author:
    name: "Alice"
    email: "alice@example.com"

访问 /actuator/info 返回：

{
  "app": {
    "name": "order-service",
    "version": "1.0.0"
  },
  "author": {
    "name": "Alice",
    "email": "alice@example.com"
  }
}

（3）指标监控（/actuator/metrics）

查看所有可用指标类型：

GET /actuator/metrics

返回示例：

{
  "names": [
    "jvm.memory.used",
    "jvm.gc.memory.promoted",
    "http.server.requests",
    "system.cpu.usage"
  ]
}

查看具体指标（如 JVM 内存使用）：

GET /actuator/metrics/jvm.memory.used

返回示例（包含堆内存、非堆内存的使用详情）：

{
  "name": "jvm.memory.used",
  "measurements": [{"value": 254423456, "statistic": "VALUE"}],
  "availableTags": [
    {"tag": "area", "values": ["heap", "non_heap"]},
    {"tag": "id", "values": ["Eden Space", "Survivor Space", "Metaspace"]}
  ]
}

四、扩展与集成

1. 自定义健康检查

实现 HealthIndicator 接口，添加自定义组件的健康检查逻辑：

@Component
public class CustomHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        // 模拟检查自定义服务（如第三方API是否可用）
        boolean isHealthy = checkExternalService();
        
        if (isHealthy) {
            return Health.up()
                    .withDetail("message", "外部服务正常")
                    .withDetail("time", LocalDateTime.now())
                    .build();
        } else {
            return Health.down()
                    .withDetail("message", "外部服务不可用")
                    .withDetail("error", "连接超时")
                    .build();
        }
    }

    private boolean checkExternalService() {
        // 实际检查逻辑（如发送HTTP请求）
        return true;
    }
}

访问 /actuator/health 会包含 custom 组件的健康状态。

2. 与监控系统集成

spring-boot-actuator 可与 Prometheus、Grafana 等工具集成，实现指标的持久化和可视化：

• 步骤1：引入 Prometheus 依赖，暴露 Prometheus 格式的指标：

  <dependency>
      <groupId>io.micrometer</groupId>
      <artifactId>micrometer-registry-prometheus</artifactId>
  </dependency>
  

• 步骤2：配置暴露 Prometheus 端点：

  management:
    endpoints:
      web:
        exposure:
          include: prometheus  # 暴露 /actuator/prometheus 端点
    metrics:
      export:
        prometheus:
          enabled: true
  

• 步骤3：Prometheus 抓取 /actuator/prometheus 端点的指标，Grafana 连接 Prometheus 展示可视化图表（如 JVM 内存趋势、HTTP 请求 QPS 等）。

五、安全控制

actuator 端点包含敏感信息（如 env 端点暴露配置），需通过 Spring Security 进行权限控制：

1. 引入 Spring Security 依赖：

   <dependency>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-security</artifactId>
   </dependency>
   

2. 配置安全规则（只允许认证用户访问 actuator 端点）：

   @Configuration
   public class SecurityConfig {
   
       @Bean
       public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
           http
               .authorizeHttpRequests(auth -> auth
                   .requestMatchers("/actuator/**").authenticated()  // actuator 端点需认证
                   .anyRequest().permitAll()  // 其他接口允许匿名访问
               )
               .httpBasic();  // 使用 HTTP 基本认证
           return http.build();
       }
   }
   

六、总结

spring-boot-actuator 是 Spring Boot 应用监控的核心组件，通过标准化的端点提供应用健康、指标、配置等信息，支持自定义扩展和第三方监控系统集成。在微服务架构中，它是实现“可观测性”的基础工具，帮助开发者实时掌握应用状态，快速定位问题，保障系统稳定运行。