5.2 Endpoints

执行器端点允许您监视应用程序并与其交互。SpringBoot包含许多内置端点，并允许您添加自己的端点。例如，health端点提供了基本的应用程序健康信息。

可以启用或禁用每个端点。 它控制是否创建端点并且其bean存在于应用程序上下文中。 要进行远程访问，还必须通过JMX或HTTP公开端点。 大多数应用程序选择HTTP，其中端点的ID以及/actuator的前缀映射到URL。 例如，默认情况下，运行状况端点映射到/actuator/health。

有以下与技术无关的端点：

如果您的应用程序是Web应用程序（Spring MVC，Spring WebFlux或Jersey），则可以使用以下附加端点：

5.2.1 启用Endpoints

默认情况下，启用除关闭之外的所有端点。 要配置端点的启用，请使用其management.endpoint..enabled属性。 以下示例启用关闭端点：

management.endpoint.shutdown.enabled=true

如果您希望端点启用是选择加入而不是选择退出，请将management.endpoints.enabled-by-default属性设置为false，并使用启用了各个端点的属性重新加入。以下示例启用info端点并禁用所有其他端点：

management.endpoints.enabled-by-default=false
management.endpoint.info.enabled=true

已完全从应用程序上下文中删除已禁用的端点。 如果只想更改端点所暴露的技术，请改用include和exclude属性。

5.2.2 暴露Endpoints

由于端点可能包含敏感信息，因此应仔细考虑何时公开它们。 下表显示了内置端点的默认暴露规则：

要更改公开的端点，请使用以下特定于技术的包含和排除属性：

include属性列出了公开的端点的ID。 exclude属性列出了不应公开的端点的ID。 exclude属性优先于include属性。 可以使用端点ID列表配置include和exclude属性。

例如，要停止通过JMX公开所有端点并仅显示运行状况和信息端点，请使用以下属性：

management.endpoints.jmx.exposure.include=health,info

*可用于选择所有端点。 例如，要通过HTTP公开除env和beans端点之外的所有内容，请使用以下属性：

management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=env,beans

*在YAML中具有特殊含义，因此如果要包含（或排除）所有端点，请务必添加引号，如以下示例所示：

management: endpoints: web: exposure: include: "*"

如果您的应用是公开的，我们强烈建议您也保护您的端点。

如果要在公开端点时实现自己的策略，可以注册EndpointFilter bean。

5.2.3 保护HTTP Endpoints

您应该像使用任何其他敏感URL一样注意保护HTTP端点。 如果存在Spring Security，则默认使用Spring Security的内容协商策略来保护端点。 例如，如果您希望为HTTP端点配置自定义安全性，只允许具有特定角色的用户访问它们，Spring Boot提供了一些方便的RequestMatcher对象，可以与Spring Security结合使用。

典型的Spring Security配置可能类似于以下示例：

@Configuration
public class ActuatorSecurity extends WebSecurityConfigurerAdapter {

	@Override
	protected void configure(HttpSecurity http) throws Exception {
		http.requestMatcher(EndpointRequest.toAnyEndpoint()).authorizeRequests()
				.anyRequest().hasRole("ENDPOINT_ADMIN")
				.and()
			.httpBasic();
	}

}

上面的示例使用EndpointRequest.toAnyEndpoint()将请求与任何端点进行匹配，然后确保所有端点都具有ENDPOINT_ADMIN角色。 EndpointRequest上还提供了其他几种匹配器方法。 有关详细信息，请参阅API文档（HTML或PDF）。

如果在防火墙后面部署应用程序，您可能希望无需身份验证即可访问所有执行器端点。 您可以通过更改management.endpoints.web.exposure.include属性来执行此操作，如下所示：

management.endpoints.web.exposure.include=*

此外，如果存在Spring Security，则需要添加自定义安全配置，以允许对端点进行未经身份验证的访问，如以下示例所示：

@Configuration
public class ActuatorSecurity extends WebSecurityConfigurerAdapter {

	@Override
	protected void configure(HttpSecurity http) throws Exception {
		http.requestMatcher(EndpointRequest.toAnyEndpoint()).authorizeRequests()
			.anyRequest().permitAll();
	}

}

5.2.4 配置Endpoints

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

management.endpoint.beans.cache.time-to-live=10s

前缀management.endpoint.用于唯一标识正在配置的端点。

在进行经过身份验证的HTTP请求时，Principal被视为端点的输入，因此不会缓存响应。

