Endpoints

由于 Spring Boot 依赖于 Spring Security 的默认设置，因此 CSRF 保护默认启用。这意味着，在使用默认安全配置时，需要 @XXX (关闭和记录器端点)、@YYY 或 @ZZZ 的 actuator 端点会收到 403（禁止）错误。

你可以在 Spring Security 参考指南中找到有关 CSRF 保护的更多信息：{url-spring-security-docs}/features/exploits/csrf.html。

端点上的操作通过其参数接收输入。当通过 Web 公开时，这些参数的值取自 URL 的查询参数和 JSON 请求正文。当通过 JMX 公开时，参数映射到 MBean 的操作参数。默认情况下，参数是必需的。通过使用 @javax.annotation.Nullable 或 @org.springframework.lang.Nullable 注释它们，可以使它们变为可选的。

您可以将 JSON 请求正文中的每个根属性映射到端点的参数。请考虑以下 JSON 请求正文：

您可以使用此文档调用一个写入操作，它采用 String name 和 int counter 参数，如下例所示：

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

可以通过实现同时实现 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 注释。

如合适，Spring Boot 会自动配置下表中列出的 HealthIndicators。你还可以通过使用下表中列出的 key 配置 management.health.key.enabled，从而启用或禁用选定的指标：

其他 HealthIndicators 是可用的，但默认情况下未启用：

要提供自定义健康信息，可以注册实现 {code-spring-boot-actuator-src}/health/HealthIndicator.java[HealthIndicator] 接口的 Spring bean。您需要提供 health() 方法的实现并返回 Health 响应。Health 响应应包括一个状态，并且可以包含可选的要显示的附加详细信息。以下代码显示一个 HealthIndicator 实现示例：

除了 Spring Boot 预定义的 {code-spring-boot-actuator-src}/health/Status.java[Status] 类型，Health 还可以返回表示新系统状态的自定义 Status。在这种情况下，还需要提供 {code-spring-boot-actuator-src}/health/StatusAggregator.java[StatusAggregator] 接口的自定义实现，或者必须使用 configprop:management.endpoint.health.status.order[] 配置属性来配置默认实现。

例如，假设一个新的 Status 在您的其中一个 HealthIndicator 实现中使用，其代码为 FATAL。要配置严重性顺序，请将以下属性添加到您的应用程序属性：

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

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

对于响应应用程序，例如使用 Spring WebFlux 的应用程序，ReactiveHealthContributor 提供了一个非阻塞合约来获取应用程序的健康状况。类似于传统 HealthContributor，健康信息是从 {code-spring-boot-actuator-src}/health/ReactiveHealthContributorRegistry.java[ReactiveHealthContributorRegistry] （默认情况下，所有 {code-spring-boot-actuator-src}/health/HealthContributor.java[HealthContributor] 和 {code-spring-boot-actuator-src}/health/ReactiveHealthContributor.java[ReactiveHealthContributor] 实例均在您的 ApplicationContext 中定义）的内容中收集的。针对非响应式 API 进行检查的常规 HealthContributors 在弹性调度程序上执行。

要从反应式 API 提供自定义健康信息，你可以注册实现 {code-spring-boot-actuator-src}/health/ReactiveHealthIndicator.java[ReactiveHealthIndicator] 接口的 Spring bean。下面的代码展示了一个示例 ReactiveHealthIndicator 实现：

当合适时，Spring Boot 会自动配置以下 ReactiveHealthIndicators：

有时候，将健康指标整理成可用于不同用途的分组很有用。

要创建一个健康指标分组，你可以使用 management.endpoint.health.group.<name> 属性，并为 include 或 exclude 指定一个健康指标 ID 列表。例如，为了创建一个仅包含数据库指标的分组，你可以定义以下内容：

然后，你可以通过点击 http://localhost:8080/actuator/health/custom 来查看结果。

类似地，为了创建一个将数据库指标从分组中排除、同时包含所有其他指标的分组，你可以定义以下内容：

默认情况下，如果一个健康分组包含或排除了不存在的健康指标，启动将会失败。要禁用此行为，将 configprop:management.endpoint.health.validate-group-membership[] 设置为 false。

默认情况下，组会继承与系统健康相同的 StatusAggregator 和 HttpCodeStatusMapper 设置。不过，你也可以在组级别上定义这些设置。你还可以根据需要覆盖 show-details 和 roles 属性：

一个健康分组还可以包含/排除一个 CompositeHealthContributor。你还可以仅包含/排除 CompositeHealthContributor 的某个组件。这可以通过使用组件的全限定名称来实现，如下所示：

在上述示例中，custom 分组将包含名称为 primary 的 HealthContributor，它是一个复合 test 的组件。这里，primary 本身是一个复合体，并且名称为 b 的 HealthContributor 将从 custom 组中排除。

