Spring Boot Actuator EndPoints（官网文档解读)

Actuator EndPoints 定义

        Actuator EndPoints 是 Spring Boot Actuator 提供的一组 RESTful 接口。这些接口可以让你深入了解应用程序的内部状态，比如健康状况、运行时指标、环境变量等。通过这些端点，运维人员和开发人员能够更好地监控应用运行，快速定位和解决问题，同时也方便进行性能调优。

EndPoints 分类

       EndPoints 的访问端点可分为两类：一类是 Web 端点，另一类是 JMX 端点。用户可根据自身使用习惯选择相应的端点类型。

EndPoints 访问

• Spring Boot 的 actuator 包含一系列内置端点，例如 /health。我们还可以通过代码编写和配置来自定义添加端点。

• actuator 端点的 Web 访问格式为：项目访问地址 + /actuator + /EndPoints 端点。

• 示例：以本地测试项目为例，若项目端口号为 8091，要访问 health 端点，请求地址为：

• http://localhost:8091/actuator/health

• 

引入依赖

        若使用 Maven 构建项目，在pom.xml文件中添加如下依赖：

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

EndPoints 全部端点列表

• 默认开启的端点：引入 spring-boot-starter-actuator 依赖后，默认会开启 /health 端点，其他端点需进一步配置才能启用。

• 查询已开启的端点列表：可通过访问 /actuator 来查询项目中已开启的全部端点列表，示例： http://localhost:8091/actuator

  • 

EndPoints 配置

修改默认的端点路径

        要在Spring Boot应用程序中将默认的Actuator端点路径/actuator更改为自定义路径如/

management，我们可以这样配置：

management:
  endpoints:
    web:
      base-path: /management

关闭端点发现页面

        我们也可以直接将端点列表发现页面关闭，可以这样配置：

management:
  endpoints:
    web:
      discovery:
        enabled: false

        这个配置只会影响端点发现页面，对端点的正常使用没有影响。

开启所有Web端点

# 开启所有默认Web端点
management:
  endpoints:
    web:
      exposure:
        include:  "*"

开启某些Web端点

# 开启 info 和 env 端点
management:
  endpoints:
    web:
      exposure:
        include:  info,env

关闭某些Web端点

# 开启全部端点，关闭info，env 端点
management:
  endpoints:
    web:
      exposure:
        include: "*"
        exclude:  info,env

开启所有JMX端点

# 开启所有默认JMX端点

management:
  endpoints:
  jmx:
    exposure:
      include: "*"

关闭所有Web端点

# 开启所有默认Web端点
management:
  endpoints:
    web:
      exposure:
        exclude: "*"

单独配置某个端点设置

        我们可以使用 endpoint: 端点名的方式配置该端点的个性化配置。下面的示例即让health 端点显示更详细的信息。

management:
  endpoint:
    health:
      show-details: always

端点缓存时间配置

        端点自动缓存对不采用任何参数的读取操作的响应。要配置端点缓存响应的时间量，请使用其cache.time-To-live属性。下面的示例将bean端点缓存的生存时间设置为10秒：

management:
  endpoint:
    beans:
      cache:
        time-to-live: "10s"

敏感值处理

  /env、/configprops和/quartz端点返回的信息可能很敏感，因此默认情况下值总是被替换成***。我们可以通过修改端点的show-values配置，来改变值的显示。

management:
  endpoint:
    env:
      show-values: always

• 未配置前的展示：

• 配置show-values 为always 的展示：

• show-values 可配置属性：

跨域支持

EndPoints 端点介绍

health 端点

• 展示更详细的信息：下面的示例即让health 端点显示更详细的信息。

management:
  endpoint:
    health:
      show-details: always

自动配置的健康指标

        在适当的情况下，Spring Boot 会自动配置HealthIndicator下表中列出的 bean。您还可以通过配置启用或禁用选定的指标management.health.key.enabled，key下表列出了这些指标：

        接下来，我将用db 端点举例，来说明/health/{*path}的使用。如果想要/health包含/db 端点，我们需要引入数据源配置和java 数据库操作引擎。我的项目以mysql和jdbc 为例，需要在maven 中引入如下依赖：

<!-- mysql 的驱动 -->
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <scope>runtime</scope>
        </dependency>
        <!-- 添加 spring-boot-starter-jdbc 依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-jdbc</artifactId>
        </dependency>

        而后重新启动我们的项目，我们就可以获得db端点的健康检查输出了。

自动配置的响应式健康指标

健康指标启用/禁用

        我们可以使用health.defaults.enabled 属性来配置健康检查的端点细节是否启用。并可以配置/health端点的详细的key是否启用和禁用，如下示例关闭了/health 端点的细节展示，但放开了/db端点的细节展示。

management:
  health:
    defaults:
      enabled: false
    db:
      enabled: true

