Spring Boot 生产就绪中文文档-上

本文为官方文档直译版本。原文链接
由于篇幅较长，遂分两篇。下半部分中文文档

引言

Spring Boot 包含大量附加功能，可帮助您在将应用程序推向生产时对其进行监控和管理。您可以选择使用 HTTP 端点或 JMX 来管理和监控应用程序。审计、健康状况和指标收集也可自动应用于您的应用程序。

启用 Production-ready 功能

spring-boot-actuator 模块提供了 Spring Boot production-ready 的所有功能。启用这些功能的推荐方法是添加对 spring-boot-starter-actuator "Starter "的依赖。

执行器(Actuator)的定义
执行器是一个制造术语，指用于移动或控制某物的机械装置。推杆可以通过微小的变化产生较大的运动。

要将执行器添加到基于 Maven 的项目中，请添加以下 "Starter "依赖关系：

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
</dependencies>

对于 Gradle，使用以下声明：

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

端点（Endpoints）

执行器端点可让您监控应用程序并与之交互。Spring Boot 包含许多内置端点，您还可以添加自己的端点。例如，health 端点提供基本的应用程序健康信息。
您可以启用或禁用每个单独的端点，并通过 HTTP 或 JMX 将其公开（使其可远程访问）。当一个端点同时启用和暴露时，它就被认为是可用的。内置端点只有在可用时才会自动配置。大多数应用程序会选择通过 HTTP 暴露，端点的 ID 和 /actuator 前缀会映射到 URL。例如，默认情况下，健康端点映射到 /actuator/health。

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

可提供以下与技术无关的端点：

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

启用端点

默认情况下，除shutdown（关机）外的所有端点都已启用。要配置端点的启用，请使用其 management.endpoint.<id>.enabled 属性。下面的示例启用了shutdown（关机）端点：

management:
  endpoint:
    shutdown:
      enabled: true

如果希望端点启用是“opt-in“而不是”opt-out“，可将 management.endpoints.enabled-by-default 属性设置为 false，然后使用单个端点启用属性重新选择进入。下面的示例启用了 info 端点，并禁用了所有其他端点：

management:
  endpoints:
    enabled-by-default: false
  endpoint:
    info:
      enabled: true

顺便说一下”opt-in“和”opt-out“
opt-in：《通用数据保护法》（General Data Protection Regulation,简称GDPR)于2018年5月开始生效，其目的是让互联网用户重获个人数据控制权。任何以电子邮件形式进行的促销活动都需要用户明确的同意，即“opt-in”（选择同意接受电子邮件广告），从而限制滥用。Opt-in是指用户明确同意接收某个企业的信息，通常是营销和广告。网站用户可通过选择“Opt-in”明确表示同意接收营销和促销信息。
opt-out：Opt-out是发送商业性电子邮件的另一种做法。这种方法允许企业在未征得互联网用户同意的情况下发送电子邮件。虽然Opt-out是合法的，但受到严格监管。Opt-out只能在两种特定情况下使用。

• 当用户已经同意企业使用其个人数据时，企业可向用户发送类似可订阅的电子报，其中内容可能包括同一公司或其合作伙伴的产品。
• 如果企业提供与互联网用户有关的服务，那它有权采用opt-out并在其电子邮件中加入商业提案。

然而，互联网用户必须被明确告知其数据使用目的，以及是否有权撤销同意。如果用户要撤销同意，必须告知企业不希望个人数据被用于这项特定的服务。通常也是勾选一个方框即可完成。

上述参考自：什么是Opt-in？

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

暴露端点

默认情况下，只有健康状况端点通过 HTTP 和 JMX 公开。由于端点可能包含敏感信息，因此应仔细考虑何时暴露端点。
要更改暴露哪些端点，请使用以下特定于技术的包含和排除属性：

include 属性列出了暴露的端点 ID。exclude属性列出了不应暴露的端点 ID。exclude属性优先于include 属性。可以使用端点 ID 列表配置include 和exclude属性。
例如，要只通过 JMX 公开健康和信息端点，请使用以下属性：

management:
  endpoints:
    jmx:
      exposure:
        include: "health,info"

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

management:
  endpoints:
    web:
      exposure:
        include: "*"
        exclude: "env,beans"

* 在 YAML 中有特殊含义，因此如果要包含（或排除）所有端点，请务必加上引号。

如果您的应用程序是公开暴露的，我们强烈建议您也确保端点的安全。

如果您想在端点暴露时实施自己的策略，可以注册一个 EndpointFilter Bean。

安全

出于安全考虑，默认情况下只有 /health 端点通过 HTTP 暴露。你可以使用 management.endpoints.web.exposure.include 属性来配置暴露的端点。

在设置 management.endpoints.web.exposure.include 之前，请确保被暴露的执行器不包含敏感信息，并将其置于防火墙之后以确保安全，或使用类似 Spring Security 这样的软件确保安全。

如果 Spring Security 位于类路径上，并且不存在其他 SecurityFilterChain Bean，那么除 /health 之外的所有执行器都会受到 Spring Boot 自动配置的保护。如果您定义了自定义 SecurityFilterChain Bean，Spring Boot 自动配置就会退出，让您完全控制执行器的访问规则。
如果您想为 HTTP 端点配置自定义安全性（例如，只允许具有特定角色的用户访问这些端点），Spring Boot 提供了一些方便的 RequestMatcher 对象，您可以将其与 Spring Security 结合使用。
典型的 Spring Security 配置可能与下面的示例类似：