5.2.5 用于Actuator Web Endpoints的Hypermedia

添加了“门户页面”，其中包含指向所有端点的链接。 默认情况下，“门户页面”在/actuator上。

配置自定义管理上下文路径时，“门户页面”会自动从/actuator移动到管理上下文的根目录。 例如，如果管理上下文路径是/management，则可以从/ management获取门户页面。 当管理上下文路径设置为/时，将禁用门户页面以防止与其他映射冲突的可能性。

5.2.6 CORS支持

跨源资源共享（CORS）是一种W3C规范，允许您以灵活的方式指定授权的跨域请求类型。 如果您使用Spring MVC或Spring WebFlux，则可以配置Actuator的Web端点以支持此类方案。

默认情况下禁用CORS支持，仅在设置了management.endpoints.web.cors.allowed-origins属性后才启用CORS支持。 以下配置允许来自example.com域的GET和POST调用：

management.endpoints.web.cors.allowed-origins=http://example.com
management.endpoints.web.cors.allowed-methods=GET,POST

有关选项的完整列表，请参阅CorsEndpointProperties。

5.2.7 实现自定义Endpoints

如果添加使用@Endpoint注释的@Bean，则使用@ReadOperation，@WritOperation或@DeleteOperation注释的任何方法都将通过JMX自动公开，并且在Web应用程序中也通过HTTP公开。 可以使用Jersey，Spring MVC或Spring WebFlux通过HTTP公开端点。

您还可以使用@JmxEndpoint或@WebEndpoint编写特定于技术的端点。 这些端点仅限于各自的技术。 例如，@WebEndpoint仅通过HTTP而不是通过JMX公开。

您可以使用@EndpointWebExtension和@EndpointJmxExtension编写特定于技术的扩展。 通过这些注释，您可以提供特定于技术的操作来扩充现有端点。

最后，如果您需要访问特定于Web框架的功能，则可以实现Servlet或Spring @Controller和@RestController端点，但代价是它们无法通过JMX或使用其他Web框架。

5.2.7.1 接收输入

端点上的操作通过其参数接收输入。 通过Web公开时，这些参数的值取自URL的查询参数和JSON请求体。 通过JMX公开时，参数将映射到MBean操作的参数。 默认情况下需要参数。 可以使用@ org.springframework.lang.Nullable对它们进行注释，使它们成为可选项。

JSON请求正文中的每个根属性都可以映射到端点的参数。 考虑以下JSON请求正文：

{
	"name": "test",
	"counter": 42
}

这可用于调用带有String name和int counter参数的写操作。

由于端点与技术无关，因此只能在方法签名中指定简单类型。 特别是不支持使用定义名称和计数器属性的自定义类型声明单个参数。

要允许将输入映射到操作方法的参数，应使用-parameters编译实现端点的Java代码，并且应使用-java-parameters编译实现端点的Kotlin代码。 如果您使用的是Spring Boot的Gradle插件，或者您使用的是Maven和spring-boot-starter-parent，则会自动执行此操作。

1）输入类型转换

如有必要，传递给端点操作方法的参数将自动转换为所需类型。 在调用操作方法之前，使用ApplicationConversionService实例将通过JMX或HTTP请求接收的输入转换为所需类型。

5.2.7.2 自定义Web Endpoints

@Endpoint，@WebEndpoint或@EndpointWebExtension上的操作将使用Jersey，Spring MVC或Spring WebFlux通过HTTP自动公开。

1）Web Endpoint请求谓词

为Web暴露的端点上的每个操作自动生成请求谓词。

2）路径

谓词的路径由端点的ID和Web暴露的端点的基本路径确定。 默认基本路径是/actuator。 例如，具有ID会话的端点将使用/actuator/sessions作为其在谓词中的路径。

通过使用@Selector注释操作方法的一个或多个参数，可以进一步定制路径。 这样的参数作为路径变量添加到路径谓词中。 调用端点操作时，变量的值将传递给操作方法。

3）HTTP方法

谓词的HTTP方法由操作类型决定，如下表所示：

3）Consumes

对于使用请求主体的@WriteOperation(HTTP POST)，谓词的consumes子句是application/vnd.spring-boot.actuator.v2 + json，application/json。 对于所有其他操作，consumemes子句为空。

4）Produces

谓词的produce子句可以由@DeleteOperation，@ReadOperation和@WriteOperation注释的produce属性确定。 该属性是可选的。 如果未使用，则自动确定produce子句。

