Spring 官网翻译 Production-ready Features 篇

一、参考资料

https://docs.spring.io/spring-boot/reference/actuator/index.html

Spring 中文网，直接看这个网站吧

https://www.spring-doc.cn/spring-boot/4.0.4/reference_actuator_endpoints.html

二、笔记总结

Production-ready Features

生产就需功能
Spring Boot 包含多项附加功能，帮助你在将应用部署到生产环境后对其进行监控和管理。你可以选择通过 HTTP 端点或 JMX 来管理并监控应用。审计、健康检查和指标收集等功能也可以自动应用于你的应用。

Enabling Production-ready Features

启用生产就需功能
spring-boot-actuator 模块提供了 Spring Boot 的所有生产就绪功能。启用这些功能的推荐方式是添加对 spring-boot-starter-actuator 启动器的依赖。
要将 actuator 添加到基于Maven的项目中，请添加以下启动依赖项：

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

Endpoints

端点
Actuator endpoints 使您能够监控和与应用程序进行交互。Spring Boot 包含多个内置端点，并允许您添加自定义端点。例如，健康检查端点提供基本的应用程序健康信息。
您可以控制对每个端点的访问权限，并通过HTTP或JMX将其暴露（使其可远程访问）。当允许访问且已暴露时，端点被视为可用。内置端点仅在可用时才会自动配置。大多数应用程序选择通过HTTP进行暴露，其中端点ID和/actuator前缀映射到URL。例如，默认情况下，健康检查端点映射到/actuator/health。
以下是一些与技术无关的端点：

如果你的应用是 Web 应用（比如 Spring MVC、Spring WebFlux 或 Jersey），你还可以使用以下额外的端点（endpoints）。

Controlling Access to Endpoints

控制对端点的访问
默认情况下，除 shutdown 和 heapdump 之外的所有端点访问均不受限制。若要配置某个端点的允许访问权限，请使用其 management.endpoint…access 属性。以下示例允许对 shutdown 端点进行无限制访问：

management:endpoint:shutdown:access:unrestricted

如果你希望采用“白名单”机制（即默认关闭，需要手动开启），而不是“黑名单”机制（默认开启，手动关闭），可以将 management.endpoints.access.default 属性设置为 none，然后通过单独配置各个端点的访问属性来按需开启。
比如下面这个配置示例，就只允许对 loggers 端点进行只读访问，同时拒绝访问所有其他端点。

management:endpoints:access:default:noneendpoint:loggers:access:read-only

被禁止访问的端点会直接从应用上下文中彻底移除。如果你只是想调整端点通过哪些技术（比如 HTTP 或 JMX）对外暴露，请使用 include 和 exclude 属性来进行配置。

Limiting Access

限制访问
你可以通过 management.endpoints.access.max-permitted 属性来限制整个应用范围内所有端点的访问权限。这个属性的优先级最高，它会覆盖默认访问设置以及各个端点单独配置的访问级别。
如果将其设置为 none，所有端点都将无法访问；如果设置为 read-only，则只允许对端点进行只读访问。
对于 @Endpoint、@JmxEndpoint 和 @WebEndpoint，读取访问权限等同于访问那些标注了 @ReadOperation 的端点方法。
对于 @ControllerEndpoint 和 @RestControllerEndpoint，读取访问权限等同于能够处理 GET 和 HEAD 请求的请求映射（request mappings）。
对于 @ServletEndpoint，读取访问权限等同于允许 GET 和 HEAD 请求。

Exposing Endpoints

暴露端点
默认情况下，只有 health（健康状态）端点会通过 HTTP 和 JMX 对外暴露。由于端点可能包含敏感信息，你应该在暴露端点时仔细考量。要更改哪些端点被暴露，请使用以下特定于技术的 include（包含）和 exclude（排除）属性：

include 属性列出了被暴露的端点的 ID。exclude 属性列出了不应被暴露的端点的 ID。exclude 属性优先于 include 属性。您可以使用端点 ID 列表来同时配置 include 和 exclude 属性。
例如，如果只想通过 JMX 暴露 health 和 info 端点，请使用以下属性：

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

可以使用 * 来选择所有端点。例如，如果希望通过 HTTP 暴露除 env 和 beans 端点之外的所有内容，请使用以下属性：

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

* 在 YAML 中有特殊含义，因此如果您想包含（或排除）所有端点，请务必加上引号。
如果您的应用对外公开，我们强烈建议您同时也对端点进行安全加固。
如果您想实现自己的端点暴露策略，可以注册一个 EndpointFilter bean。

Security