编写一个自定义的健康指标

package person.wend.springbootlearnexample2.health;

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

@Component
public class TestHealthIndicator 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() {
		// perform some specific health check
		return 899;
	}

}

        该示例增加了一个 /health/test 端点的健康指标。

健康指标 status 状态定义

• 下表显示了内置状态的默认状态映射：

• 自定义status 状态码映射

# 定义状态码映射

http-mapping:

  up: 200
  down: 503
  out_of_serivce: 503
  unknown: 200

• 配置状态码顺序

# 定义状态码映射
http-mapping:
  up: 200 
  down: 503 
  out_of_serivce: 503 
  unknown: 200
# 定义状态顺序
order:down, out_of_service, up, unknown

健康指标组定义

        如下示例，定义了一个/custom 组端点，包含了健康指标的 db 端点。

management:
  endpoint:
    health:
      group:
        custom:
          include: "db"

如下示例，定义了一个/custom 组端点，不包含健康指标的 db 端点。

management:
  endpoint:
    health:
      group:
        custom:
          exclude: "db"

info 端点

自动配置的 InfoContributors

• Spring 会自动配置以下InfoContributor Bean：

• 在初始化项目的时候，/info 端点展示的将是一个空json串。在这里，我将以/build 端点、/git 端点和/info端点为示例，讲述如何正确配置/info端点的子端点。

• build 端点

• 生成build端点的第一种方式是在resources的META-INF 资源文件夹下配置buid-info.properties。

• 但我们一般采用使用maven 插件自动生成的方式：

            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <executions>
                    <execution>
                        <goals>
                            <goal>build-info</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

• git端点

• git.properties文件一般配置在项目的根目录，我们可以手写生成该文件，但我们一般使用maven 插件自动生成的方式生成该文件。

•              <plugin>
                  <groupId>io.github.git-commit-id</groupId>
                  <artifactId>git-commit-id-maven-plugin</artifactId>
                  <version>5.0.0</version>
                  <executions>
                      <execution>
                          <id>get-the-git-infos</id>
                          <goals>
                              <goal>revision</goal>
                          </goals>
                      </execution>
                  </executions>
                  <configuration>
                      <dotGitDirectory>${project.basedir}/.git</dotGitDirectory>
                      <generateGitPropertiesFile>true</generateGitPropertiesFile>
                      <generateGitPropertiesFilename>target/classes/git.properties</generateGitPropertiesFilename>
                  </configuration>
              </plugin>

• 要想展示git 配置的更详细内容，可以做如下配置：

• management:
    info:
      git:
        mode: "full"

• git 端点展示效果如下图所示：

• 

• env端点

• env 端点展示配置中以 info开头的任何属性。我们可以在application.yml 中做如下配置进行测试。

info:
    app:
        name: ReD
        description: ReD
        version: 1.0.0

• 在application.yml 中配置env.enabled =true,则最终会在页面中展示该配置。
• 

启用/禁用

# 开启所有默认Web端点
management:
  info:
    defaults:
      enabled: true
    env:
      enabled: true
    java:
      enabled: true
    build:
      enabled: false

• 可以看到我们开启了/env，/java端点，关闭了/build 端点，最后/info端点的显示结果是这样的：

自定义/info子端点

• 我们可以采用编码的方式，继承 InfoContributor，以实现定义自己的/info 子端点，示例代码如下：

package person.wend.springbootlearnexample2.health;

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

import java.util.Collections;

@Component
public class TestInfoIndicator implements InfoContributor {
    @Override
    public void contribute(Info.Builder builder) {
        builder.withDetail("example", Collections.singletonMap("key", "value"));
    }
}

• 编写完成后，重启程序。最终会在/info 端点展示自行定义的内容

• 

shutdown 端点

• shutdown 端点配置

management:
  endpoint:
    shutdown:
        enabled: true # 开启
        access: unrestricted #不受限制的访问shutdown端点

• 使用示例
  • shutdown 端点是Post 请求，所以我使用了PostMan 模拟一个/actuator/shutdown 请求。请求后，运行的项目被正常关闭了。

prometheus端点

        如果我们的项目中集成了prometheus，则可以通过如下配置开启/prometheus 端点。

management:
  endpoints:
    web:
      prometheus:
        enabled: true

自定义EndPoints 端点

端点定义注解

@Endpoint

        这是一个通用的端点定义注解，用于创建一个自定义端点，该端点可以同时支持 Web 和 JMX 两种访问方式。它允许开发者定义自己的管理端点，通过这些端点可以暴露应用程序的一些内部状态或执行特定的操作。

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

@Component
@Endpoint(id = "custom")
public class CustomEndpoint {

    @ReadOperation
    public String customInfo() {
        return "This is custom endpoint information.";
    }
}