如果操作方法返回void或Void，则produce子句为空。 如果操作方法返回org.springframework.core.io.Resource，则produce子句为application/octet-stream。 对于所有其他操作，produce子句是application/vnd.spring-boot.actuator.v2 + json，application/json。

5）Web Endpoint响应状态

端点操作的默认响应状态取决于操作类型（读取，写入或删除）以及操作返回的内容（如果有）。

@ReadOperation返回一个值，响应状态为200（OK）。 如果它未返回值，则响应状态将为404（未找到）。

如果@WriteOperation或@DeleteOperation返回值，则响应状态将为200（OK）。 如果它没有返回值，则响应状态将为204（无内容）。

如果在没有必需参数的情况下调用操作，或者使用无法转换为所需类型的参数，则不会调用操作方法，并且响应状态将为400（错误请求）。

6）Web Endpoint范围请求

HTTP范围请求可用于请求部分HTTP资源。 使用Spring MVC或Spring Web Flux时，返回org.springframework.core.io.Resource的操作会自动支持范围请求。

使用Jersey时不支持范围请求。

7）Web Endpoint安全

Web端点或特定于Web的端点扩展上的操作可以接收当前的java.security.Principal或org.springframework.boot.actuate.endpoint.SecurityContext作为方法参数。 前者通常与@Nullable结合使用，为经过身份验证和未经身份验证的用户提供不同的行为。 后者通常用于使用其isUserInRole(String)方法执行授权检查。

5.2.7.3 Servlet endpoints

通过实现一个带有@ServletEndpoint注释的类，Servlet可以作为端点公开，该类也实现了Supplier。 Servlet端点提供与Servlet容器更深层次的集成，但代价是可移植性。 它们旨在用于将现有Servlet作为端点公开。 对于新端点，应尽可能首选@Endpoint和@WebEndpoint注释。

5.2.7.4 Controller endpoints

@ControllerEndpoint和@RestControllerEndpoint可用于实现仅由Spring MVC或Spring WebFlux公开的端点。 使用Spring MVC和Spring WebFlux的标准注释（如@RequestMapping和@GetMapping）映射方法，并将端点的ID用作路径的前缀。 控制器端点提供与Spring的Web框架更深层次的集成，但代价是可移植性。 应尽可能首选@Endpoint和@WebEndpoint注释。

5.2.8 健康信息

您可以使用运行状况信息来检查正在运行的应用程序的状态。 监视软件经常使用它在生产系统出现故障时提醒某人。 运行状况端点公开的信息取决于management.endpoint.health.show-details属性，该属性可以使用以下值之一进行配置：

永远不会是默认值。 当用户处于一个或多个端点的角色时，将被视为已获得授权。 如果端点没有配置角色（默认值），则认为所有经过身份验证的用户都已获得授权。 可以使用management.endpoint.health.roles属性配置角色。

如果您已保护应用程序并希望始终使用，则安全配置必须允许对经过身份验证和未经身份验证的用户访问运行状况终结点。

健康信息是从HealthIndicatorRegistry的内容中收集的（默认情况下，ApplicationContext中定义的所有HealthIndicator实例。Spring Boot包含许多自动配置的HealthIndicators，您也可以自己编写。默认情况下，最终系统状态由 HealthAggregator根据状态的有序列表对每个HealthIndicator的状态进行排序。排序列表中的第一个状态用作整体健康状态。如果没有HealthIndicator返回HealthAggregator已知的状态，则使用UNKNOWN状态。

HealthIndicatorRegistry可用于在运行时注册和注销健康指示器。

5.2.8.1 自动配置的HealthIndicators

适当时，Spring Boot会自动配置以下HealthIndicator：

您可以通过设置management.health.defaults.enabled属性来禁用它们。

5.2.8.2 编写自定义HealthIndicators

要提供自定义运行状况信息，可以注册实现HealthIndicator接口的Spring bean。 您需要提供health()方法的实现并返回Health响应。 运行状况响应应包括状态，并且可以选择包括要显示的其他详细信息。 以下代码显示了一个示例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(); // perform some specific health check
		if (errorCode != 0) {
			return Health.down().withDetail("Error Code", errorCode).build();
		}
		return Health.up().build();
	}

}

给定HealthIndicator的标识符是没有HealthIndicator后缀的bean的名称（如果存在）。 在前面的示例中，健康信息在名为my的条目中可用。

除了Spring Boot的预定义状态类型之外，Health还可以返回表示新系统状态的自定义状态。 在这种情况下，还需要提供HealthAggregator接口的自定义实现，或者必须使用management.health.status.order配置属性配置默认实现。

