Spring Boot 参考指南（端点）

50. 端点

Actuator端点让你监视和与应用程序交互，Spring Boot包含许多内置的端点，并容许你添加本身的端点。例如，health端点提供基本的应用程序健康信息。

能够启用或禁用每一个单独的端点，这将控制端点是否被建立，以及它的bean是否存在于应用程序上下文中，要实现远程访问，端点还必须经过JMX或HTTP公开，大多数应用程序选择HTTP，将端点的ID与/actuator的前缀映射到URL。例如，默认状况下，health端点映射到/actuator/health。

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

ID	描述	默认启用
auditevents	公开当前应用程序的审计事件信息	Yes
beans	显示应用程序中全部Spring bean的完整列表	Yes
conditions	显示在配置和自动配置类上评估的条件以及它们是否匹配的缘由	Yes
configprops	显示全部@ConfigurationProperties对照的列表	Yes
env	从Spring的ConfigurableEnvironment中公开属性	Yes
flyway	显示已应用的任何Flyway数据库迁移	Yes
health	显示应用程序健康信息	Yes
httptrace	显示HTTP跟踪信息（默认状况下，最后100个HTTP请求-响应交互）	Yes
info	显示任意应用程序信息	Yes
loggers	显示和修改应用程序中记录器的配置	Yes
liquibase	显示已应用的任何Liquibase数据库迁移	Yes
metrics	显示当前应用程序的“指标”信息	Yes
mappings	显示全部@RequestMapping路径对照的列表	Yes
scheduledtasks	显示应用程序中调度的任务	Yes
sessions	容许从Spring session支持的会话存储中检索和删除用户会话，在使用Spring会话对响应性web应用程序的支持时不可用	Yes
shutdown	让应用程序优雅地关闭	No
threaddump	执行线程转储	Yes

若是你的应用程序是一个web应用程序（Spring MVC、Spring WebFlux或Jersey），你可使用如下附加端点：

ID	描述	默认启用
heapdump	返回一个GZip压缩的hprof堆转储文件	Yes
jolokia	在HTTP上公开JMX bean（当Jolokia在类路径上时，WebFlux不可用）	Yes
logfile	返回日志文件的内容（若是是logging.file或loggin.path属性已经设置了），支持使用HTTP Range header来检索日志文件内容的一部分	Yes
prometheus	公开指标，该格式能够被Prometheus服务器采集	Yes

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

50.1 启用端点

默认状况下，除了shutdown以外的全部端点都启用了，要配置端点的启动，可使用它的management.endpoint.<id>.enabled属性，下面的示例启用关闭端点：

management.endpoint.shutdown.enabled=true

若是你更喜欢端点opt-in而不是opt-out，设置management.endpoints.enabled-by-default属性为false并使用单独的端点启用属性来选择返回，下面的示例启用info端点并禁用全部其余端点：

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

禁用的端点彻底从应用程序上下文中删除，若是你只想更改端点暴露的技术，则使用 include和 exclude属性代替。

50.2 公开端点

因为端点可能包含敏感信息，因此应该仔细考虑什么时候公开它们，下表显示了默认公开的内置端点：

ID	JMX	Web
auditevents	Yes	No
beans	Yes	No
conditions	Yes	No
configprops	Yes	No
env	Yes	No
flyway	Yes	No
health	Yes	Yes
heapdump	N/A	No
httptrace	Yes	No
info	Yes	Yes
jolokia	N/A	No
logfile	N/A	No
loggers	Yes	No
liquibase	Yes	No
metrics	Yes	No
mappings	Yes	No
prometheus	N/A	No
scheduledtasks	Yes	No
sessions	Yes	No
shutdown	Yes	No
threaddump	Yes	No

要更改公开的端点，请使用如下技术特定的include和exclude属性：

属性	默认
management.endpoints.jmx.exposure.exclude
management.endpoints.jmx.exposure.include	*
management.endpoints.web.exposure.exclude
management.endpoints.web.exposure.include	info, health

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