import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

import static org.springframework.security.config.Customizer.withDefaults;

@Configuration(proxyBeanMethods = false)
public class MySecurityConfiguration {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.securityMatcher(EndpointRequest.toAnyEndpoint());
        http.authorizeHttpRequests((requests) -> requests.anyRequest().hasRole("ENDPOINT_ADMIN"));
        http.httpBasic(withDefaults());
        return http.build();
    }

}

前面的示例使用 EndpointRequest.toAnyEndpoint() 将请求匹配到任何端点，然后确保所有端点都具有 ENDPOINT_ADMIN 角色。EndpointRequest 上还有其他几种匹配器方法。详情请查看 API 文档（HTML 或 PDF）。
如果在防火墙后面部署应用程序，可能更希望所有执行器端点都能在不需要身份验证的情况下被访问。为此，您可以更改 management.endpoints.web.exposure.include 属性，如下所示：

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

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

import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration(proxyBeanMethods = false)
public class MySecurityConfiguration {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.securityMatcher(EndpointRequest.toAnyEndpoint());
        http.authorizeHttpRequests((requests) -> requests.anyRequest().permitAll());
        return http.build();
    }

}

在上述两个示例中，配置仅适用于执行器端点。由于在存在任何 SecurityFilterChain Bean 的情况下，Spring Boot 的安全配置都会完全关闭，因此您需要配置一个额外的 SecurityFilterChain Bean，其中包含适用于应用程序其余部分的规则。

跨域请求伪造保护

由于 Spring Boot 依赖 Spring Security 的默认设置，因此 CSRF 保护默认开启。这意味着在使用默认安全配置时，需要 POST（关机和日志记录端点）、PUT 或 DELETE 的执行器端点会出现 403（禁止）错误。

我们建议，只有在创建的服务被非浏览器客户端使用时，才完全禁用 CSRF 保护。

有关 CSRF 保护的更多信息，请参阅《Spring 安全参考指南》。

配置端点

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

management:
  endpoint:
    beans:
      cache:
        time-to-live: "10s"

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

敏感值脱敏

由 /env、/configprops 和 /quartz 端点返回的信息可能有些敏感。默认情况下，所有值都经过脱敏处理（即用 ****** 代替）。可以使用每个端点的 showValues 属性为该端点配置以未脱敏形式查看原始值。该属性可配置为以下值：

• ALWAYS - 所有值都以未经脱敏的形式显示给所有用户
• NEVER - 所有值始终经过脱敏处理（即用 ****** 代替）
• WHEN_AUTHORIZED - 所有值都以未经脱敏的形式显示给授权用户

对于 HTTP 端点，如果用户已通过身份验证并拥有端点的角色属性所配置的角色，则视为已获得授权。默认情况下，任何已通过身份验证的用户都已获得授权。对于 JMX 端点，所有用户始终都有授权。

management:
  endpoint:
    env:
      show-values: WHEN_AUTHORIZED
      roles: "admin"

通过上述配置，所有具有admin角色的用户都能从 /env 端点以原始形式查看所有值。

当 show-values 设置为 ALWAYS 或 WHEN_AUTHORIZED 时，仍会应用 SanitizingFunction 所应用的任何脱敏处理。

执行器网络终端的超媒体

添加一个 “discovery page”，其中包含所有端点的链接。默认情况下，“discovery page” 位于 /actuator。
要禁用 “discovery page”，请在应用程序属性中添加以下属性：

management:
  endpoints:
    web:
      discovery:
        enabled: false

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

CORS 支持

跨源资源共享（CORS）是一项W3C规范，它能让你以灵活的方式指定授权哪种跨域请求。如果使用 Spring MVC 或 Spring WebFlux，就可以配置 Actuator 的网络端点以支持此类场景。
CORS 支持默认是禁用的，只有设置了 management.endpoints.web.cors.allowed-origins 属性后才会启用。以下配置允许从 example.com 域进行 GET 和 POST 调用：

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

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

实现自定义端点

如果添加了注释为 @Endpoint 的 @Bean，那么注释为 @ReadOperation、@WriteOperation 或 @DeleteOperation 的任何方法都会自动通过 JMX 公开，在 Web 应用程序中还会通过 HTTP 公开。可以通过使用 Jersey、Spring MVC 或 Spring WebFlux 通过 HTTP 公开端点。如果 Jersey 和 Spring MVC 都可用，则使用 Spring MVC。
下面的示例公开了一个返回自定义对象的读操作：

@ReadOperation
public CustomData getData() {
    return new CustomData("test", 5);
}

您还可以使用 @JmxEndpoint 或 @WebEndpoint 编写特定技术的端点。这些端点仅限于各自的技术。例如，@WebEndpoint 只能通过 HTTP 而不是 JMX 暴露。
您可以使用 @EndpointWebExtension 和 @EndpointJmxExtension 编写特定技术的扩展。这些注解可让你提供特定于技术的操作，以增强现有的端点。
最后，如果需要访问特定于网络框架的功能，可以实现 servlet 或 Spring @Controller 和 @RestController 端点，但代价是这些端点不能通过 JMX 或使用不同的网络框架时可用。

接收输入

