章节 V. Spring Boot 执行器: 生产就绪特性

默认情况下，启用除 shutdown 以外的所有节点。若要配置节点的启用，请使用其 management.endpoint.<id>.enabled 的属性。下面的示例启用 shutdown 节点：

management.endpoint.shutdown.enabled=true

如果希望节点启用是 opt-in 而不是 opt-out，请将 management.endpoints.enabled-by-default 属性设置为 false，并使用单独的节点 enabled 属性选择返回。下面的示例启用 info 节点并禁用所有其它节点：

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

	Note
	禁用节点完全从应用程序上下文中删除。如果仅希望更改公开节点的技术，则使用 include 和 exclude 属性。

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

要更改暴露哪些节点，请使用以下特定技术的 include 和 exclude 属性：

include 属性列出了被暴露的节点的 ID。exclude 属性列出不应该暴露的节点的ID。exclude 属性优先于 include 属性。include 和 exclude 属性都可以用节点 ID 列表来配置。

例如，要停止通过 JMX 暴露所有节点，并且只暴露 health 和 info 节点，请使用以下属性：

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

* 可以用来选择所有节点。例如，若要通过 HTTP 暴露除了 env 和 beans 节点之外的所有内容，请使用以下属性：

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

	Note
	*在 YAML 中具有特殊含义，因此如果希望包含（或排除）所有节点，请确保添加引号，如下例所示： management: endpoints: web: exposure: include: "*"

	Note
	如果你的应用程序公开暴露，我们强烈建议你也保护你的节点。

	Tip
	如果希望实现自己的策略，以便暴露节点时，可以注册 EndpointFilter bean。

你应该像保护其它敏感 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 属性来实现这一点，如下：

application.properties. 

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();
	}

}

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

application.properties. 

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

	Note
	management.endpoint.<name> 前缀用于唯一标识正在配置的节点。

	Note
	当发出经过身份验证的 HTTP 请求时，Principal 被视为节点的输入，因此不会缓存响应。

在发现页中添加指向所有节点的链接。默认情况下，发现页可在 /actuator 上使用。

当配置自定义管理上下文路径时，发现页自动从 /actuator 移动到管理上下文的根。例如，如果管理上下文路径是 /management ，那么可以从 /management 获得发现页面。当管理上下文路径设置为 / 时，发现页面将被禁用，以防止与其它映射发生冲突的可能性。

默认情况下，节点使用的 ID 在 /actuator 路径下通过 HTTP 暴露节点。例如，beans 节点在 /actuator/beans 下暴露。如果希望将节点映射到其它路径，可以使用 management.endpoints.web.path-mapping 属性。此外，如果要更改基本路径，可以使用 management.endpoints.web.base-path。

下面的示例将 /actuator/health 重新映射到 /healthcheck：

application.properties. 

management.endpoints.web.base-path=/
management.endpoints.web.path-mapping.health=healthcheck

跨域资源共享（CORS）是一个 W3C 规范，它允许你以灵活的方式指定授权的跨域请求的种类。如果使用 Spring MVC 或 Spring WebFlux，则可以将执行器的 web 节点配置为支持这样的场景。

跨域支持在默认情况下是禁用的，并且仅在设置了 management.endpoints.web.cors.allowed-origins 属性之后才启用。下面的配置允许从 example.com 域获取 GET 和 POST 调用：

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

	Tip
	完整的选项列表请参阅 CorsEndpointProperties。

如果添加了 @Bean 注解为 @Endpoint，则任何注解为 @ReadOperation、@WriteOperation 或 @DeleteOperation 的方法都会自动通过 JMX 暴露，在 web 应用程序中，也会通过 HTTP暴露。节点可以通过 HTTP 使用 Jersey、Spring MVC 或 Spring WebFlux 进行暴露。

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

可以使用 @EndpointWebExtension 和 @EndpointJmxExtension 编写特定技术的扩展。这些注解允许你提供特定技术的操作以扩充现有节点。

最后，如果需要访问特定 web 框架的功能，则可以实现 Servlet 或 Spring @Controller 和 @RestController 节点，代价是它们不能通过 JMX 获得，或者当使用不同的 web 框架时。

51.8.1 接收输入

节点上的操作通过它们的参数接收输入。当通过 web 暴露时，这些参数的值取自 URL 的查询参数和 JSON 请求主体。当通过 JMX 暴露时，参数被映射到 MBean 操作的参数。默认情况下需要参数，可以通过 @org.springframework.lang.Nullable 注解它们来进行选择。

	Note
	为了允许输入映射到操作方法的参数，实现一个节点的 Java 代码应该用 -parameters 编译，而实现节点的 Kotlin 代码应该用 -java-parameters 编译。如果你正在使用 Spring Boot 的 Gradle 插件，或者你正在使用 Maven 和 spring-boot-starter-parent，则这些将自动发生。

输入类型转换

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

51.8.2 自定义 Web 节点

@Endpoint、@WebEndpoint 或 @WebEndpointExtension 上的操作使用 Jersey、Spring MVC 或 Spring WebFlux 通过 HTTP 自动暴露。

Web 节点请求断言

对于 Web 暴露节点上的每个操作，自动生成请求谓词。

路径

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

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

HTTP 方法

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

操作	HTTP 方法
@ReadOperation	GET
@WriteOperation	POST
@DeleteOperation	DELETE

消费者

对于使用请求体的 @WriteOperation（HTTP POST），谓词的消费者子句是 application/vnd.spring-boot.actuator.v2+json, application/json。对于所有其它操作，消费者子句都是空的。

生产者

谓词的提供者子句可以由 @DeleteOperation、@ReadOperation 和 @WriteOperation 注解的 produces 属性确定。属性是可选的。如果不使用，则生产者子句自动确定。

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

