摘要：在發(fā)出經(jīng)過身份驗證的請求時，被認為是端點的輸入，因此不會緩存響應(yīng)。自定義端點對或的操作通過使用或通過自動公開。端點范圍請求范圍請求可以用于請求資源的一部分，當使用或時，操作將返回一個自動支持范圍請求的。

Actuator端點讓你監(jiān)視和與應(yīng)用程序交互，Spring Boot包含許多內(nèi)置的端點，并允許你添加自己的端點。例如，health端點提供基本的應(yīng)用程序健康信息。

可以啟用或禁用每個多帶帶的端點，這將控制端點是否被創(chuàng)建，以及它的bean是否存在于應(yīng)用程序上下文中，要實現(xiàn)遠程訪問，端點還必須通過JMX或HTTP公開，大多數(shù)應(yīng)用程序選擇HTTP，將端點的ID與/actuator的前綴映射到URL。例如，默認情況下，health端點映射到/actuator/health。

可以使用以下與技術(shù)無關(guān)的端點：

如果你的應(yīng)用程序是一個web應(yīng)用程序（Spring MVC、Spring WebFlux或Jersey），你可以使用以下附加端點：

要了解有關(guān)Actuator的端點及其請求和響應(yīng)格式的更多信息，請參考多帶帶的API文檔(HTML 或 PDF)。

默認情況下，除了shutdown之外的所有端點都啟用了，要配置端點的啟動，可以使用它的management.endpoint..enabled屬性，下面的示例啟用關(guān)閉端點：

management.endpoint.shutdown.enabled=true

如果你更喜歡端點opt-in而不是opt-out，設(shè)置management.endpoints.enabled-by-default屬性為false并使用多帶帶的端點啟用屬性來選擇返回，下面的示例啟用info端點并禁用所有其他端點：

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

禁用的端點完全從應(yīng)用程序上下文中刪除，如果你只想更改端點暴露的技術(shù)，則使用include和exclude屬性代替。

由于端點可能包含敏感信息，所以應(yīng)該仔細考慮何時公開它們，下表顯示了默認公開的內(nèi)置端點：

要更改公開的端點，請使用以下技術(shù)特定的include和exclude屬性：

include屬性列出了公開的端點的id，exclude屬性列出不應(yīng)公開的端點的id，exclude屬性優(yōu)先于include屬性，include和exclude屬性都可以使用端點id列表進行配置。

例如，要停止在JMX上公開所有端點，并且只公開health和info端點，請使用以下屬性:

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

*可用于選擇所有端點，例如，要通過HTTP公開除env和beans端點之外的所有內(nèi)容，請使用以下屬性:

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

*在YAML中有特殊的含義，所以如果要包含(或排除)所有端點，請務(wù)必添加引號，如下例所示:

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

如果你的應(yīng)用程序是對外公開的，我們強烈建議你也保護你的端點。

如果你想要當端點暴露時實現(xiàn)自己的策略，可以注冊EndpointFilter bean。

你應(yīng)該注意保護HTTP端點的方式，就像保護其他敏感URL一樣，如果存在Spring Security，則使用Spring Security的內(nèi)容協(xié)商策略默認保護端點。如果你希望為HTTP端點配置自定義安全性，例如，只允許具有特定角色的用戶訪問它們，Spring Boot提供了一些方便的RequestMatcher對象，可以與Spring Security結(jié)合使用。

一個典型的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)。

如果你將應(yīng)用程序部署到防火墻后，你可能希望可以在不需要身份驗證的情況下訪問所有actuator端點，你可以通過更改management.endpoints.web.exposure.include屬性來實現(xiàn)這一點，如下:

application.properties

management.endpoints.web.exposure.include=*

此外，如果存在Spring Security，則需要添加自定義安全配置，允許對端點進行未經(jīng)身份驗證的訪問，如下面的示例所示:

