Endpoints

通过执行器端点，您可以监控应用程序并与之交互。Spring Boot包含许多内置端点，允许您添加自己的端点。例如， health端点提供基本的应用程序健康信息。

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

可以使用以下与技术无关的端点：

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

要了解有关Actuator端点及其请求和响应格式的更多信息，请参阅单独的API文档（HTML或 PDF）。

启用端点

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

1

management.endpoint.shutdown.enabled=true

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

1
2

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

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

公开端点

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

要更改端点暴露，使用下面的特定技术include和 exclude特性：

该include属性列出了公开的端点的ID。该exclude 属性列出了不应公开的端点的ID。该exclude 属性优先于该include属性。无论include和exclude 性能可与端点ID列表进行配置。

例如，要停止通过JMX公开所有端点并仅显示端点health和 info端点，请使用以下属性：

1

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

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

1
2

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

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

1
2
3
4
5

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

如果您的申请是公开的，我们强烈建议您也 保护您的终端。

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

保护HTTP端点

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

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

1
2
3
4
5
6
7
8
9
10
11
12

@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属性来执行此操作 ，如下所示：

1

anagement.endpoints.web.exposure.include=*

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

1
2
3
4
5
6
7
8
9
10

@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秒：

1

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

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

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

用于执行器Web端点的超媒体

添加了“发现页面”，其中包含指向所有端点的链接。/actuator默认情况下，“发现页面”可用。

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

CORS支持

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

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

1
2

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

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

实现自定义端点

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

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

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

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

接收输入

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

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

1
2
3
4

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

这可以用于调用，需要一个写操作String name和int counter 参数。

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

为了允许输入映射到操作方法的参数，应该编译实现端点的Java代码-parameters，并且应该编译实现端点的Kotlin代码-java-parameters。如果您使用的是Spring Boot的Gradle插件，或者您正在使用Maven和 spring-boot-starter-parent。

输入类型转换

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

自定义Web端点

操作@Endpoint，@WebEndpoint或者@EndpointWebExtension使用新泽西州，Spring MVC，或Spring WebFlux通过HTTP自动曝光。

Web端点请求谓词

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

路径

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

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

HTTP方法

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

消费

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

产生

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

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

Web端点响应状态

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

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

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

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

Web端点范围请求

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

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

Web端点安全

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

Servlet端点

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

控制器端点

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

健康信息

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

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

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

健康信息是从a的内容中收集的 （默认情况下，所有 实例都在你的Spring中定义.Spring Boot包括一些自动配置 ，你也可以编写自己的。默认情况下，最终的系统状态是通过对状态进行排序得出的从每个 基于状态的有序列表上。在排序列表中的第一个状态用作总体运行状况。如果没有回报是已知的一个状态 ，一个是使用状态。

HealthIndicatorRegistryHealthIndicatorApplicationContext HealthIndicators HealthAggregator HealthIndicator HealthIndicator HealthAggregator UNKNOWN

该HealthIndicatorRegistry可用于注册和在运行时注销卫生指标。

自动配置的HealthIndicators

HealthIndicators适当时，Spring Boot会自动配置以下内容：

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

编写自定义HealthIndicators

要提供自定义运行状况信息，可以注册实现该HealthIndicator接口的Spring bean 。您需要提供health()方法的实现并返回Health 响应。的Health响应应该包括一个状态，并且可以任选地包括另外的细节被显示。以下代码显示了一个示例HealthIndicator 实现：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

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

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

1

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

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

1

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

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

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

反应性健康指标

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

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

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

1
2
3
4
5
6
7
8
9

@Component
public class MyReactiveHealthIndicator implements ReactiveHealthIndicator {

	@Override
	public Mono<Health> health() {
		return doHealthCheck() //执行一些返回Mono <Health> 
			.onErrorResume(ex -> Mono.just(new Health.Builder().down(ex).build())));
	}
}

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

自动配置的ReactiveHealthIndicators

ReactiveHealthIndicators适当时，Spring Boot会自动配置以下内容：

必要时，反应指标取代常规指标。此外，任何 HealthIndicator未明确处理的内容都会自动换行。

应用信息

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

自动配置的InfoContributors

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

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

自定义应用程序信息

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

1
2
3

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

您可以在构建时扩展信息属性，而不是对这些值进行硬编码 。

假设您使用Maven，您可以按如下方式重写前面的示例：

1
2
3

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

Git提交信息

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

一个GitPropertiesbean是自动配置，如果一个git.properties文件可在classpath的根目录。有关更多详细信息，请参阅“ 生成git信息 ”。

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

1

management.info.git.mode=full

构建信息

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

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

编写自定义InfoContributors

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

以下示例example使用单个值提供条目：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

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

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

1
2
3
4
5

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