例如，假设在您的一个HealthIndicator实现中使用了具有代码FATAL的新状态。 要配置严重性顺序，请将以下属性添加到应用程序属性：

management.health.status.order=FATAL, DOWN, OUT_OF_SERVICE, UNKNOWN, UP

响应中的HTTP状态代码反映了整体运行状况（例如，UP映射到200，而OUT_OF_SERVICE和DOWN映射到503）。 如果通过HTTP访问运行状况端点，则可能还需要注册自定义状态映射。 例如，以下属性将FATAL映射到503（服务不可用）：

management.health.status.http-mapping.FATAL=503

如果需要更多控制，可以定义自己的HealthStatusHttpMapper bean。

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

5.2.8.3 反应健康指标

对于反应式应用程序，例如使用Spring WebFlux的应用程序，ReactiveHealthIndicator提供了一个非阻塞的类来获取应用程序运行状况。 与传统的HealthIndicator类似，健康信息从ReactiveHealthIndicatorRegistry的内容中收集（默认情况下，ApplicationContext中定义的所有HealthIndicator和ReactiveHealthIndicator实例。不检查反应API的Regular HealthIndicator在弹性调度程序上执行。

在响应式应用程序中，ReactiveHealthIndicatorRegistry可用于在运行时注册和取消注册运行状况指示器。

要从反应式API提供自定义运行状况信息，可以注册实现ReactiveHealthIndicator接口的Spring bean。 以下代码显示了ReactiveHealthIndicator实现的示例：

@Component
public class MyReactiveHealthIndicator implements ReactiveHealthIndicator {

	@Override
	public Mono<Health> health() {
		return doHealthCheck() //perform some specific health check that returns a Mono<Health>
			.onErrorResume(ex -> Mono.just(new Health.Builder().down(ex).build())));
	}

}

要自动处理错误，请考虑从AbstractReactiveHealthIndicator进行扩展。

5.2.8.4 自动配置的ReactiveHealthIndicators

适当时，Spring Boot会自动配置以下ReactiveHealthIndicator：

如有必要，应采用反应性指标取代常规指标。此外，未显式处理的任何HealthIndicator都会自动包装。

5.2.9 应用信息

应用程序信息公开从ApplicationContext中定义的所有InfoContributor bean收集的各种信息。 Spring Boot包含许多自动配置的InfoContributor bean，您可以编写自己的bean。

5.2.9.1 自动配置的InfoContributors

适当时，Spring Boot会自动配置以下InfoContributor bean：

可以通过设置management.info.defaults.enabled属性来禁用它们。

5.2.9.2 定制应用信息

您可以通过设置info.* Spring属性来自定义信息端点公开的数据。 信息键下的所有环境属性都会自动公开。 例如，您可以将以下设置添加到application.properties文件中：

info.app.encoding=UTF-8
info.app.java.source=1.8
info.app.java.target=1.8

您可以在构建时扩展信息属性，而不是对这些值进行硬编码。 假设您使用Maven，您可以按如下方式重写前面的示例：

info.app.encoding=@project.build.sourceEncoding@ info.app.java.source=@java.version@ info.app.java.target=@java.version@

5.2.9.3 Git提交信息

nfo端点的另一个有用功能是它能够在构建项目时发布有关git源代码存储库状态的信息。 如果GitProperties bean可用，则公开git.branch，git.commit.id和git.commit.time属性。

果git.properties文件在类路径的根目录中可用，则会自动配置GitProperties bean。 有关更多详细信息，请参阅“生成git信息”。

如果要显示完整的git信息（即git.properties的完整内容），请使用management.info.git.mode属性，如下所示：

management.info.git.mode=full

5.2.9.4 构建信息

如果BuildProperties bean可用，则信息端点还可以发布有关构建的信息。 如果类路径中有META-INF/build-info.properties文件，则会发生这种情况。

Maven和Gradle插件都可以生成该文件。 有关更多详细信息，请参阅“生成构建信息”。

5.2.9.5 编写自定义InfoContributors

要提供自定义应用程序信息，可以注册实现InfoContributor接口的Spring bean。

以下示例提供了具有单个值的示例条目：

import java.util.Collections;

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

@Component
public class ExampleInfoContributor implements InfoContributor {

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

}

如果到达信息端点，您应该看到包含以下附加条目的响应：

{
	"example": {
		"key" : "value"
	}
}