健康组可以使用主端口或管理端口上的额外路径。这在云环境中很有用，例如 Kubernetes，其中出于安全目的，通常为执行器端点使用单独的管理端口。由于主应用程序即使健康检查成功，也可能无法正常工作，拥有一个单独的端口可能会导致不可靠的健康检查。健康组可以通过以下方式配置额外路径：

这将使 live 健康组在 /healthz 处的主服务器端口上可用。前缀是必需的，它必须是 server:（代表主服务器端口）或 management:（代表管理端口（如果已配置））中的一个。路径必须是一个单一的路径部分。

DataSource 健康指标展示了标准数据源和路由数据源 bean 的运行状况。路由数据源的运行状况包括其每个目标数据源的运行状况。在健康端点的响应中，每个路由数据源的目标都通过使用其路由键来命名。如果你不希望在指标输出中包含路由数据源，请将 configprop:management.health.db.ignore-routing-data-sources[] 设置为 true。

执行器将 “liveness” 和 “readiness” 探测配置为健康组。这意味着所有的 health groups features 都对它们可用。例如，你可以配置其他健康指标：

默认情况下，Spring Boot 不会将其他健康指标添加到这些组中。

“liveness” 探测不应依赖于外部系统的运行状况检查。如果 liveness state of an application 已中断，Kubernetes 会通过重新启动应用程序实例来尝试解决该问题。这意味着，如果外部系统（例如数据库、Web API 或外部缓存）发生故障，Kubernetes 可能会重新启动所有应用程序实例并创建级联故障。

至于 “readiness” 探测，检查外部系统的选择必须由应用程序开发人员仔细做出。因此，Spring Boot 不会在准备就绪探测中包括任何其他运行状况检查。如果 readiness state of an application instance 未准备好，Kubernetes 不会将流量路由到该实例。某些外部系统可能不会被应用程序实例共享，在这种情况下，它们可以包含在准备就绪探测中。其他外部系统可能对应用程序不必要（应用程序可能有断路器和后备选项），在这种情况下，绝对不应包含这些外部系统。不幸的是，所有应用程序实例共享的外部系统很常见，你必须做出判断：将其包含在准备就绪探测中并希望在外部服务关闭时将应用程序排除在外或将其排除在外并处理堆栈中更高的故障，也许通过在调用方中使用断路器。

此外，如果应用程序使用 Kubernetes autoscaling，它对从负载平衡器中移除应用程序的反应可能不同，具体取决于其自动伸缩器配置。

Kubernetes 探测支持的一个重要方面是它与应用程序生命周期的协调一致。AvailabilityState （也就是应用程序的内存内部状态）与实际探测（公开该状态）之间有显着差别。根据应用程序生命周期的阶段，该探测可能不可用。

Spring Boot 会发布 application events during startup and shutdown，并且探测可以监听此类事件并公开 AvailabilityState 信息。

下表显示了 AvailabilityState 和 HTTP 连接器在不同阶段的状态。

Spring Boot 应用程序启动时：

Spring Boot 应用程序关闭时：

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

单独分发者的启用与否由其 management.info.<id>.enabled 属性控制。不同的分发者对此属性有不同的默认值，具体取决于其前提条件和它们公开信息的性质。

如果没有前置条件表明应启用它们，env、java、os 和 process 分发者默认情况下处于禁用状态。可通过将 management.info.<id>.enabled 属性设置为 true 来启用每个分发者。

build 和 git 信息分发者默认情况下处于启用状态。可通过将 management.info.<id>.enabled 属性设置为 false 来禁用每个分发者。或者，要禁用通常默认启用的所有分发者，将 configprop:management.info.defaults.enabled[] 属性设置为 false。

当 env 分发者启用时，您可以通过设置 info.* Spring 属性来定制 info 终端公开的数据。所有 info 键下的 Environment 属性会自动公开。例如，您可以添加以下设置到 application.properties 文件：

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

默认情况下，此终端公开 git.branch、git.commit.id 和 git.commit.time 属性（如果存在）。如果您不希望在终端响应中出现任何这些属性，则需要从 git.properties 文件中排除这些属性。如果您想显示全部 git 信息（即 git.properties 的全部内容），请使用 configprop:management.info.git.mode[] 属性，如下所示：

要从 info 终端中完全禁用 git 提交信息，请将 configprop:management.info.git.enabled[] 属性设置为 false，如下所示：

如果 BuildProperties bean 可用，info 端点还可以发布有关你的构建的信息，只要 classpath 中提供 META-INF/build-info.properties 文件，情况即是如此。

info 端点发布有关你的 Java 运行时环境的信息，有关更多详细信息，请参阅 JavaInfo。

info 端点发布有关你的操作系统的的信息，有关更多详细信息，请参阅 OsInfo。

info 端点发布有关你的进程的信息，有关更多详细信息，请参阅 ProcessInfo。

若要提供自定义应用程序信息，可以注册实现 {code-spring-boot-actuator-src}/info/InfoContributor.java[InfoContributor] 界面的 Spring bean。

以下示例包含一个具有单个值的 example 条目：

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