Spring Boot 为开发人员提供了大量工具和实用程序，有助于简化创建健壮、可扩展应用程序的过程。其中一个功能是 Spring Boot Actuator，它是一组生产就绪的功能，使您能够轻松监视和管理应用程序。执行器端点对于公开与应用程序相关的操作数据和功能至关重要。在这篇文章中，我们将深入研究 Spring Boot Actuator 的注释，例如 @Endpoint 、 @ReadOperation 等，这些注释使创建自定义端点变得轻而易举。
Spring Boot Actuator 不仅仅是 Spring Boot 应用程序的一组附加功能；它是一个库，旨在使您的应用程序进入生产就绪状态，而不需要大量的定制开发。Actuator 提供了一系列功能，旨在简化管理任务并监控应用程序的运行状况、性能和整体状态。从本质上讲，它是 DevOps 工程师和开发人员的救星，提供了原本需要大量自定义代码和第三方工具的功能。
Spring Boot 执行器的主要特性
- 健康检查： 最基本的是，执行器可以通过/health端点报告应用程序的健康状态。这是可扩展和可定制的，允许您添加自己的健康指标。
- 指标收集： 收集系统和应用程序指标，例如内存使用情况、垃圾收集、活动线程等。在诊断问题或调整性能时，这些都是有价值的见解。
- 环境详细信息 ：检查正在运行的应用程序中的配置和属性，帮助您调试或确认设置，而无需重新启动服务。
- 应用程序信息： /info使用任意应用程序信息（例如构建版本、描述和自定义元数据）填充端点。这对于自动化系统和工程师验证部署非常有用。
- 审核： Spring Boot Actuator 提供了审核应用程序中事件的工具，例如身份验证失败，这对于安全审核至关重要。
- 功能切换： 动态启用或禁用正在运行的应用程序中的功能。这通常用于金丝雀发布或其他渐进式部署策略。
如何添加 Spring Boot 执行器
Spring Boot Actuator 可以快速设置。所需要做的就是向项目的构建配置添加依赖项。
Maven依赖
`<dependency>` `<groupId>org.springframework.boot</groupId>` `<artifactId>spring-boot-starter-actuator</artifactId>` `</dependency>`
自定义执行器端点
Spring Boot Actuator 的最强点之一是它的自定义选项。尽管它包含一系列端点，但您可能只想公开其中的一个子集，甚至添加您自己的自定义端点。正如您将在以下部分中看到的，执行器使此过程变得简单。
“端点”的概念在 Web 应用程序领域并不新鲜。本质上，端点是应用程序侦听的 URL 模式，提供某种资源或服务。在 Spring Boot 中，术语“端点”通过@Endpoint注释获得了额外的功能和灵活性。此注释允许您公开自定义逻辑和数据，成为可以通过 HTTP、JMX 或其他协议访问的应用程序的操作扩展。
@Endpoint 剖析
该@Endpoint注释用于装饰 Spring 组件，有效地将其标记为公开操作信息或功能的特殊类型的 bean。当您用 注释一个类时@Endpoint，它会获得某些功能：
- ID：您可以为端点分配一个 ID，使其可以通过自定义 URL 进行访问。
- 启用/禁用：可以通过属性有选择地启用或禁用端点。
- 安全性：您可以应用安全规则来限制对端点的访问。
- 操作：您可以定义端点将公开哪种操作（读、写、删除）。
这是一个突出这些要点的基本示例：
`import org.springframework.boot.actuate.endpoint.annotation.Endpoint;` `import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;` `@Endpoint(id = "helloWorld")` `public class HelloWorldEndpoint {` `@ReadOperation` `public String sayHello() {` `return "Hello, World!";` `}` `}`
在此示例中，该类用HelloWorldEndpoint进行注释 @Endpoint ，使其成为执行器端点。该id属性将其 ID 设置为“helloWorld”，使其可以通过 URL 进行访问/actuator/helloWorld。该方法sayHello()用 进行注释 @ReadOperation ，这意味着可以使用 HTTP GET 请求来调用它。
为什么使用@Endpoint？
虽然 Spring Boot Actuator 附带了各种内置端点，但您经常会发现需要自定义行为或数据公开。这就是@Endpoint发挥作用的地方。无论您是希望公开默认情况下未涵盖的系统指标、提供复杂应用程序数据的简化视图，还是提供功能切换等实用功能，注释都使其变得简单且可维护@Endpoint。
安全影响
由于端点可能会暴露敏感数据或功能，因此 Spring Boot 允许您保护它们。您可以通过应用程序的属性文件指定访问每个端点所需的角色，甚至完全禁用某些端点。
`management.endpoint.helloWorld.enabled = true` `management.endpoint.helloWorld.roles =ADMIN`
在此示例中，helloWorld端点已启用并仅限于具有“ADMIN”角色的用户。
Spring Boot 的执行器端点不仅仅是被动的观察者；他们还可以作为管理您的应用程序的积极参与者。这种管理功能是通过三个主要注释实现的： @ReadOperation 、 @WriteOperation 和 @DeleteOperation 。这些注释允许您在自定义端点上公开方法，分别用于读取、写入和删除数据或操作方面。本质上，它们映射到 HTTP GET、POST/PUT 和 DELETE 方法，尽管它们不限于 HTTP 并且可以通过 JMX 等其他协议公开。
@ReadOperation
该 @ReadOperation 注释用于公开类似 HTTP GET 的操作。它允许您从系统读取信息并将其呈现给呼叫者。范围可以从有关资源使用情况的基本统计数据到更复杂的数据形式，例如应用程序中各种服务的状态。
例如，考虑一个公开系统上可用磁盘空间的自定义端点。
`import org.springframework.boot.actuate.endpoint.annotation.Endpoint;` `import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;` `import java.io.File;` `@Endpoint(id = "diskSpace")` `public class DiskSpaceEndpoint {` `@ReadOperation` `public long getFreeDiskSpace() {` `File file = new File("/");` `return file.getFreeSpace();` `}` `}`
@WriteOperation
使用 @WriteOperation ，您可以公开更改应用程序状态的方法。它相当于执行器端点的 HTTP POST 或 PUT。您可以使用它来更新配置、启用或禁用功能或启动特定操作。
以下是切换应用程序中的功能的端点示例：
`import org.springframework.boot.actuate.endpoint.annotation.Endpoint;` `import org.springframework.boot.actuate.endpoint.annotation.WriteOperation;` `import java.util.concurrent.atomic.AtomicBoolean;` `@Endpoint(id = "featureToggle")` `public class FeatureToggleEndpoint {` `private AtomicBoolean featureEnabled = new AtomicBoolean(true);` `@WriteOperation` `public String toggleFeature() {` `featureEnabled.set(!featureEnabled.get());` `return "Feature is now " + (featureEnabled.get() ? "enabled" : "disabled");` `}` `}`
@DeleteOperation
该 @DeleteOperation 注释公开了类似 HTTP DELETE 的操作。这通常用于清理资源或将应用程序的某些方面重置为其默认状态。
例如，让我们考虑一个清除内存缓存的端点：
`import org.springframework.boot.actuate.endpoint.annotation.Endpoint;` `import org.springframework.boot.actuate.endpoint.annotation.DeleteOperation;` `import java.util.Map;` `import java.util.concurrent.ConcurrentHashMap;` `@Endpoint(id = "cache")` `public class CacheEndpoint {` `private Map<String, Object> cache = new ConcurrentHashMap<>();` `@DeleteOperation` `public String clearCache() {` `cache.clear();` `return "Cache cleared";` `}` `}`
参数和端点操作
这些注释还允许您接受参数。例如，您可以在 @ReadOperation 方法中使用查询参数，或在 @WriteOperation 和@DeleteOperation方法中使用请求正文和路径变量，从而使您能够更好地控制和灵活地控制自定义端点的功能。
了解基本注释及其功能后，您可能想知道如何在 Spring Boot 应用程序中实际实现自定义执行器端点。由于该框架提供的易用性和灵活性，该过程非常简单。在本节中，我们将逐步创建一个功能齐全的自定义执行器端点，该端点公开假设应用程序中的活动用户数量。
第1步：使用@Endpoint创建一个Spring组件
首先，您需要创建一个 Spring 组件并对其进行注释@Endpoint以定义您的自定义端点。该id属性用于指定可访问端点的 URL。
`import org.springframework.boot.actuate.endpoint.annotation.Endpoint;` `@Endpoint(id = "activeUsers")` `public class ActiveUsersEndpoint {` `// 实现将在此处` `}`
第二步：添加操作方法
一旦您使用 设置了您的类 @Endpoint ，您就可以开始添加方法来公开不同的操作。在此示例中，我们将用来 @ReadOperation 公开活跃用户的数量。
`import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;` `public class ActiveUsersEndpoint {` `@ReadOperation` `public int getActiveUsers () {` `// 通常，此数据可能来自数据库或其他外部源。` `return 5；` `}` `}`
步骤 3：保护端点（可选）
如果您的自定义端点暴露了敏感数据或功能，那么保护它就至关重要。您可以使用文件中的属性application.properties或直接在代码中进行配置。
`management.endpoint.activeUsers.enabled = true` `management.endpoint.activeUsers.roles = ADMIN`
第 4 步：测试您的端点
创建自定义端点后，最好对其进行测试。根据您配置 Spring Boot 应用程序的方式，新端点应该可以通过类似 的 URL 访问http://localhost:8080/actuator/activeUsers。
您可能希望端点更具交互性。您可以根据您的要求添加更多带有 @WriteOperation 和注释的操作方法。 @DeleteOperation
`import org.springframework.boot.actuate.endpoint.annotation.WriteOperation;` `import org.springframework.boot.actuate.endpoint.annotation.DeleteOperation;` `public class ActiveUsersEndpoint {` `@WriteOperation` `public String addUser () {` `// 将新用户添加到活动用户列表` `return "用户添加成功。" ;` `}` `@DeleteOperation` `public String removeUser () {` `// 从活跃用户列表中删除用户` `return "用户删除成功。" ;` `}` `}`
Spring Boot Actuator 注解如 @Endpoint 、 @ReadOperation 、 @WriteOperation 、 和 @DeleteOperation 提供了一种强大的方式来公开和管理您的应用程序。这些注释简化了创建自定义端点的过程，并使您的应用程序更加健壮和易于管理。
通过了解这些注解以及如何实现它们，您可以充分利用 Spring Boot Actuator 的功能。无论您想要公开应用程序指标、配置还是自定义数据，这些注释都可以满足您的需求。