端点上的操作通过参数接收输入。通过网络公开时，这些参数的值取自 URL 的查询参数和 JSON 请求体。通过 JMX 公开时，参数会映射到 MBean 操作的参数。默认情况下，参数是必需的。通过使用 @javax.annotation.Nullable 或 @org.springframework.lang.Nullable 对参数进行注解，可将其设置为可选参数。
您可以将 JSON 请求正文中的每个根属性映射到端点参数。请看下面的 JSON 请求正文：

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

如下面的示例所示，你可以用它来调用一个包含String name和 int counter参数的写操作：

@WriteOperation
public void updateData(String name, int counter) {
    // injects "test" and 42
}

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

为了让输入映射到操作方法的参数，实现端点的 Java 代码在编译时应使用 -parameters，而实现端点的 Kotlin 代码在编译时应使用 -java-parameters。如果使用 Spring Boot 的 Gradle 插件，或使用 Maven 和 spring-boot-starter-parent，这将自动实现。

输入类型转换

必要时，传递给端点操作方法的参数会自动转换为所需类型。在调用操作方法之前，通过 JMX 或 HTTP 接收的输入会使用 ApplicationConversionService 的实例以及任何用 @EndpointConverter 限定的 Converter 或 GenericConverter Bean 转换为所需类型。

自定义 Web 端点

对 @Endpoint、@WebEndpoint 或 @EndpointWebExtension 的操作会自动使用 Jersey、Spring MVC 或 Spring WebFlux 通过 HTTP 公开。如果 Jersey 和 Spring MVC 都可用，则使用 Spring MVC。

Web 端点请求谓词

网络端点上的每个操作都会自动生成一个请求谓词。

predicate ：谓词，这里表判断的意思

路径

谓词的路径由端点的 ID 和网络暴露端点的基本路径决定。默认的基本路径是/actuator。例如，ID 为 sessions 的端点在谓词中使用 /actuator/sessions 作为路径。
通过使用 @Selector 对操作方法的一个或多个参数进行注解，可以进一步自定义路径。此类参数将作为路径变量添加到路径谓词中。在调用端点操作时，该变量的值将被传递到操作方法中。如果要捕获所有剩余的路径元素，可以在最后一个参数中添加 @Selector(Match=ALL_REMAINING)，并使其成为与 String[] 兼容的转换类型。

HTTP 方法

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

消耗

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

生产

谓词的 produces 子句可由 @DeleteOperation、@ReadOperation 和 @WriteOperation 注解的 produces 属性决定。该属性是可选的。如果不使用，produces 子句将自动确定。
如果操作方法返回 void 或 Void，则 produces 子句为空。如果操作方法返回 org.springframework.core.io.Resource，则 produces 子句为 application/octet-stream。对于所有其他操作，produces 子句为 application/vnd.spring-boot.actuator.v2+json、application/json。

Web 端点响应状态

端点操作的默认响应状态取决于操作类型（读取、写入或删除）和操作返回的内容（如果有的话）。
如果 @ReadOperation 返回一个值，响应状态将是 200（OK）。如果没有返回值，响应状态将是 404（未找到）。
如果 @WriteOperation 或 @DeleteOperation 返回值，响应状态将是 200（OK）。如果没有返回值，响应状态将是 204（无内容）。
如果调用的操作没有必填参数或参数无法转换为必填类型，则不会调用操作方法，响应状态将是 400（错误请求）。

Web 端点范围请求

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

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

Web 端点安全

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

Servlet 端点

通过实现一个同时实现 Supplier<EndpointServlet> 和注释 @ServletEndpoint 的类，可以将 Servlet 作为端点公开。Servlet 端点提供了与 Servlet 容器的深度集成，但却牺牲了可移植性。它们的目的是将现有的 servlet 作为端点公开。对于新端点，应尽可能使用 @Endpoint 和 @WebEndpoint 注解。

控制器端点

您可以使用 @ControllerEndpoint 和 @RestControllerEndpoint 来实现仅由 Spring MVC 或 Spring WebFlux 公开的端点。方法通过使用 Spring MVC 和 Spring WebFlux 的标准注解（如 @RequestMapping 和 @GetMapping）进行映射，端点的 ID 用作路径的前缀。控制器端点提供了与 Spring Web 框架的深度集成，但却牺牲了可移植性。在可能的情况下，应首选 @Endpoint 和 @WebEndpoint 注解。

健康信息

您可以使用健康信息来检查运行中应用程序的状态。当生产系统宕机时，监控软件通常会使用它来发出警报。健康状况端点显示的信息取决于 management.endpoint.health.show-details 和 management.endpoint.health.show-components 属性，这两个属性可配置为以下值之一：

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

如果您已确保应用程序的安全并希望always，您的安全配置必须允许通过身份验证和未通过身份验证的用户访问健康状况端点。

健康信息是从 HealthContributorRegistry（默认情况下是 ApplicationContext 中定义的所有 HealthContributor 实例）的内容中收集的。Spring Boot 包含大量自动配置的 HealthContributor，您也可以编写自己的 HealthContributor。
HealthContributor 可以是 HealthIndicator 或 CompositeHealthContributor。HealthIndicator 提供实际的健康信息，包括Status。CompositeHealthContributor提供其他HealthIndicator 的复合信息。这些贡献器共同组成了一个树形结构，用来表示整个系统的健康状况。
默认情况下，最终的系统健康状况是由 StatusAggregator 得出的，它会根据有序状态列表对每个 HealthIndicator 的状态进行排序。排序列表中的第一个状态被用作整体健康状态。如果没有 HealthIndicator 返回 StatusAggregator 所知道的状态，则使用UNKNOWN状态。

