Actuator 端点：Spring Boot 应用监控与管理利器

各位观众，欢迎来到今天的“码农脱口秀”！今天我们要聊聊 Spring Boot 家族里一位低调却实力非凡的成员——Actuator。 啥？Actuator？ 听起来像变形金刚里的某个小角色？ 错！它可是个能帮你监控和管理 Spring Boot 应用的超级英雄！

想象一下，你辛辛苦苦开发了一个 Spring Boot 应用，部署上线后，就开始提心吊胆，担心它会不会突然罢工，性能是不是出了问题，内存有没有泄漏。 别慌！有了 Actuator，你就像拥有了一个全天候的监控室，可以随时掌握应用的健康状况，还能远程控制应用的各种功能。

接下来，就让我们一起深入了解一下 Actuator 这个“监控利器”，看看它到底能帮我们做些什么。

Actuator 是什么？

简单来说，Actuator 是 Spring Boot 提供的一组预定义的 HTTP 端点，用于监控和管理 Spring Boot 应用。 通过这些端点，你可以获取应用的健康信息、度量指标、配置信息、日志信息等，还可以执行一些管理操作，比如刷新配置、关闭应用等。

你可以把 Actuator 想象成你家里的智能家居控制面板，通过它你可以查看各个房间的温度、湿度，控制灯光、窗帘，甚至还能远程启动咖啡机。

引入 Actuator

要使用 Actuator，只需要在你的 Spring Boot 项目中添加 spring-boot-starter-actuator 依赖即可。

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

添加依赖后，Spring Boot 会自动配置 Actuator，并暴露一些默认的端点。你可以通过访问这些端点来获取应用的信息。

常用端点一览

Actuator 提供了很多非常有用的端点，下面列举一些常用的端点：

端点	描述
/actuator/health	显示应用的健康状况。
/actuator/info	显示应用的自定义信息，比如版本号、构建时间等。
/actuator/metrics	显示应用的各种度量指标，比如内存使用情况、CPU 使用率、请求响应时间等。
/actuator/loggers	查看和修改应用的日志级别。
/actuator/env	显示应用的配置信息，包括环境变量、系统属性、配置文件等。
/actuator/beans	显示应用中所有的 Spring Bean。
/actuator/mappings	显示应用中所有的请求映射。
/actuator/shutdown	关闭应用（默认禁用，需要手动开启）。
/actuator/threaddump	显示应用的线程转储信息。
/actuator/heapdump	生成应用的堆转储文件。

健康检查：/actuator/health

/actuator/health 端点用于显示应用的健康状况。 它会检查应用依赖的各种组件（比如数据库、消息队列）是否正常工作，并返回一个总体健康状态。

访问 /actuator/health 端点，你会得到类似下面的 JSON 响应：

{
  "status": "UP"
}

status 字段表示应用的健康状态，UP 表示应用正常运行。 如果应用依赖的某个组件出现问题，status 字段可能会变成 DOWN，同时还会提供更详细的错误信息。

你还可以自定义健康检查逻辑，通过实现 HealthIndicator 接口，你可以添加自己的健康检查项。

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

@Component
public class MyHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        int errorCode = check(); // 执行自定义检查逻辑
        if (errorCode != 0) {
            return Health.down().withDetail("Error Code", errorCode).build();
        }
        return Health.up().build();
    }

    private int check() {
        // 在这里编写你的健康检查逻辑
        // 比如检查某个文件是否存在，或者检查某个服务的可用性
        // 如果一切正常，返回 0，否则返回一个错误码
        return 0;
    }
}

上面的代码定义了一个名为 MyHealthIndicator 的健康检查器，它实现了 HealthIndicator 接口。 health() 方法是健康检查的入口，它会调用 check() 方法执行自定义的检查逻辑，并根据检查结果返回一个 Health 对象。

应用信息：/actuator/info

/actuator/info 端点用于显示应用的自定义信息，比如版本号、构建时间等。 你可以在 application.properties 或 application.yml 文件中配置这些信息。

info.app.name=My Awesome App
info.app.version=1.0.0
info.app.description=A simple Spring Boot application

配置完成后，访问 /actuator/info 端点，你会得到类似下面的 JSON 响应：

{
  "app": {
    "name": "My Awesome App",
    "version": "1.0.0",
    "description": "A simple Spring Boot application"
  }
}

你还可以通过实现 InfoContributor 接口，以编程方式添加应用信息。

import org.springframework.boot.actuate.info.Info;
import org.springframework.boot.actuate.info.InfoContributor;
import org.springframework.stereotype.Component;

