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

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

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

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

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

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

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

management.endpoint.shutdown.enabled=true

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

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

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

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

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

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

例如，要停止在JMX上公開所有端點(diǎn)，并且只公開health和info端點(diǎn)，請(qǐng)使用以下屬性:

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

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

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

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

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

如果你的應(yīng)用程序是對(duì)外公開的，我們強(qiáng)烈建議你也保護(hù)你的端點(diǎn)。

如果你想要當(dāng)端點(diǎn)暴露時(shí)實(shí)現(xiàn)自己的策略，可以注冊(cè)EndpointFilter bean。

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

一個(gè)典型的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()匹配任何端點(diǎn)的請(qǐng)求，然后確保所有端點(diǎn)都具有ENDPOINT_ADMIN角色，在EndpointRequest上還有幾個(gè)其他的matcher方法，詳情請(qǐng)參閱API文檔(HTML 或 PDF)。

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

application.properties

management.endpoints.web.exposure.include=*

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

@Configuration
public class ActuatorSecurity extends WebSecurityConfigurerAdapter {

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

}

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

application.properties

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

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

一個(gè)鏈接所有端點(diǎn)的“discovery頁面”被添加，默認(rèn)情況下，“ discovery頁面”在/actuator上可用。

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

默認(rèn)情況下，通過使用端點(diǎn)的ID在/actuator路徑下通過HTTP公開端點(diǎn)，例如，beans端點(diǎn)在/actuator/beans下公開，如果希望將端點(diǎn)映射到不同的路徑，可以使用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)的跨域請(qǐng)求類型，如果你使用Spring MVC或Spring WebFlux，可以配置Actuator的web端點(diǎn)來支持這些場(chǎng)景。

CORS支持在默認(rèn)情況下是禁用的，并且只在management.endpoints.web.cors.allowed-origins屬性已設(shè)置時(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)選項(xiàng)的完整列表，請(qǐng)參見CorsEndpointProperties

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

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

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

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

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

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

輸入類型轉(zhuǎn)換

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

對(duì)@Endpoint、@WebEndpoint或@WebEndpointExtension的操作通過使用Jersey、Spring MVC或Spring WebFlux通過HTTP自動(dòng)公開。

在web公開的端點(diǎn)上，每個(gè)操作都會(huì)自動(dòng)生成一個(gè)請(qǐng)求謂詞。

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

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

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

@ReadOperation => GET

@WriteOperation => POST

@DeleteOperation => DELETE

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

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

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

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

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

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

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

HTTP范圍請(qǐng)求可以用于請(qǐng)求HTTP資源的一部分，當(dāng)使用Spring MVC或Spring Web Flux時(shí)，操作將返回一個(gè)自動(dòng)支持范圍請(qǐng)求的org.springframework.core.io.Resource。

使用Jersey時(shí)不支持范圍請(qǐng)求

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

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

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

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

never

不顯示細(xì)節(jié)

when-authorized

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

always

詳細(xì)信息顯示給所有用戶

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

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

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

以下的HealthIndicators在適當(dāng)?shù)臅r(shí)候在Spring Boot中自動(dòng)配置：

CassandraHealthIndicator

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

DiskSpaceHealthIndicator

檢查低磁盤空間

DataSourceHealthIndicator

檢查能否獲得到DataSource的連接

ElasticsearchHealthIndicator

檢查Elasticsearch集群是否已啟動(dòng)

InfluxDbHealthIndicator

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

JmsHealthIndicator

檢查JMS代理是否已啟動(dòng)

MailHealthIndicator

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

MongoHealthIndicator

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

Neo4jHealthIndicator

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

RabbitHealthIndicator

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

RedisHealthIndicator

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

SolrHealthIndicator

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

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

要提供自定義的健康信息，你可以注冊(cè)實(shí)現(xiàn)HealthIndicator接口的Spring bean，你需要提供health()方法的實(shí)現(xiàn)并返回Health響應(yīng)。Health響應(yīng)應(yīng)該包含一個(gè)狀態(tài)，可以選擇包含要顯示的其他細(xì)節(jié)，下面的代碼顯示了一個(gè)示例HealthIndicator實(shí)現(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的標(biāo)識(shí)符是沒有HealthIndicator后綴的bean的名稱(如果存在的話)，在前面的示例中，健康信息可以在名為my的條目中獲得。

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

例如，假設(shè)在你的一個(gè)HealthIndicator實(shí)現(xiàn)中使用了一個(gè)帶有代碼FATAL的新Status，要配置嚴(yán)重性順序，請(qǐng)?jiān)趹?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訪問健康端點(diǎn)，你可能還想注冊(cè)自定義狀態(tài)映射，例如，以下屬性將FATAL映射到503(service unavailable):

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

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

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

DOWN

SERVICE_UNAVAILABLE (503)

OUT_OF_SERVICE

SERVICE_UNAVAILABLE (503)

UP

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

UNKNOWN

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