@Configuration
public class ActuatorSecurity extends WebSecurityConfigurerAdapter {

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

}

端點為不帶任何參數(shù)的讀取操作自動緩存響應(yīng)，要配置端點緩存響應(yīng)的時間量，請使用cache.time-to-live屬性，下面的示例將beans端點緩存的生存時間設(shè)置為10秒：

application.properties

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

前綴management.endpoint.用于惟一地標識正在配置的端點。
在發(fā)出經(jīng)過身份驗證的HTTP請求時，Principal被認為是端點的輸入，因此不會緩存響應(yīng)。

一個鏈接所有端點的“discovery頁面”被添加，默認情況下，“ discovery頁面”在/actuator上可用。

配置自定義管理上下文路徑時，“discovery頁面”自動從/actuator移動到管理上下文的根，例如，如果管理上下文路徑是/management，那么可以從/management獲得discovery頁面，當管理上下文路徑被設(shè)置為/時，discovery頁面被禁用，以防止與其他映射發(fā)生沖突。

默認情況下，通過使用端點的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規(guī)范，允許你靈活地指定授權(quán)的跨域請求類型，如果你使用Spring MVC或Spring WebFlux，可以配置Actuator的web端點來支持這些場景。

CORS支持在默認情況下是禁用的，并且只在management.endpoints.web.cors.allowed-origins屬性已設(shè)置時才啟用，以下配置允許從example.com域GET和POST調(diào)用:

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

有關(guān)選項的完整列表，請參見CorsEndpointProperties

如果你添加一個帶@Endpoint注解的@Bean，那么任何帶@ReadOperation、@WriteOperation或@DeleteOperation的方法都會自動地通過JMX公開，在web應(yīng)用程序中，也會通過HTTP公開，可以使用Jersey、Spring MVC或Spring WebFlux通過HTTP公開端點。

你還可以使用@JmxEndpoint或@WebEndpoint來編寫特定于技術(shù)的端點，這些端點僅限于各自的技術(shù)，例如，@WebEndpoint僅通過HTTP公開，而不是通過JMX公開。

可以使用@EndpointWebExtension和@EndpointJmxExtension編寫特定于技術(shù)的擴展，這些注解允許你提供特定于技術(shù)的操作，以增強現(xiàn)有的端點。

最后，如果你需要訪問特定于web框架的功能，你可以實現(xiàn)Servlet或Spring @Controller和@RestController端點，代價是它們在JMX上不可用，或者在使用不同的web框架時不可用。

端點上的操作通過它們的參數(shù)接收輸入，當通過web公開時，這些參數(shù)的值取自URL的查詢參數(shù)和JSON請求體，當通過JMX公開時，參數(shù)被映射到MBean操作的參數(shù)，默認情況下需要參數(shù)，可以使用@org.springframework.lang.Nullable對它們進行注解，從而使它們成為可選的。

允許將輸入映射到操作方法的參數(shù)，實現(xiàn)端點的Java代碼應(yīng)該用-parameters編譯，并且實現(xiàn)端點的Kotlin代碼應(yīng)該用-java-parameters編譯，如果你使用Spring Boot的Gradle插件，或者使用Maven和spring-boot-starter-parent，這將自動發(fā)生。

輸入類型轉(zhuǎn)換

如果需要，傳遞給端點操作方法的參數(shù)將自動轉(zhuǎn)換為所需的類型，在調(diào)用操作方法之前，使用ApplicationConversionService實例將通過JMX或HTTP請求接收的輸入轉(zhuǎn)換為所需的類型。

對@Endpoint、@WebEndpoint或@WebEndpointExtension的操作通過使用Jersey、Spring MVC或Spring WebFlux通過HTTP自動公開。

在web公開的端點上，每個操作都會自動生成一個請求謂詞。

謂詞的路徑由端點的ID和web公開端點的基本路徑?jīng)Q定，默認的基本路徑是/actuator，例如，具有ID sessions的端點將在謂詞中使用/actuator/sessions作為其路徑。