import java.util.HashMap;
import java.util.Map;

@Component
public class MyInfoContributor implements InfoContributor {

    @Override
    public void contribute(Info.Builder builder) {
        Map<String, Object> details = new HashMap<>();
        details.put("developers", new String[]{"Alice", "Bob"});
        details.put("license", "Apache 2.0");
        builder.withDetail("my-app", details);
    }
}

上面的代码定义了一个名为 MyInfoContributor 的信息贡献器，它实现了 InfoContributor 接口。 contribute() 方法用于添加应用信息，它接收一个 Info.Builder 对象，你可以使用它来添加各种信息。

度量指标：/actuator/metrics

/actuator/metrics 端点用于显示应用的各种度量指标，比如内存使用情况、CPU 使用率、请求响应时间等。 Actuator 使用 Micrometer 库来收集和暴露这些指标。

访问 /actuator/metrics 端点，你会得到一个包含所有可用指标名称的列表。 你可以通过指定指标名称来获取该指标的详细信息。

例如，要获取 jvm.memory.used 指标的详细信息，可以访问 /actuator/metrics/jvm.memory.used 端点。 你会得到类似下面的 JSON 响应：

{
  "name": "jvm.memory.used",
  "description": "The amount of used memory",
  "baseUnit": "bytes",
  "measurements": [
    {
      "statistic": "VALUE",
      "value": 2.147483648E8
    }
  ],
  "availableTags": []
}

name 字段表示指标的名称，description 字段表示指标的描述，baseUnit 字段表示指标的单位，measurements 字段包含指标的测量值。

你还可以自定义度量指标，通过使用 @Timed 注解或 MeterRegistry 对象，你可以收集自己的业务指标。

import io.micrometer.core.annotation.Timed;
import org.springframework.stereotype.Service;

@Service
public class MyService {

    @Timed("my.service.execution.time")
    public String doSomething() {
        // 模拟耗时操作
        try {
            Thread.sleep(100);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
        return "Done!";
    }
}

上面的代码使用 @Timed 注解来标记 doSomething() 方法，Micrometer 会自动收集该方法的执行时间，并将其暴露为 my.service.execution.time 指标。

日志管理：/actuator/loggers

/actuator/loggers 端点用于查看和修改应用的日志级别。 你可以通过访问该端点来获取当前应用的日志配置，还可以动态地修改某个 logger 的日志级别。

访问 /actuator/loggers 端点，你会得到一个包含所有 logger 名称和日志级别的列表。 你可以通过指定 logger 名称来获取该 logger 的详细信息。

例如，要获取 com.example.myapp logger 的详细信息，可以访问 /actuator/loggers/com.example.myapp 端点。 你会得到类似下面的 JSON 响应：

{
  "configuredLevel": null,
  "effectiveLevel": "INFO"
}

configuredLevel 字段表示该 logger 配置的日志级别，effectiveLevel 字段表示该 logger 实际生效的日志级别。 如果 configuredLevel 为 null，表示该 logger 没有配置日志级别，它会继承父 logger 的日志级别。

你可以通过发送 POST 请求到 /actuator/loggers/{name} 端点来修改 logger 的日志级别。 请求体应该包含一个 configuredLevel 字段，表示要设置的日志级别。

{
  "configuredLevel": "DEBUG"
}

环境信息：/actuator/env

/actuator/env 端点用于显示应用的配置信息，包括环境变量、系统属性、配置文件等。 通过访问该端点，你可以了解应用的运行环境，还可以查看配置文件的内容。

访问 /actuator/env 端点，你会得到一个包含所有配置源和配置属性的列表。 配置源按照优先级排序，优先级高的配置源会覆盖优先级低的配置源。

你可以通过指定配置属性的名称来获取该属性的详细信息。

例如，要获取 spring.datasource.url 属性的详细信息，可以访问 /actuator/env/spring.datasource.url 端点。

注意： 默认情况下，敏感信息（比如数据库密码）会被屏蔽。 你可以通过配置 management.endpoint.env.keys-to-sanitize 属性来指定要屏蔽的配置属性。

Bean 信息：/actuator/beans

/actuator/beans 端点用于显示应用中所有的 Spring Bean。 通过访问该端点，你可以了解应用中所有的 Bean 定义，以及它们的依赖关系。

访问 /actuator/beans 端点，你会得到一个包含所有 Bean 定义的列表。 每个 Bean 定义都包含 Bean 的名称、类型、依赖关系等信息。

请求映射：/actuator/mappings

/actuator/mappings 端点用于显示应用中所有的请求映射。 通过访问该端点，你可以了解应用中所有的 URL 路由，以及它们对应的处理方法。

访问 /actuator/mappings 端点，你会得到一个包含所有请求映射的列表。 每个请求映射都包含 URL 模式、HTTP 方法、处理方法等信息。

关闭应用：/actuator/shutdown

/actuator/shutdown 端点用于关闭应用。 默认情况下，该端点是禁用的，需要手动开启。

要开启 /actuator/shutdown 端点，需要在 application.properties 或 application.yml 文件中配置 management.endpoint.shutdown.enabled=true。

警告： 开启 /actuator/shutdown 端点后，任何人都可以通过访问该端点来关闭应用。 因此，在生产环境中应该谨慎使用该端点，最好是添加安全认证。

线程转储：/actuator/threaddump

/actuator/threaddump 端点用于显示应用的线程转储信息。 线程转储信息可以帮助你诊断应用的性能问题，比如死锁、线程阻塞等。

访问 /actuator/threaddump 端点，你会得到一个包含所有线程信息的文本。 每个线程信息都包含线程的名称、ID、状态、堆栈信息等。

堆转储：/actuator/heapdump

/actuator/heapdump 端点用于生成应用的堆转储文件。 堆转储文件可以帮助你诊断应用的内存问题，比如内存泄漏、内存溢出等。

访问 /actuator/heapdump 端点，你会得到一个堆转储文件，你可以使用专业的工具（比如 MAT）来分析该文件。

注意： 生成堆转储文件会消耗大量的系统资源，因此在生产环境中应该谨慎使用该端点。

安全性

默认情况下，Actuator 端点是公开的，任何人都可以访问。 在生产环境中，为了保证应用的安全性，应该对 Actuator 端点进行安全认证。

你可以使用 Spring Security 来保护 Actuator 端点。 首先，需要在你的项目中添加 spring-boot-starter-security 依赖。

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

然后，你需要配置 Spring Security，指定哪些用户可以访问 Actuator 端点。

import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;

@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
                .antMatchers("/actuator/**").hasRole("ACTUATOR") // 只有具有 ACTUATOR 角色的用户才能访问 Actuator 端点
                .anyRequest().permitAll()
                .and()
                .httpBasic();
    }
}

