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監控和管理