Web 节点响应状态

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

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

如果 @WriteOperation 或 @DeleteOperation 返回一个值，则响应状态将为 200（ok）。如果它不返回一个值，则响应状态将为 204（无内容）。

如果调用操作时没有必需的参数，或者参数不能转换为所需的类型，则不会调用操作方法，响应状态将为 400（Bad Request）。

Web 节点范围请求

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

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

Web 节点安全性

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

你可以使用健康信息来检查运行的应用程序状态。当生产系统下降时，它经常被监控软件用来提醒某人。健康节点暴露的信息取决于 management.endpoint.health.show-details 属性，可以使用以下值之一进行配置：

默认值为 never。当用户处于节点的一个或多个角色时，被认为是被授权的。如果节点没有配置的角色（默认的），所有经认证的用户都被认为是授权的。角色可以使用 management.endpoint.health.roles 属性配置。

	Note
	如果你已经保护了应用程序并希望一直使用，则安全配置必须允许已验证和未验证的用户访问健康节点。

健康信息是从 HealthIndicatorRegistry（默认情况下在 ApplicationContext 中定义的所有 HealthIndicator 实例）的内容中收集的。Spring Boot 包含一些自动配置的 HealthIndicators，你也可以自己编写。默认情况下，HealthAggregator 根据每个基于状态的有序列表的 HealthIndicator 状态派生出最终的系统状态，有序列表中的第一个状态被用作总体健康状态。如果没有 HealthIndicator 返回 HealthAggregator 所知道的状态，则使用 UNKNOWN 状态。

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

51.9.1 自动配置健康指标

Spring Boot 在适时自动配置下列 HealthIndicators：

名称	描述
CassandraHealthIndicator	检查 Cassandra 数据库是否正常运行。
DiskSpaceHealthIndicator	检查磁盘空间不足。.
DataSourceHealthIndicator	检查是否可以获得与 DataSource 的连接。
ElasticsearchHealthIndicator	检查 Elasticsearch 集群是否正常运行。
InfluxDbHealthIndicator	检查 InfluxDB 服务器是否正常运行。
JmsHealthIndicator	检查 JMS 代理是否正常运行。
MailHealthIndicator	检查邮件服务器是否正常运行。
MongoHealthIndicator	检查 Mongo 数据库是否正常运行。
Neo4jHealthIndicator	检查 Neo4j 服务器是否正常运行。
RabbitHealthIndicator	检查 Rabbit 服务器是否正常运行。
RedisHealthIndicator	检查 Redis 服务器是否正常运行。
SolrHealthIndicator	检查 Solr 服务器是否正常运行。

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

51.9.2 编写自定义健康指标

为了提供自定义的健康信息，可以注册实现 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();
	}

}

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

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

例如，假设在你的 HealthIndicator 实现中使用了代码 FATAL 的新 Status。若要配置严重性顺序，请将以下属性添加到应用程序属性中：

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

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

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

状态	映射
DOWN	SERVICE_UNAVAILABLE (503)
OUT_OF_SERVICE	SERVICE_UNAVAILABLE (503)
UP	No mapping by default, so http status is 200
UNKNOWN	No mapping by default, so http status is 200

51.9.3 响应式健康指标

对于响应式应用程序，例如使用 Spring WebFlux 的应用程序，ReactiveHealthIndicator 提供了用于获得应用程序健康的非阻塞协议。类似于传统的 HealthIndicator，健康信息是从 ReactiveHealthIndicatorRegistry（默认情况下是 ApplicationContext 中定义的所有 HealthIndicator 和 ReactiveHealthIndicator 实例）的内容中收集的。在弹性调度器上之心不检查响应式 API 的常规 HealthIndicator。

	Tip
	在响应式应用程序中，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())));
	}

}

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

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

下列反应性健康指标在适当的时候由弹簧引导自动配置： Spring Boot 在适当的时候自动配下列 ReactiveHealthIndicators：

名称	描述
MongoReactiveHealthIndicator	检查 Mongo 数据库是否正常运行。
RedisReactiveHealthIndicator	检查 Redis 服务器是否正常运行。

	Tip
	必要时，响应式指标代替常规指标。此外，未显式处理的任何 HealthIndicator 都自动包装。

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

51.10.1 自动配置信息提供者

在适当的时候，Spring Boot 自动配置下列 InfoContributor bean：

名称	描述
EnvironmentInfoContributor	在 info 键下暴露任何 Environment 键。
GitInfoContributor	在 git.properties 文件可用时暴漏 git 信息。
BuildInfoContributor	在 META-INF/build-info.properties 文件可用时暴漏构建信息。

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

51.10.2 自定义应用程序信息

通过设置 info.* Spring 属性，可以自定义由 info 节点暴露的数据。info 键下的所有 Environment 属性都会自动暴露。例如，可以向 application.properties 文件添加以下设置：

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

	Tip
	你可以在编译时扩展信息属性，而不是对这些值进行硬编码。 假设你使用 Maven，可以将前面的示例重写如下： info.app.encoding=@project.build.sourceEncoding@ info.app.java.source=@java.version@ info.app.java.target=@java.version@

51.10.3 Git 提交信息

info 节点的另一个有用特性是它能够在构建项目时发布关于 git 源代码存储库状态的信息。如果 GitProperties bean 可用，则暴露 git.branch、git.commit.id 和 git.commit.time 属性。

	Tip
	如果 git.properties 文件在类路径的根部可用，则自动配置 GitProperties bean。详细信息请参阅"生成 git 信息"。

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

management.info.git.mode=full

51.10.4 构建信息

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

	Tip
	Maven 和 Gradle 插件都可以生成该文件。有关的详细信息请参阅"生成构建信息"。

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"
	}
}