通過使用@Selector注解操作方法的一個或多個參數(shù)，可以進一步定制路徑，這樣的參數(shù)作為路徑變量添加到路徑謂詞，當調(diào)用端點操作時，將變量的值傳遞給操作方法。

謂詞的HTTP方法由操作類型決定，如下表所示:

@ReadOperation => GET

@WriteOperation => POST

@DeleteOperation => DELETE

對于使用請求體的@WriteOperation (HTTP POST)，謂詞的消費子句是application/vnd.spring-boot.actuator.v2+json, application/json，對于所有其他操作，消費子句為空。

謂詞的生產(chǎn)子句可以由@DeleteOperation、@ReadOperation和@WriteOperation注解的produces屬性確定，屬性是可選的，如果不使用，則自動確定“生成”子句。

如果操作方法返回void或Void，則生成子句為空，如果操作方法返回一個org.springframework.core.io.Resource，生成子句是application/octet-stream。對于所有其他操作，生成子句是application/vnd.spring-boot.actuator.v2+json, application/json。

端點操作的默認響應(yīng)狀態(tài)取決于操作類型(讀、寫或刪除)以及操作返回的內(nèi)容(如果有的話)。

@ReadOperation返回一個值，響應(yīng)狀態(tài)為200 (OK)，如果不返回值，響應(yīng)狀態(tài)將為404(Not Found)。

如果@WriteOperation或@DeleteOperation返回一個值，則響應(yīng)狀態(tài)為200 (OK)，如果不返回值，響應(yīng)狀態(tài)將為204(No Content)。

如果沒有必需的參數(shù)調(diào)用操作，或者參數(shù)不能轉(zhuǎn)換為所需的類型，則不會調(diào)用操作方法，響應(yīng)狀態(tài)將為400(Bad Request)。

HTTP范圍請求可以用于請求HTTP資源的一部分，當使用Spring MVC或Spring Web Flux時，操作將返回一個自動支持范圍請求的org.springframework.core.io.Resource。

使用Jersey時不支持范圍請求

web端點或特定于web的端點擴展上的操作可以接收當前的java.security.Principal或org.springframework.boot.actuate.endpoint.SecurityContext作為一個方法參數(shù)。前者通常與@Nullable一起使用，用于為經(jīng)過身份驗證的用戶和未經(jīng)身份驗證的用戶提供不同的行為，后者通常用于使用其isUserInRole(String)方法執(zhí)行授權(quán)檢查。

Servlet可以通過實現(xiàn)一個帶有@ServletEndpoint注解的類來作為端點公開，這個類也實現(xiàn)了Supplier。Servlet端點提供了與Servlet容器更深層次的集成，但暴露了可移植性，它們用于將現(xiàn)有的Servlet公開為端點。對于新的端點，應(yīng)該盡可能使用@Endpoint和@WebEndpoint注解。

可以使用@ControllerEndpoint和@RestControllerEndpoint實現(xiàn)僅由Spring MVC或Spring WebFlux公開的端點，方法使用Spring MVC和Spring WebFlux(如@RequestMapping和@GetMapping)的標準注解進行映射，使用端點的ID作為路徑的前綴。Controller端點提供了與Spring web框架的更深入的集成，但卻犧牲了可移植性，盡可能使用@Endpoint和@WebEndpoint注解。

你可以使用健康信息檢查正在運行的應(yīng)用程序的狀態(tài)，當生產(chǎn)系統(tǒng)崩潰時，監(jiān)控軟件通常會用它來通知某人，health端點公開的信息取決于management.endpoint.health.show-details屬性，可以使用以下值之一配置：

never

不顯示細節(jié)

when-authorized

詳細信息只顯示給授權(quán)用戶，可以使用management.endpoint.health.roles配置授權(quán)角色

always

詳細信息顯示給所有用戶