出于安全考虑，默认情况下仅通过 HTTP 暴露 /health 端点。您可以使用 management.endpoints.web.exposure.include 属性来配置要暴露的端点。
在设置 management.endpoints.web.exposure.include 之前，请确保暴露的 Actuator 不包含敏感信息，或者通过将其置于防火墙之后或使用类似 Spring Security 的东西来确保其安全。
如果类路径中存在 Spring Security，且没有其他 SecurityFilterChain bean，则除 /health 之外的所有 Actuator 都由 Spring Boot 自动配置进行保护。如果您定义了自定义的 SecurityFilterChain bean，Spring Boot 自动配置将退避，让您完全控制 Actuator 的访问规则。
如果您希望为 HTTP 端点配置自定义安全性（例如，仅允许具有特定角色的用户访问），Spring Boot 提供了一些便捷的 RequestMatcher 对象，您可以将其与 Spring Security 结合使用。
典型的 Spring Security 配置可能如下例所示：

importorg.springframework.boot.security.autoconfigure.actuate.web.servlet.EndpointRequest;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;importorg.springframework.security.config.annotation.web.builders.HttpSecurity;importorg.springframework.security.web.SecurityFilterChain;importstaticorg.springframework.security.config.Customizer.withDefaults;@Configuration(proxyBeanMethods=false)publicclassMySecurityConfiguration{@BeanpublicSecurityFilterChainsecurityFilterChain(HttpSecurityhttp){http.securityMatcher(EndpointRequest.toAnyEndpoint());http.authorizeHttpRequests((requests)->requests.anyRequest().hasRole("ENDPOINT_ADMIN"));http.httpBasic(withDefaults());returnhttp.build();}}