*在YAML中有特殊的含义，因此若是要包含(或排除)全部端点，请务必添加引号，以下例所示:

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

若是你的应用程序是对外公开的，咱们强烈建议你也保护你的端点。

---

若是你想要当端点暴露时实现本身的策略，能够注册 EndpointFilter bean。

50.3 HTTP端点安全

你应该注意保护HTTP端点的方式，就像保护其余敏感URL同样，若是存在Spring Security，则使用Spring Security的内容协商策略默认保护端点。若是你但愿为HTTP端点配置自定义安全性，例如，只容许具备特定角色的用户访问它们，Spring Boot提供了一些方便的RequestMatcher对象，能够与Spring Security结合使用。

一个典型的Spring安全配置可能以下面的示例所示:

@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上还有几个其余的matcher方法，详情请参阅API文档(HTML 或 PDF)。

若是你将应用程序部署到防火墙后，你可能但愿能够在不须要身份验证的状况下访问全部actuator端点，你能够经过更改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()
    }

}

50.4 配置端点

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

application.properties

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

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

在发出通过身份验证的HTTP请求时，Principal被认为是端点的输入，所以不会缓存响应。

50.5 Actuator Web端点的超媒体

一个连接全部端点的“discovery页面”被添加，默认状况下，“ discovery页面”在/actuator上可用。

配置自定义管理上下文路径时，“discovery页面”自动从/actuator移动到管理上下文的根，例如，若是管理上下文路径是/management，那么能够从/management得到discovery页面，当管理上下文路径被设置为/时，discovery页面被禁用，以防止与其余映射发生冲突。

50.6 Actuator Web端点的路径

默认状况下，经过使用端点的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

50.7 CORS支持

跨源资源共享（CORS）是W3C规范，容许你灵活地指定受权的跨域请求类型，若是你使用Spring MVC或Spring WebFlux，能够配置Actuator的web端点来支持这些场景。

CORS支持在默认状况下是禁用的，而且只在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

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

50.8 实现自定义端点

若是你添加一个带@Endpoint注解的@Bean，那么任何带@ReadOperation、@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框架时不可用。

50.8.1 接收输入

端点上的操做经过它们的参数接收输入，当经过web公开时，这些参数的值取自URL的查询参数和JSON请求体，当经过JMX公开时，参数被映射到MBean操做的参数，默认状况下须要参数，可使用@org.springframework.lang.Nullable对它们进行注解，从而使它们成为可选的。

容许将输入映射到操做方法的参数，实现端点的Java代码应该用 -parameters编译，而且实现端点的Kotlin代码应该用 -java-parameters编译，若是你使用Spring Boot的Gradle插件，或者使用Maven和 spring-boot-starter-parent，这将自动发生。

输入类型转换

若是须要，传递给端点操做方法的参数将自动转换为所需的类型，在调用操做方法以前，使用ApplicationConversionService实例将经过JMX或HTTP请求接收的输入转换为所需的类型。

50.8.2 自定义Web端点

对@Endpoint、@WebEndpoint或@WebEndpointExtension的操做经过使用Jersey、Spring MVC或Spring WebFlux经过HTTP自动公开。

Web端点请求谓词

在web公开的端点上，每一个操做都会自动生成一个请求谓词。

路径

谓词的路径由端点的ID和web公开端点的基本路径决定，默认的基本路径是/actuator，例如，具备ID sessions的端点将在谓词中使用/actuator/sessions做为其路径。

经过使用@Selector注解操做方法的一个或多个参数，能够进一步定制路径，这样的参数做为路径变量添加到路径谓词，当调用端点操做时，将变量的值传递给操做方法。

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(Not Found)。

若是@WriteOperation或@DeleteOperation返回一个值，则响应状态为200 (OK)，若是不返回值，响应状态将为204(No Content)。

若是没有必需的参数调用操做，或者参数不能转换为所需的类型，则不会调用操做方法，响应状态将为400(Bad Request)。

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)方法执行受权检查。