上面的代码配置了 Spring Security，只有具有 ACTUATOR 角色的用户才能访问 Actuator 端点。

你还需要配置一个用户，并为其分配 ACTUATOR 角色。 你可以在 application.properties 或 application.yml 文件中配置用户。

spring.security.user.name=admin
spring.security.user.password=password
spring.security.user.roles=ACTUATOR

配置完成后，访问 Actuator 端点时，需要提供用户名和密码。

自定义端点

除了 Spring Boot 提供的默认端点之外，你还可以自定义端点，以暴露自己的业务信息或执行自己的管理操作。

要自定义端点，你需要创建一个类，并使用 @Endpoint 注解标记它。 然后，你需要定义一个或多个方法，并使用 @ReadOperation、@WriteOperation 或 @DeleteOperation 注解标记它们，分别表示读操作、写操作和删除操作。

import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
import org.springframework.stereotype.Component;

import java.util.HashMap;
import java.util.Map;

@Component
@Endpoint(id = "my-endpoint")
public class MyEndpoint {

    @ReadOperation
    public Map<String, String> hello() {
        Map<String, String> result = new HashMap<>();
        result.put("message", "Hello from my endpoint!");
        return result;
    }
}

上面的代码定义了一个名为 MyEndpoint 的自定义端点，它包含一个名为 hello() 的读操作。 你可以通过访问 /actuator/my-endpoint 端点来执行该操作。

小结

Actuator 是 Spring Boot 提供的一组强大的工具，可以帮助你监控和管理 Spring Boot 应用。 通过使用 Actuator，你可以了解应用的健康状况、度量指标、配置信息、日志信息等，还可以执行一些管理操作。

但是，在使用 Actuator 时，需要注意安全性，避免敏感信息泄露。 另外，应该谨慎使用一些具有破坏性的端点，比如 /actuator/shutdown。

希望今天的“码农脱口秀”能帮助你更好地了解 Actuator。 记住，Actuator 是你的得力助手，它可以让你更好地掌控你的 Spring Boot 应用。

最后，送给大家一句至理名言：“代码虐我千百遍，我待代码如初恋！” 感谢大家收看，我们下期再见！