介绍

Spring Boot 为开发人员提供了大量工具和实用程序，有助于简化创建健壮、可扩展应用程序的过程。其中一个功能是 Spring Boot Actuator，它是一组生产就绪的功能，使您能够轻松监视和管理应用程序。执行器端点对于公开与应用程序相关的操作数据和功能至关重要。在这篇文章中，我们将深入研究 Spring Boot Actuator 的注释，例如@Endpoint、@ReadOperation等，这些注释使创建自定义端点变得轻而易举。

什么是 Spring Boot 执行器？

Spring Boot Actuator 不仅仅是 Spring Boot 应用程序的一组附加功能；它是一个库，旨在使您的应用程序进入生产就绪状态，而不需要大量的定制开发。Actuator 提供了一系列功能，旨在简化管理任务并监控应用程序的运行状况、性能和整体状态。从本质上讲，它是 DevOps 工程师和开发人员的救星，提供了原本需要大量自定义代码和第三方工具的功能。

Spring Boot 执行器的主要特性

1. 健康检查：最基本的是，执行器可以通过/health端点报告应用程序的健康状态。这是可扩展和可定制的，允许您添加自己的健康指标。
2. 指标收集：收集系统和应用程序指标，例如内存使用情况、垃圾收集、活动线程等。在诊断问题或调整性能时，这些都是有价值的见解。
3. 环境详细信息：检查正在运行的应用程序中的配置和属性，帮助您调试或确认设置，而无需重新启动服务。
4. 应用程序信息：/info使用任意应用程序信息（例如构建版本、描述和自定义元数据）填充端点。这对于自动化系统和工程师验证部署非常有用。
5. 审核： Spring Boot Actuator 提供了审核应用程序中事件的工具，例如身份验证失败，这对于安全审核至关重要。
6. 功能切换：动态启用或禁用正在运行的应用程序中的功能。这通常用于金丝雀发布或其他渐进式部署策略。

如何添加 Spring Boot 执行器

Spring Boot Actuator 可以快速设置。所需要做的就是向项目的构建配置添加依赖项。

Maven依赖

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

自定义执行器端点

Spring Boot Actuator 的最强点之一是它的自定义选项。尽管它包含一系列端点，但您可能只想公开其中的一个子集，甚至添加您自己的自定义端点。正如您将在以下部分中看到的，执行器使此过程变得简单。

引入@Endpoint注释

“端点”的概念在 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”角色的用户。

探索@ReadOperation、@WriteOperation 和@DeleteOperation

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 的功能。无论您想要公开应用程序指标、配置还是自定义数据，这些注释都可以满足您的需求。