Spring Boot Actuator 详细使用说明（完整代码与配置）
Spring Boot Actuator 详细使用说明（完整代码与配置）
1. 依赖引入
在 pom.xml 中添加 Actuator 依赖：
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
2. 核心配置与安全设置
2.1 允许暴露的端点配置（application.yml）
management:endpoints:web:exposure:include: "health,info,metrics,prometheus,env,loggers,shutdown" # 按需选择端点
2.2 安全配置（结合 Spring Security）
// SecurityConfig.java
@Configuration
@EnableWebSecurity
public class SecurityConfig {@Beanpublic SecurityFilterChain filterChain(HttpSecurity http) throws Exception {http.authorizeHttpRequests().requestMatchers("/actuator/health", "/actuator/info").permitAll() // 允许公开访问.requestMatchers("/actuator/**").hasRole("ACTUATOR") // 其他端点需角色验证.and().httpBasic() // 启用 Basic Auth.and().formLogin(); // 启用表单登录return http.build();}@Beanpublic UserDetailsService userDetailsService() {UserDetails user = User.withDefaultPasswordEncoder().username("admin").password("password").roles("ACTUATOR") // 赋予访问 Actuator 的角色.build();return new InMemoryUserDetailsManager(user);}
}
3. 常用端点详解与代码示例
3.1 /actuator/health - 健康检查
自定义健康指标：
// CustomHealthIndicator.java
@Component
public class CustomHealthIndicator implements HealthIndicator {@Overridepublic Health health() {try {// 模拟数据库连接检查boolean isConnected = checkDatabaseConnection();if (isConnected) {return Health.up().build();}} catch (Exception e) {return Health.down().withDetail("Error", e.getMessage()).build();}return Health.outOfService().build();}private boolean checkDatabaseConnection() {// 实际实现数据库连接检查逻辑return true;}
}
3.2 /actuator/info - 应用信息
配置元数据（application.yml）：
info:app:name: "MySpringApp"version: "1.0.0"build: "2023-10-01"
3.3 /actuator/metrics - 性能指标
自定义指标（计数器+计时器）：
// CustomMetrics.java
@Component
public class CustomMetrics {private final MeterRegistry registry;public CustomMetrics(MeterRegistry registry) {this.registry = registry;}@PostConstructpublic void init() {// 计数器：记录用户注册次数Counter userRegistrationCounter = registry.counter("user.registration.count");userRegistrationCounter.increment();// 计时器：记录某个方法的执行时间Timer methodTimer = registry.timer("my_method.timer");methodTimer.record(() -> {// 需要计时的代码逻辑});}
}
3.4 /actuator/loggers - 日志管理
动态调整日志级别（通过 Postman 或 curl）：
curl -X POST \http://localhost:8080/actuator/loggers/com.example \-H 'Content-Type: application/json' \-d '{"configuredLevel": "DEBUG"}'
3.5 /actuator/shutdown - 应用关闭
启用关闭端点（application.yml）：
management:endpoints:enabled-by-default: trueshutdown:enabled: true
3.6 /actuator/prometheus - Prometheus 集成
配置（application.yml）：
management:metrics:export:prometheus:enabled: true
4. 自定义端点示例
// CustomEndpoint.java
@Component
@Endpoint(id = "custom")
public class CustomEndpoint {@ReadOperationpublic Map<String, String> getCustomData() {return Map.of("message", "Hello from Actuator!");}@WriteOperationpublic void setCustomData(@Selector String key, String value) {// 处理写操作逻辑}
}
5. 完整配置与测试
5.1 完整 application.yml 示例
server:port: 8080spring:application:name: my-spring-appmanagement:endpoints:web:exposure:include: "health,info,metrics,prometheus,env,loggers,shutdown,custom"endpoint:health:show-details: ALWAYS # 显示详细健康检查信息shutdown:enabled: truemetrics:export:prometheus:enabled: true
5.2 测试端点
# 查看健康状态
curl http://localhost:8080/actuator/health# 获取自定义端点数据
curl http://localhost:8080/actuator/custom# 触发应用关闭（需认证）
curl -X POST -u admin:password http://localhost:8080/actuator/shutdown
6. 功能总结表格
| 端点 | 功能 | 配置关键项 | 安全要求 | 示例代码 |
|---|---|---|---|---|
/actuator/health | 应用健康状态检查 | management.endpoint.health.show-details=ALWAYS | 公开/受限 | CustomHealthIndicator.java |
/actuator/info | 应用元数据展示 | info.app.* 配置 | 公开 | application.yml |
/actuator/metrics | 性能指标监控（内存、CPU、HTTP请求等） | management.metrics.export.prometheus.enabled=true | 受限 | CustomMetrics.java |
/actuator/loggers | 动态调整日志级别 | - | 受限 | curl 命令示例 |
/actuator/shutdown | 优雅关闭应用 | management.endpoint.shutdown.enabled=true | 受限 | application.yml |
/actuator/prometheus | Prometheus 指标导出 | management.metrics.export.prometheus.enabled=true | 受限 | Prometheus 配置 |
/actuator/custom | 自定义端点（示例返回固定文本） | 自定义 @Endpoint 注解组件 | 受限 | CustomEndpoint.java |
7. 注意事项
- 安全性：生产环境必须配置 Spring Security，敏感端点（如
env）应设置权限。 - 性能影响：高频指标采集可能增加系统负载，可通过
management.metrics.use-registry=none禁用默认指标。 - 监控集成：结合 Prometheus + Grafana 可实现可视化监控，需部署 Prometheus 服务器并配置抓取任务。
通过以上配置和代码示例，可以快速集成 Actuator 的核心功能，并根据需求扩展自定义逻辑。