上述示例使用 EndpointRequest.toAnyEndpoint() 来匹配对任意端点的请求，然后确保所有请求都具备 ENDPOINT_ADMIN 角色。EndpointRequest 还提供了其他几种匹配器方法。有关详细信息，请参阅 API 文档。
在匹配 Actuator 端点时，EndpointRequest.to(“endpoint”) 会考虑端点根路径及其所有子路径，即使该端点没有声明嵌套路由，也能有效匹配 “/actuator/endpoint/**”。
如果您将应用程序部署在防火墙之后，您可能希望所有 Actuator 端点都可以在无需身份验证的情况下进行访问。您可以通过更改 management.endpoints.web.exposure.include 属性来实现这一点，如下所示：

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

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

importorg.springframework.boot.security.autoconfigure.actuate.web.servlet.EndpointRequest;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;importorg.springframework.security.config.annotation.web.builders.HttpSecurity;importorg.springframework.security.web.SecurityFilterChain;@Configuration(proxyBeanMethods=false)publicclassMySecurityConfiguration{@BeanpublicSecurityFilterChainsecurityFilterChain(HttpSecurityhttp){http.securityMatcher(EndpointRequest.toAnyEndpoint());http.authorizeHttpRequests((requests)->requests.anyRequest().permitAll());returnhttp.build();}}

在上述两个示例中，该配置仅适用于 Actuator 端点。由于当存在任何 SecurityFilterChain bean 时，Spring Boot 的安全配置会完全退避，因此您需要配置一个额外的 SecurityFilterChain bean，并为其设置适用于应用程序其余部分的规则。

Cross Site Request Forgery Protection

跨站请求伪造（CSRF）防护
由于 Spring Boot 依赖于 Spring Security 的默认设置，因此默认情况下会启用 CSRF 保护。这意味着，当使用默认的安全配置时，需要 POST（shutdown 和 loggers 端点）、PUT 或 DELETE 的 Actuator 端点将返回 403（禁止）错误。
我们建议，只有在创建供非浏览器客户端使用的服务时，才完全禁用 CSRF 保护。
您可以在 Spring Security 参考指南中找到有关 CSRF 防护的更多信息。

Configuring Endpoints

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

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

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

Sanitize Sensitive Values

脱敏敏感值
/env、/configprops 和 /quartz 端点返回的信息可能包含敏感内容，因此默认情况下，这些值始终会被完全脱敏（替换为 ******）。

只有在满足以下条件时，才能以未脱敏的形式查看值：

• show-values 属性已设置为 never 以外的值
• 没有自定义的 SanitizingFunction bean 生效

可以将可脱敏端点的 show-values 属性配置为以下值之一：

• never - 值始终被完全脱敏（替换为 ******）
• always - 向所有用户显示值（只要没有 SanitizingFunction bean 生效）
• when-authorized - 仅向已授权用户显示值（只要没有 SanitizingFunction bean 生效）

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

对于 JMX 端点，所有用户始终都是已授权的。

以下示例允许所有具有 admin 角色的用户以原始形式查看 /env 端点的值。未授权用户或不具有 admin 角色的用户将只能看到脱敏后的值。

management:endpoint:env:show-values:when-authorizedroles:"admin"

此示例假设没有定义 SanitizingFunction bean。

Hypermedia for Actuator Web Endpoints

Actuator Web 端点的超媒体
会添加一个包含指向所有端点链接的“发现页面”。默认情况下，“发现页面”位于 /actuator。

要禁用“发现页面”，请在您的应用属性中添加以下属性：

management:endpoints:web:discovery:enabled:false

当配置了自定义的管理上下文路径时，“发现页面”会自动从 /actuator 移动到管理上下文的根路径。例如，如果管理上下文路径是 /management，则可以从 /management 访问发现页面。当管理上下文路径设置为 / 时，发现页面会被禁用，以防止与其他映射发生冲突。

CORS Support

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:"https://example.com"allowed-methods:"GET,POST"

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

JSON

在使用 JSON 时，Jackson 被用于序列化和反序列化。默认情况下，系统会使用一个独立的 JsonMapper。这种隔离意味着它不会与应用本身的 JsonMapper 共享相同的配置，也不会受到 spring.jackson.* 属性的影响。若要禁用此行为并配置 Actuator 使用应用的 JsonMapper，请将 management.endpoints.jackson.isolated-json-mapper 设置为 false。或者，您也可以定义自己的 EndpointJsonMapper bean 来生成一个符合您需求的 JsonMapper。Actuator 随后将使用它来进行 JSON 处理。

Implementing Custom Endpoints

实现自定义端点
如果你添加了一个带有 @Endpoint 注解的 @Bean，那么任何带有 @ReadOperation、@WriteOperation 或 @DeleteOperation 注解的方法都会自动通过 JMX 暴露出来；在 Web 应用中，它们也会通过 HTTP 暴露。端点可以通过 Jersey、Spring MVC 或 Spring WebFlux 在 HTTP 上暴露。如果 Jersey 和 Spring MVC 同时存在，则使用 Spring MVC。

以下示例暴露了一个返回自定义对象的读取操作：

@ReadOperationpublicCustomDatagetData(){returnnewCustomData("test",5);}

你也可以使用 @JmxEndpoint 或 @WebEndpoint 来编写特定技术的端点。这些端点仅限于各自对应的技术。例如，@WebEndpoint 仅通过 HTTP 暴露，而不会通过 JMX 暴露。

你可以使用 @EndpointWebExtension 和 @EndpointJmxExtension 来编写特定技术的扩展。这些注解允许你提供特定技术的操作来增强现有的端点。一个端点每种类型的扩展最多只能有一个。

最后，如果你需要访问 Web 框架特有的功能，可以实现 Servlet 或 Spring 的 @Controller 和 @RestController 端点，但代价是它们无法通过 JMX 暴露，或者在使用其他 Web 框架时不可用。

Receiving Input

接收输入
端点上的操作通过其参数来接收输入。当通过 Web 暴露时，这些参数的值取自 URL 的查询参数和 JSON 请求体。当通过 JMX 暴露时，参数会被映射到 MBean 操作的参数。参数默认是必填的。可以通过使用 JSpecify 的 @Nullable 注解将它们设为可选。同时也支持 Kotlin 的空安全。
你可以将 JSON 请求体中的每个根属性映射到端点的参数。请看以下 JSON 请求体示例：

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

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

@WriteOperationpublicvoidupdateData(Stringname,intcounter){// injects "test" and 42}

由于端点是与技术无关的，因此在方法签名中只能指定简单类型。特别是，不支持声明一个具有 name 和 counter 属性的 CustomData 类型的单个参数。
为了让输入能够正确映射到操作方法（operation method）的参数，实现端点的 Java 代码在编译时需要加上-parameters选项。对于 Kotlin 代码，请参阅 Spring Framework 参考文档中的相关建议。如果你使用的是 Spring Boot 的 Gradle 插件，或者使用 Maven 并依赖了spring-boot-starter-parent，这一配置会自动完成。
Input Type Conversion
输入类型转换
传递给端点操作方法（endpoint operation methods）的参数会在必要时自动转换为所需的类型。在调用操作方法之前，通过 HTTP 或 JMX 接收到的输入会使用 ApplicationConversionService 的实例，以及任何带有 @EndpointConverter 限定的 Converter 或 GenericConverter bean，被转换为所需的类型。

Custom Web Endpoints

自定义 Web 端点