您可以使用 HealthContributorRegistry 在运行时注册或取消注册健康指标。

自动配置HealthIndicators

在适当的时候，Spring Boot 会自动配置下表列出的 HealthIndicators。您还可以通过配置 management.health.key.enabled 启用或禁用所选指标，键值如下表所列：

您可以通过设置 management.health.defaults.enabled 属性将其全部禁用。

其他HealthIndicators可用，但默认情况下不启用：

编写自定义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();
        if (errorCode != 0) {
            return Health.down().withDetail("Error Code", errorCode).build();
        }
        return Health.up().build();
    }

    private int check() {
        // perform some specific health check
        return ...
    }

}

给定 HealthIndicator 的标识符是 bean 的名称，不含 HealthIndicator 后缀（如果存在的话）。在上例中，健康信息存在于名为 my 的条目中。

健康指示器通常通过 HTTP 调用，需要在连接超时前做出响应。对于响应时间超过 10 秒的健康指示器，Spring Boot 会记录一条警告消息。如果要配置此阈值，可以使用 management.endpoint.health.logging.slow-indicator-threshold 属性。

除了 Spring Boot 预定义的 Status 类型外，Health 还可以返回代表新系统状态的自定义 Status。在这种情况下，您还需要提供 StatusAggregator 接口的自定义实现，或者必须使用 management.endpoint.health.status.order 配置属性来配置默认实现。
例如，假设在某个 HealthIndicator 实现中使用了代码为 FATAL 的新 Status。要配置严重性顺序，请在应用程序属性中添加以下属性：

management:
  endpoint:
    health:
      status:
        order: "fatal,down,out-of-service,unknown,up"

响应中的 HTTP 状态代码反映了整体健康状态。默认情况下，OUT_OF_SERVICE 和 DOWN 映射为 503。任何未映射的健康状态（包括 UP）都映射为 200。如果通过 HTTP 访问健康状况端点，可能还需要注册自定义状态映射。配置自定义映射会禁用 DOWN 和 OUT_OF_SERVICE 的默认映射。如果要保留默认映射，必须显式配置它们以及任何自定义映射。例如，以下属性将 FATAL 映射为 503（服务不可用），并保留了 DOWN 和 OUT_OF_SERVICE 的默认映射：

management:
  endpoint:
    health:
      status:
        http-mapping:
          down: 503
          fatal: 503
          out-of-service: 503

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

下表列出了内置状态的默认状态映射：

反应式健康指标

对于反应式应用程序（如使用 Spring WebFlux 的应用程序），ReactiveHealthContributor 提供了获取应用程序健康状况的非阻塞合约。与传统的 HealthContributor 类似，健康信息也是从 ReactiveHealthContributorRegistry（默认情况下是 ApplicationContext 中定义的所有 HealthContributor 和 ReactiveHealthContributor 实例）的内容中收集的。不检查反应式 API 的常规 HealthContributor 会在弹性调度程序上执行。

在反应式应用程序中，应使用 ReactiveHealthContributorRegistry 在运行时注册和取消注册健康指标。如果需要注册普通的 HealthContributor，则应使用 ReactiveHealthContributor#adapt 对其进行封装。

要通过反应式 API 提供自定义健康信息，可以注册实现 ReactiveHealthIndicator 接口的 Spring Bean。下面的代码展示了一个 ReactiveHealthIndicator 实现示例：

import reactor.core.publisher.Mono;

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.ReactiveHealthIndicator;
import org.springframework.stereotype.Component;

@Component
public class MyReactiveHealthIndicator implements ReactiveHealthIndicator {

    @Override
    public Mono<Health> health() {
        return doHealthCheck().onErrorResume((exception) ->
            Mono.just(new Health.Builder().down(exception).build()));
    }

    private Mono<Health> doHealthCheck() {
        // perform some specific health check
        return ...
    }

}

要自动处理错误，可以考虑从 AbstractReactiveHealthIndicator 扩展。

自动配置ReactiveHealthIndicators

在适当的时候，Spring Boot 会自动配置以下 ReactiveHealthIndicators：

如有必要，反应式指示器会取代常规指示器。此外，任何未明确处理的 HealthIndicator 都会被自动封装。

健康小组

有时，将健康指标组织成可用于不同目的的组非常有用。
要创建健康指标组，可以使用 management.endpoint.health.group.<name> 属性，并指定要包括或排除的健康指标 ID 列表。例如，要创建一个只包括数据库指标的组，可以定义如下：

management:
  endpoint:
    health:
      group:
        custom:
          include: "db"

然后点击 localhost:8080/actuator/health/custom 查看结果。
同样，如果要创建一个组，将数据库指标排除在组之外，而将所有其他指标包括在内，可以定义如下：

management:
  endpoint:
    health:
      group:
        custom:
          exclude: "db"

默认情况下，如果健康组包含或排除了不存在的健康指示符，启动将失败。要禁用此行为，请将 management.endpoint.health.validate-group-membership 设置为 false。
默认情况下，组继承与系统健康状况相同的 StatusAggregator 和 HttpCodeStatusMapper 设置。不过，您也可以按组定义这些设置。如果需要，还可以覆盖show-details和roles属性：