50.8.3 Servlet端点

Servlet能够经过实现一个带有@ServletEndpoint注解的类来做为端点公开，这个类也实现了Supplier<EndpointServlet>。Servlet端点提供了与Servlet容器更深层次的集成，但暴露了可移植性，它们用于将现有的Servlet公开为端点。对于新的端点，应该尽量使用@Endpoint和@WebEndpoint注解。

50.8.4 Controller端点

可使用@ControllerEndpoint和@RestControllerEndpoint实现仅由Spring MVC或Spring WebFlux公开的端点，方法使用Spring MVC和Spring WebFlux(如@RequestMapping和@GetMapping)的标准注解进行映射，使用端点的ID做为路径的前缀。Controller端点提供了与Spring web框架的更深刻的集成，但却牺牲了可移植性，尽量使用@Endpoint和@WebEndpoint注解。

50.9 健康信息

你可使用健康信息检查正在运行的应用程序的状态，当生产系统崩溃时，监控软件一般会用它来通知某人，health端点公开的信息取决于management.endpoint.health.show-details属性，可使用如下值之一配置：

never

• 不显示细节

when-authorized

• 详细信息只显示给受权用户，可使用management.endpoint.health.roles配置受权角色

always

• 详细信息显示给全部用户

默认值是never，当用户处于端点的一个或多个角色中时，就被认为是通过受权的，若是端点没有配置角色(默认)，则认为全部通过身份验证的用户都是通过受权的，可使用management.endpoint.health.roles属性。

若是你已经保护了你的应用程序而且但愿使用 always，你的安全配置必须容许对通过身份验证的用户和未经身份验证的用户访问健康端点。

健康信息是从你的ApplicationContext中定义的全部HealthIndicator bean中收集的，Spring Boot包括许多自动配置的HealthIndicators，而且你也能够本身写。默认状况下，最终的系统状态由HealthAggregator派生，它根据有序的状态列表从每一个HealthIndicator排序状态。排序列表中的第一个状态被用做整体健康状态，若是没有HealthAggregator所知道的HealthIndicator状态返回，则使用UNKNOWN状态。

50.9.1 自动配置HealthIndicators

如下的HealthIndicators在适当的时候在Spring Boot中自动配置：

CassandraHealthIndicator

• 检查Cassandra数据库是否已启动

DiskSpaceHealthIndicator

• 检查低磁盘空间

DataSourceHealthIndicator

• 检查可否得到到DataSource的链接

ElasticsearchHealthIndicator

• 检查Elasticsearch集群是否已启动

InfluxDbHealthIndicator

• 检查InfluxDB服务是否已启动

JmsHealthIndicator

• 检查JMS代理是否已启动

MailHealthIndicator

• 检查邮件服务是否已启动

MongoHealthIndicator

• 检查Mongo数据库是否已启动

Neo4jHealthIndicator

• 检查Neo4j服务是否已经启动

RabbitHealthIndicator

• 检查Rabbit服务是否已经启动

RedisHealthIndicator

• 检查Redis服务是否已启动

SolrHealthIndicator

• 检查Solr服务是否已启动

你能够经过设置 management.health.defaults.enabled属性来禁用它们全部。

50.9.2 编写自定义HealthIndicators

要提供自定义的健康信息，你能够注册实现HealthIndicator接口的Spring bean，你须要提供health()方法的实现并返回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的预约义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(service unavailable):

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

若是你须要更多的控制，你能够定义本身的 HealthStatusHttpMapper bean。

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

DOWN

• SERVICE_UNAVAILABLE (503)

OUT_OF_SERVICE

• SERVICE_UNAVAILABLE (503)

UP

• 默认状况下没有映射，因此http状态是200

UNKNOWN

• 默认状况下没有映射，因此http状态是200

50.9.3 Reactive健康指标

---

上一篇：启用生产就绪特性

下一篇：经过HTTP监控和管理