@WebEndpoint

        专门用于定义仅支持 Web 访问的自定义端点。如果你的端点只需要通过 HTTP 请求进行访问，使用该注解可以避免不必要的 JMX 相关配置。

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

@Component
@WebEndpoint(id = "webCustom")
public class WebCustomEndpoint {

    @ReadOperation
    public String webCustomInfo() {
        return "This is web custom endpoint information.";
    }
}

@JmxEndpoint

        用于定义仅支持 JMX（Java Management Extensions）访问的自定义端点。如果你的应用程序需要通过 JMX 工具（如 VisualVM、JConsole 等）来管理和监控端点，就可以使用该注解。

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

@Component
@JmxEndpoint(id = "jmxCustom")
public class JmxCustomEndpoint {

    @ReadOperation
    public String jmxCustomInfo() {
        return "This is JMX custom endpoint information.";
    }
}

@EndpointWebExtension

        用于为现有的端点（可以是使用 @Endpoint 定义的端点）添加 Web 扩展功能。当你想要为一个已经存在的端点添加一些特定的 Web 访问逻辑时，可以使用这个注解。

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

@Endpoint(id = "original")
class OriginalEndpoint {
    @ReadOperation
    public String originalInfo() {
        return "Original endpoint information.";
    }
}

@Component
@EndpointWebExtension(endpoint = OriginalEndpoint.class)
public class OriginalEndpointWebExtension {

    @ReadOperation
    public String extendedInfo() {
        return "Extended information for original endpoint.";
    }
}

@EndpointJmxExtension

        与 @EndpointWebExtension 类似，只不过它是为现有的端点添加 JMX 扩展功能，允许你为已有的端点增加特定的 JMX 访问逻辑。

操作注解

@ReadOperation

        用于标记端点中的读操作方法。当客户端通过 HTTP GET 请求或 JMX 查询访问端点时，会调用被该注解标记的方法。通常用于获取端点的信息或状态。

@WriteOperation

        用于标记端点中的写操作方法。当客户端通过 HTTP POST 请求访问端点时，会调用被该注解标记的方法。通常用于修改端点的某些配置或状态。

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

@Component
@Endpoint(id = "config")
public class ConfigEndpoint {

    private String configValue = "default";

    @WriteOperation
    public void updateConfig(String newValue) {
        this.configValue = newValue;
    }
}

@DeleteOperation

        用于标记端点中的删除操作方法。当客户端通过 HTTP DELETE 请求访问端点时，会调用被该注解标记的方法。通常用于删除端点的某些资源或配置。

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

@Component
@Endpoint(id = "resource")
public class ResourceEndpoint {

    @DeleteOperation
    public void deleteResource() {
        // 执行删除资源的操作
    }
}

其他注解

@EndpointConverter

        在自定义端点的开发过程中，端点方法可能会接收各种类型的参数。然而客户端传递过来的数据往往是字符串形式，此时就需要将这些字符串数据转换为端点方法所期望的具体类型。@EndpointConverter 注解的作用就是注册自定义的转换器，以此实现从字符串到特定类型的转换，保证端点方法能够正确接收和处理参数。

        当你自定义端点方法需要接收非标准类型（例如自定义的枚举类型、复杂对象等）的参数，而 Spring Boot 又没有提供默认的转换器时，就可以使用 @EndpointConverter 注解来注册自定义的转换器。

@Selector

   @Selector 注解起到的关键作用是让端点方法能接收动态路径变量，以此实现对特定资源的精准访问与操作。在开发自定义端点时，有时候需要根据不同的资源标识来执行特定操作。@Selector 注解能够将 URL 中的动态部分映射到端点方法的参数上，使得端点可以处理针对特定资源的请求。

• 使用场景

  • 资源查询：根据特定资源的 ID 查询该资源的详细信息。

  • 资源修改：根据资源 ID 修改特定资源的属性。

  • 资源删除：根据资源 ID 删除特定资源。

• 代码示例：

• 定义自定义端点

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 = "custom-resources")
public class CustomResourcesEndpoint {

    private final Map<String, String> resources = new HashMap<>();

    public CustomResourcesEndpoint() {
        resources.put("resource1", "Value for resource 1");
        resources.put("resource2", "Value for resource 2");
    }

    // 使用 @Selector 注解接收动态路径变量
    @ReadOperation
    public String getResource(@Selector String resourceId) {
        return resources.getOrDefault(resourceId, "Resource not found");
    }
}

• 访问端点

        假设应用运行在 http://localhost:8080，可以通过以下 URL 访问特定资源：

• http://localhost:8080/actuator/custom-resources/resource1：

  • 返回 "Value for resource 1"

• http://localhost:8080/actuator/custom-resources/resource2：

  • 返回 "Value for resource 2"

• http://localhost:8080/actuator/custom-resources/non-existent：

  • 返回 "Resource not found"

Web 端点响应状态