management:
  endpoint:
    health:
      group:
        custom:
          show-details: "when-authorized"
          roles: "admin"
          status:
            order: "fatal,up"
            http-mapping:
              fatal: 500
              out-of-service: 500

如果您需要注册自定义的 StatusAggregator 或 HttpCodeStatusMapper Bean 以用于组，可以使用 @Qualifier("groupname")。

健康组也可以包含/排除CompositeHealthContributor。您也可以只包含/排除 CompositeHealthContributor 的某个组件。可以使用组件的全限定名称来实现，如下所示：

management.endpoint.health.group.custom.include="test/primary"
management.endpoint.health.group.custom.exclude="test/primary/b"

在上面的示例中，自定义组将包括名称为 primary 的 HealthContributor，它是复合测试的一个组件。在这里，primary 本身就是复合测试，名称为 b 的 HealthContributor 将被排除在自定义组之外。
健康组可以在主端口或管理端口的附加路径上提供。这在 Kubernetes 等云环境中非常有用，在这些环境中，为了安全起见，通常会为执行器端点使用单独的管理端口。使用单独的端口可能会导致不可靠的健康检查，因为即使健康检查成功，主应用程序也可能无法正常工作。健康组可以通过以下额外路径进行配置：

management.endpoint.health.group.live.additional-path="server:/healthz"

这样，live健康组就可以在 /healthz 的主服务器端口上使用。前缀必须是 server:（表示主服务器端口）或 management:（表示管理端口，如果已配置）。

数据源健康

数据源健康状况指标显示标准数据源和路由数据源 Bean 的健康状况。路由数据源的健康状况包括其每个目标数据源的健康状况。在健康状况端点的响应中，路由数据源的每个目标都使用其路由键命名。如果不希望在指标输出中包含路由数据源，请将 management.health.db.ignore-routing-data-sources 设置为 true。

Kubernetes 探针

部署在 Kubernetes 上的应用程序可以通过容器探针（Container Probes）提供有关其内部状态的信息。根据 Kubernetes 的配置，kubelet 会调用这些探针并对结果做出反应。
默认情况下，Spring Boot 会管理应用程序可用性状态。如果部署在 Kubernetes 环境中，actuator 会从 ApplicationAvailability 接口收集 “Liveness” 和 “Readiness” 信息，并在专用的健康指示器中使用这些信息： LivenessStateHealthIndicator 和 ReadinessStateHealthIndicator。这些指标显示在全局健康状况端点（"/actuator/health"）上。它们还可以通过使用健康组作为单独的 HTTP 探测器显示： "/actuator/health/liveness" 和 "/actuator/health/readiness"。
然后，您可以使用以下端点信息配置 Kubernetes 基础设施：

livenessProbe:
  httpGet:
    path: "/actuator/health/liveness"
    port: <actuator-port>
  failureThreshold: ...
  periodSeconds: ...

readinessProbe:
  httpGet:
    path: "/actuator/health/readiness"
    port: <actuator-port>
  failureThreshold: ...
  periodSeconds: ...

<actuator-port>（执行器端口）应设置为执行器端点可用的端口。如果设置了 "management.server.port"（管理服务器端口）属性，则可以是主网络服务器端口或单独的管理端口。

只有当应用程序在 Kubernetes 环境中运行时，这些健康组才会自动启用。您可以使用 management.endpoint.health.probes.enabled 配置属性在任何环境中启用它们。

如果应用程序的启动时间超过了配置的有效期，Kubernetes 会将 "startupProbe" 作为一种可能的解决方案。一般来说，这里并不一定需要 "startupProbe"，因为在所有启动任务完成之前，"readinessProbe" 都会失败。这意味着您的应用程序在准备就绪之前不会接收流量。不过，如果您的应用程序需要很长时间才能启动，可以考虑使用 "startupProbe" 来确保 Kubernetes 不会在您的应用程序启动过程中杀死它。请参阅 “探针在应用程序生命周期中的行为” 部分。

如果 Actuator 端点部署在单独的管理上下文中，则端点不会使用与主应用程序相同的网络基础结构（端口、连接池、框架组件）。在这种情况下，即使主应用程序无法正常工作（例如，无法接受新连接），探测检查也可能成功。因此，最好在主服务器端口上提供liveness和readiness状态组。这可以通过设置以下属性来实现：

management.endpoint.health.probes.add-additional-paths=true

这样，主服务器端口上的/livez 和/readyz 就可以分别使用liveness组和readiness组。可以使用每个组的 additional-path 属性自定义路径，详情请参阅健康组。

利用 Kubernetes 探测器检查外部状态

Actuator 将 “liveness” 和 “readiness” 探测器配置为健康组。这意味着它们可以使用健康组的所有功能。例如，您可以配置额外的健康指标：

management:
  endpoint:
    health:
      group:
        readiness:
          include: "readinessState,customCheck"