默認值是never，當用戶處于端點的一個或多個角色中時，就被認為是經(jīng)過授權(quán)的，如果端點沒有配置角色(默認)，則認為所有經(jīng)過身份驗證的用戶都是經(jīng)過授權(quán)的，可以使用management.endpoint.health.roles屬性。

如果你已經(jīng)保護了你的應(yīng)用程序并且希望使用always，你的安全配置必須允許對經(jīng)過身份驗證的用戶和未經(jīng)身份驗證的用戶訪問健康端點。

健康信息是從你的ApplicationContext中定義的所有HealthIndicator bean中收集的，Spring Boot包括許多自動配置的HealthIndicators，并且你也可以自己寫。默認情況下，最終的系統(tǒng)狀態(tài)由HealthAggregator派生，它根據(jù)有序的狀態(tài)列表從每個HealthIndicator排序狀態(tài)。排序列表中的第一個狀態(tài)被用作總體健康狀態(tài)，如果沒有HealthAggregator所知道的HealthIndicator狀態(tài)返回，則使用UNKNOWN狀態(tài)。

以下的HealthIndicators在適當?shù)臅r候在Spring Boot中自動配置：

CassandraHealthIndicator

檢查Cassandra數(shù)據(jù)庫是否已啟動

DiskSpaceHealthIndicator

檢查低磁盤空間

DataSourceHealthIndicator

檢查能否獲得到DataSource的連接

ElasticsearchHealthIndicator

檢查Elasticsearch集群是否已啟動

InfluxDbHealthIndicator

檢查InfluxDB服務(wù)是否已啟動

JmsHealthIndicator

檢查JMS代理是否已啟動

MailHealthIndicator

檢查郵件服務(wù)是否已啟動

MongoHealthIndicator

檢查Mongo數(shù)據(jù)庫是否已啟動

Neo4jHealthIndicator

檢查Neo4j服務(wù)是否已經(jīng)啟動

RabbitHealthIndicator

檢查Rabbit服務(wù)是否已經(jīng)啟動

RedisHealthIndicator

檢查Redis服務(wù)是否已啟動

SolrHealthIndicator

檢查Solr服務(wù)是否已啟動

你可以通過設(shè)置management.health.defaults.enabled屬性來禁用它們所有。

要提供自定義的健康信息，你可以注冊實現(xiàn)HealthIndicator接口的Spring bean，你需要提供health()方法的實現(xiàn)并返回Health響應(yīng)。Health響應(yīng)應(yīng)該包含一個狀態(tài)，可以選擇包含要顯示的其他細節(jié)，下面的代碼顯示了一個示例HealthIndicator實現(xiàn)：

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的預(yù)定義Status類型之外，Health還可以返回表示新系統(tǒng)狀態(tài)的自定義Status，在這種情況下，還需要提供HealthAggregator接口的自定義實現(xiàn)，或者，默認實現(xiàn)是使用management.health.status.order配置屬性。

例如，假設(shè)在你的一個HealthIndicator實現(xiàn)中使用了一個帶有代碼FATAL的新Status，要配置嚴重性順序，請在應(yīng)用程序?qū)傩灾刑砑右韵聦傩?

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

響應(yīng)中的HTTP狀態(tài)代碼反映總體健康狀態(tài)(例如，UP映射到200，而OUT_OF_SERVICE和DOWN映射到503)，如果你通過HTTP訪問健康端點，你可能還想注冊自定義狀態(tài)映射，例如，以下屬性將FATAL映射到503(service unavailable):

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

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

下表顯示了內(nèi)建狀態(tài)的默認狀態(tài)映射：

DOWN

SERVICE_UNAVAILABLE (503)

OUT_OF_SERVICE

SERVICE_UNAVAILABLE (503)

UP

默認情況下沒有映射，所以http狀態(tài)是200

UNKNOWN

默認情況下沒有映射，所以http狀態(tài)是200