默认情况下，Spring Boot 不会向这些组添加其他健康指标。
“liveness”探针不应依赖外部系统的健康检查。如果应用程序的有效性状态被破坏，Kubernetes 会尝试通过重启应用程序实例来解决问题。这意味着，如果外部系统（如数据库、Web API 或外部缓存）发生故障，Kubernetes 可能会重启所有应用实例，并造成级联故障。
至于 “readiness” 探针，应用程序开发人员必须谨慎选择检查外部系统。因此，Spring Boot 在 “readiness” 探针中不包含任何额外的健康检查。如果应用程序实例的就绪状态为 “未就绪”，Kubernetes 不会将流量路由到该实例。有些外部系统可能不被应用实例共享，在这种情况下，它们可以被包含在就绪状态探查中。其他外部系统可能对应用并不重要（应用可能有断路器和回退），在这种情况下，它们肯定不应该被包括在内。不幸的是，所有应用程序实例共享的外部系统很常见，因此必须做出判断： 是将其包含在就绪探测器中，并期望在外部服务宕机时应用程序停止服务，还是不将其包含在内，而是通过在调用程序中使用断路器来处理堆栈上层的故障。

如果应用程序的所有实例都未就绪，则 type=ClusterIP 或 NodePort 的 Kubernetes 服务不会接受任何传入连接。由于没有连接，所以不会有 HTTP 错误响应（503 等）。type=LoadBalancer 的服务可能接受也可能不接受连接，具体取决于提供商。有明确入口的服务的响应方式也取决于实现–入口服务本身必须决定如何处理来自下游的 “连接被拒绝”。在负载平衡器和入口的情况下，都很可能出现 HTTP 503。

此外，如果应用程序使用 Kubernetes 自动扩展，它可能会对从负载平衡器中取出的应用程序做出不同的反应，具体取决于其自动扩展器配置。

应用程序生命周期和探针状态

Kubernetes 探针支持的一个重要方面是它与应用程序生命周期的一致性。AvailabilityState（应用程序的内存内部状态）与实际探针（暴露该状态）之间存在显著差异。根据应用程序生命周期的不同阶段，探针可能不可用。
Spring Boot 会在启动和关闭期间发布应用程序事件，探针可以监听此类事件并公开 AvailabilityState 信息。
下表显示了不同阶段的 AvailabilityState 和 HTTP 连接器状态。
Spring Boot 应用程序启动时：

Spring Boot 应用程序关闭时：

有关 Kubernetes 部署的更多信息，请参阅 Kubernetes 容器生命周期部分。

应用信息

应用程序信息会公开从 ApplicationContext 中定义的所有 InfoContributor Bean 收集到的各种信息。Spring Boot 包含大量自动配置的 InfoContributor Bean，您也可以编写自己的 InfoContributor Bean。

自动配置InfoContributors

在适当的时候，Spring 会自动配置以下 InfoContributor Bean：

单个贡献者是否启用由其 management.info.<id>.enabled 属性控制。不同的贡献者有不同的默认值，这取决于它们的先决条件和所暴露信息的性质。
由于没有先决条件表明它们应该被启用，因此 env、java 和 os 贡献者默认为禁用。可通过将其 management.info.<id>.enabled 属性设置为 true 来启用它们。
build和 git info 贡献者默认为启用。可通过将其 management.info.<id>.enabled 属性设置为 false 来禁用。或者，要禁用通常默认启用的每个贡献器，可将 management.info.defaults.enabled 属性设置为 false。

自定义应用信息

启用 env 贡献者后，你可以通过设置 info.* Spring 属性来定制 info 端点暴露的数据。info.* 键下的所有环境属性都会自动公开。例如，你可以在 application.properties 文件中添加以下设置：

info:
  app:
    encoding: "UTF-8"
    java:
      source: "17"
      target: "17"

除了硬编码这些值之外，还可以在构建时扩展 info 属性。
假设你使用 Maven，你可以将前面的示例重写如下：

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

Git 提交信息

info 端点的另一个有用功能是，它能发布项目构建时 git 源代码库的状态信息。如果有 GitProperties Bean，就可以使用 info 端点公开这些属性。

如果类路径根目录下有 git.properties 文件，GitProperties Bean 就会自动配置。详情请参阅 “如何生成 git 信息”。

默认情况下，端点会公开 git.branch、git.commit.id 和 git.commit.time 属性（如果存在）。如果不想在端点响应中显示这些属性，就需要在 git.properties 文件中排除它们。如果要显示完整的 git 信息（即 git.properties 的全部内容），请使用 management.info.git.mode 属性，如下所示：

management:
  info:
    git:
      mode: "full"

要完全禁用 info 端点的 git 提交信息，请将 management.info.git.enabled 属性设置为 false，如下所示：

management:
  info:
    git:
      enabled: false

构建信息

如果 BuildProperties Bean 可用，info 端点也可以发布有关构建的信息。如果类路径中存在 META-INF/build-info.properties 文件，就会出现这种情况。

Maven 和 Gradle 插件都能生成该文件。详情请参阅 “如何生成构建信息”。

Java 信息

info 端点会发布有关 Java 运行环境的信息，详情请参阅 JavaInfo。

OS 信息

info 端点发布有关操作系统的信息，详情请查看 OsInfo。

编写自定义InfoContributors

要提供自定义应用程序信息，可以注册实现 InfoContributor 接口的 Spring Bean。
下面的示例提供了一个具有单一值的example条目：

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 MyInfoContributor implements InfoContributor {

    @Override
    public void contribute(Info.Builder builder) {
        builder.withDetail("example", Collections.singletonMap("key", "value"));
    }

}

如果访问 info 端点，就会看到一个包含以下附加条目的响应：

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

通过 HTTP 进行监控和管理

如果您正在开发 Web 应用程序，Spring Boot Actuator 会自动配置所有启用的端点，使其通过 HTTP 暴露。默认的惯例是使用带有 /actuator 前缀的端点 id 作为 URL 路径。例如，health 显示为 /actuator/health。

Actuator 原生支持 Spring MVC、Spring WebFlux 和 Jersey。如果 Jersey 和 Spring MVC 都可用，则使用 Spring MVC。

Jackson 是获取 API 文档（HTML 或 PDF）中记录的正确 JSON 响应所必需的依赖项。

自定义管理端点路径

有时，自定义管理端点的前缀非常有用。例如，您的应用程序可能已将 /actuator 用于其他目的。您可以使用 management.endpoints.web.base-path 属性更改管理端点的前缀，如下例所示：

management:
  endpoints:
    web:
      base-path: "/manage"

前面的 application.properties 示例将端点从 /actuator/{id} 更改为 /manage/{id}（例如，/manage/info）。

除非管理端口已配置为通过使用不同的 HTTP 端口来暴露端点，否则 management.endpoints.web.base-path 将相对于 server.servlet.context-path（针对 servlet 网络应用程序）或 spring.webflux.base-path（针对反应式网络应用程序）。如果配置了 management.server.port，则 management.endpoints.web.base-path 会相对于 management.server.base-path。

如果要将端点映射到不同的路径，可以使用 management.endpoints.web.path-mapping 属性。
下面的示例将 /actuator/health 重映射为 /healthcheck：

management:
  endpoints:
    web:
      base-path: "/"
      path-mapping:
        health: "healthcheck"

自定义管理服务器端口

使用默认 HTTP 端口暴露管理端点是基于云的部署的明智选择。但如果你的应用程序在自己的数据中心内运行，你可能更愿意使用不同的 HTTP 端口来暴露端点。
您可以设置 management.server.port 属性来更改 HTTP 端口，如下例所示：

management:
  server:
    port: 8081

在 Cloud Foundry 上，默认情况下应用程序仅在 HTTP 和 TCP 路由的 8080 端口上接收请求。如果您想在 Cloud Foundry 上使用自定义管理端口，则需要显式设置应用程序的路由以将流量转发到自定义端口。

配置管理专用 SSL

当配置为使用自定义端口时，还可以通过使用各种 management.server.ssl.* 属性，为管理服务器配置自己的 SSL。例如，这样做可以让管理服务器通过 HTTP 提供服务，而主应用程序则使用 HTTPS，如下属性设置所示：

server:
  port: 8443
  ssl:
    enabled: true
    key-store: "classpath:store.jks"
    key-password: "secret"
management:
  server:
    port: 8080
    ssl:
      enabled: false

或者，主服务器和管理服务器都可以使用 SSL，但使用不同的密钥存储，如下所示：

server:
  port: 8443
  ssl:
    enabled: true
    key-store: "classpath:main.jks"
    key-password: "secret"
management:
  server:
    port: 8080
    ssl:
      enabled: true
      key-store: "classpath:management.jks"
      key-password: "secret"

自定义管理服务器地址

通过设置 management.server.address 属性，可以自定义管理端点可用的地址。如果你只想监听内部网络或面向操作的网络，或者只想监听来自 localhost 的连接，那么这样做会很有用。

只有当端口与主服务器端口不同时，才能监听不同的地址。

以下示例的 application.properties 不允许远程管理连接：

management:
  server:
    port: 8081
    address: "127.0.0.1"

禁用 HTTP 端点

如果不想通过 HTTP 公开端点，可以将管理端口设置为-1，如下例所示：

management:
  server:
    port: -1

您还可以使用 management.endpoints.web.exposure.exclude 属性来实现这一目的，如下例所示：

management:
  endpoints:
    web:
      exposure:
        exclude: "*"

通过 JMX 进行监控和管理

Java 管理扩展（JMX）提供了一种监控和管理应用程序的标准机制。默认情况下，此功能未启用。您可以通过将 spring.jmx.enabled 配置属性设置为 true 来开启该功能。Spring Boot 将最合适的 MBeanServer 公开为一个 ID 为 mbeanServer 的 Bean。您的任何带有 Spring JMX 注释（@ManagedResource、@ManagedAttribute 或 @ManagedOperation）的 Bean 都会暴露给它。
如果您的平台提供了标准 MBeanServer，Spring Boot 将使用该服务器，并在必要时默认使用 VM MBeanServer。如果所有方法都失败，则会创建一个新的 MBeanServer。
有关详细信息，请参阅 JmxAutoConfiguration 类。
默认情况下，Spring Boot 还会将管理端点作为 org.springframework.boot 域下的 JMX MBeans 公开。要完全控制 JMX 域中的端点注册，请考虑注册自己的 EndpointObjectNameFactory 实现。

自定义 MBean 名称

MBean 的名称通常由端点的 id 生成。例如，健康端点以 org.springframework.boot:type=Endpoint,name=Health 的形式公开。
如果您的应用程序包含多个 Spring ApplicationContext，您可能会发现名称冲突。要解决这个问题，可以将 spring.jmx.unique-names 属性设置为 true，这样 MBean 名称就总是唯一的了。
您还可以自定义端点暴露的 JMX 域。下面的设置展示了在 application.properties 中这样做的一个示例：

spring:
  jmx:
    unique-names: true
management:
  endpoints:
    jmx:
      domain: "com.example.myapp"

禁用 JMX 端点

如果不想通过 JMX 暴露端点，可以将 management.endpoints.jmx.exposure.exclude 属性设置为 *，如下例所示：

management:
  endpoints:
    jmx:
      exposure:
        exclude: "*"

可观察性（Observability）

可观察性是指从外部观察运行系统内部状态的能力。它由日志、度量和跟踪三大支柱组成。
对于度量和跟踪，Spring Boot 使用 Micrometer Observation。要创建自己的观察结果（这将导致度量和跟踪），您可以注入一个 ObservationRegistry。

import io.micrometer.observation.Observation;
import io.micrometer.observation.ObservationRegistry;

import org.springframework.stereotype.Component;

@Component
public class MyCustomObservation {

    private final ObservationRegistry observationRegistry;

    public MyCustomObservation(ObservationRegistry observationRegistry) {
        this.observationRegistry = observationRegistry;
    }

    public void doSomething() {
        Observation.createNotStarted("doSomething", this.observationRegistry)
            .lowCardinalityKeyValue("locale", "en-US")
            .highCardinalityKeyValue("userId", "42")
            .observe(() -> {
                // Execute business logic here
            });
    }

}

卡入度低（Low cardinality）的键值将被添加到度量和轨迹中，而卡入度高（high cardinality）的键值只会被添加到轨迹中。

ObservationPredicate、GlobalObservationConvention、ObservationFilter 和 ObservationHandler 类型的 Bean 将自动在 ObservationRegistry 上注册。此外，您还可以注册任意数量的 ObservationRegistryCustomizer Bean 来进一步配置注册表。
可观察性支持依赖于上下文传播库，以跨线程和反应管道转发当前观察结果。默认情况下，线程本地值不会在反应式操作符中自动恢复。这一行为由 spring.reactor.context-propagation 属性控制，可将其设置为 auto 以启用自动传播。
有关观察的更多详情，请参阅 Micrometer Observation 文档。

JDBC 的可观察性可以使用单独的项目进行配置。Datasource Micrometer 项目提供了一个 Spring Boot 启动器，可在调用 JDBC 操作时自动创建观察结果。有关详细信息，请参阅参考文档。

Spring Boot 内置了 R2DBC 的可观察性。要启用它，请在项目中添加 io.r2dbc:r2dbc-proxy 依赖关系。

通用键值

通用键值通常用于对运行环境进行维度钻取，如主机、实例、区域、堆栈等。通用键值作为低卡片性键值应用于所有观测值，并可进行配置，如下例所示：

management:
  observations:
    key-values:
      region: "us-east-1"
      stack: "prod"

上例为所有值分别为 us-east-1 和 prod 的观测值添加了region和stack键值。

防止观察

如果想阻止某些观察结果被报告，可以使用 management.observations.enable 属性：

management:
  observations:
    enable:
      denied:
        prefix: false
      another:
        denied:
          prefix: false

上例将阻止所有名称以 denied.prefix 或 another.denied.prefix 开头的观察结果。

如果要阻止 Spring Security 报告观察结果，请将 management.observations.enable.spring.security 属性设置为 false。

如果需要对观察结果的预防进行更多控制，可以注册 ObservationPredicate 类型的 Bean。只有当所有 ObservationPredicate Bean 都对该观察结果返回 true 时，才会报告该观察结果。

import io.micrometer.observation.Observation.Context;
import io.micrometer.observation.ObservationPredicate;

import org.springframework.stereotype.Component;

@Component
class MyObservationPredicate implements ObservationPredicate {

    @Override
    public boolean test(String name, Context context) {
        return !name.contains("denied");
    }

}

上例将阻止所有名称包含 “denied” 的观察结果。

OpenTelemetry 支持

Spring Boot 的执行器模块包含对 OpenTelemetry 的基本支持。
它提供了 OpenTelemetry 类型的 Bean，如果应用程序上下文中有 SdkTracerProvider、ContextPropagators、SdkLoggerProvider 或 SdkMeterProvider 类型的 Bean，它们会自动注册。此外，它还提供了一个Resource bean。Resource的属性可通过 management.opentelemetry.resource-attributes 配置属性进行配置。

Spring Boot 不为 OpenTelemetry 指标或日志提供自动配置。OpenTelemetry 跟踪只有在与 Micrometer 跟踪一起使用时才会自动配置。

接下来的章节将详细介绍日志、度量和跟踪。

Loggers

Spring Boot Actuator 具有在运行时查看和配置应用程序日志级别的功能。您既可以查看整个列表，也可以查看单个日志记录器的配置，其中既包括显式配置的日志记录级别，也包括日志记录框架赋予它的有效日志记录级别。这些级别可以是：

• TRACE
• DEBUG
• INFO
• WARN
• ERROR
• FATAL
• OFF
• null

null 表示没有明确的配置。

配置Logger

要配置给定的logger，请向资源的 URI 发送部分实体，如下例所示：

{
    "configuredLevel": "DEBUG"
}

要 “reset” 日志记录器的特定级别（并使用默认配置），可将 configuredLevel 设为null值。文章来源地址https://www.toymoban.com/news/detail-819417.html

到了这里，关于Spring Boot 生产就绪中文文档-上的文章就介绍完了。如果您还想了解更多内容，请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章，希望大家以后多多支持TOY模板网！