Spring Boot 端点

什么是 Spring Boot 端点？

Spring Boot 端点（Endpoints）是通过特定 URL 暴露的接口，主要用于监控和管理 Spring Boot 应用程序的运行时状态。它们由 Spring Boot Actuator 模块提供，允许开发者和运维人员获取应用程序的健康状况、配置信息、性能指标等。端点通常用于生产环境的监控、调试和运维管理。

Spring Boot Actuator 简介

Spring Boot Actuator 是 Spring Boot 的一个模块，提供了一组内置的端点，用于暴露应用程序的运行时信息。Actuator 端点可以通过 HTTP 或 JMX 访问，适用于自动化监控、日志分析、性能调优等场景。

主要特性

• 内置端点：提供多种开箱即用的端点，如健康检查、环境变量、Bean 信息等。
• 可扩展性：支持自定义端点，满足特定需求。
• 安全性：可以与 Spring Security 集成，限制对敏感端点的访问。
• 灵活配置：通过配置文件（如 application.properties 或 application.yml）控制端点的启用、禁用和暴露方式。

内置端点

以下是 Spring Boot Actuator 提供的一些常用内置端点（基于 Spring Boot 3.x）：

端点 ID	描述	默认启用	默认 HTTP 暴露
/actuator/health	显示应用程序健康状态（如 UP 或 DOWN），支持组件级健康检查	是	是
/actuator/info	显示应用程序的元信息（如版本号、构建信息等）	是	是
/actuator/beans	列出 Spring 容器中所有 Bean 的信息	是	否
/actuator/metrics	提供应用程序的性能指标（如内存使用、CPU 使用率等）	是	否
/actuator/env	显示环境变量和配置属性	是	否
/actuator/loggers	查看或动态修改应用程序的日志级别	是	否
/actuator/caches	查看或管理缓存信息	是	否
/actuator/scheduledtasks	列出计划任务信息	是	否
/actuator/shutdown	优雅关闭应用程序（需手动启用）	否	否
/actuator/mappings	列出所有 HTTP 请求映射	是	否
/actuator/conditions	显示自动配置条件的评估报告	是	否

端点访问方式

• HTTP 访问：默认路径为 /actuator/{endpoint-id}，如 http://localhost:8080/actuator/health。
• JMX 访问：通过 JMX 客户端（如 JConsole）访问端点。
• 自定义路径：可以通过配置修改默认路径，例如：management.endpoints.web.base-path=/manage这会将端点路径改为 /manage/{endpoint-id}。

配置端点

Spring Boot 允许通过 application.properties 或 application.yml 配置文件灵活管理端点。以下是一些常见配置项：

1. 暴露端点

默认情况下，只有 /health 和 /info 端点通过 HTTP 暴露。可以通过以下配置暴露其他端点：

# 暴露所有端点
management.endpoints.web.exposure.include=*
# 排除特定端点
management.endpoints.web.exposure.exclude=loggers,shutdown

2. 启用/禁用端点

某些端点（如 /shutdown）默认禁用，可以手动启用：

management.endpoint.shutdown.enabled=true

3. 自定义端点路径

修改 Actuator 的基础路径：

management.endpoints.web.base-path=/monitor

4. 自定义健康检查

可以配置健康检查的详细程度：

management.endpoint.health.show-details=always

• never：不显示详细信息（默认）。
• when-authorized：仅对授权用户显示。
• always：总是显示详细信息。

示例配置文件

以下是一个完整的 application.properties 示例：

# 暴露特定端点
management.endpoints.web.exposure.include=health,info,metrics,beans
# 禁用特定端点
management.endpoint.shutdown.enabled=false
# 自定义基础路径
management.endpoints.web.base-path=/monitor
# 显示健康检查详细信息
management.endpoint.health.show-details=always
# 自定义服务器端口
management.server.port=8081

安全性

Actuator 端点可能包含敏感信息（如环境变量、堆栈跟踪等），因此在生产环境中需要保护。以下是一些常见的安全措施：

1. Spring Security 集成： 添加 Spring Security 依赖并配置访问权限。例如：@Configuration
   public class SecurityConfig {
      @Bean
      public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
          http
             .authorizeHttpRequests(auth -> auth
                 .requestMatchers(“/actuator/health”).permitAll()
                 .requestMatchers(“/actuator/**”).hasRole(“ADMIN”)
                 .anyRequest().authenticated()
             )
             .httpBasic();
          return http.build();
     }
   }
2. 网络隔离：
   • 将 Actuator 端点配置到单独的管理端口：management.server.port=8081
   • 使用防火墙限制对管理端口的访问。
3. 禁用敏感端点： 在生产环境中禁用不必要的端点：management.endpoint.env.enabled=false
   management.endpoint.beans.enabled=false

自定义端点

Spring Boot 允许开发者通过实现 @Endpoint 注解创建自定义端点。以下是一个简单的自定义端点示例：

import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
import org.springframework.stereotype.Component;
​
@Component
@Endpoint(id = "custom")
public class CustomEndpoint {
​
    @ReadOperation
    public String customInfo() {
        return "This is a custom endpoint!";
    }
}

访问路径为 /actuator/custom，返回 JSON 响应：

{
  "message": "This is a custom endpoint!"
}

启用自定义端点

确保在配置文件中暴露自定义端点：

management.endpoints.web.exposure.include=*,custom

实际应用场景

1. 健康检查：
   • 在 Kubernetes 或 Docker 环境中，使用 /actuator/health 进行存活探针（liveness probe）和就绪探针（readiness probe）。
   • 示例：配置 Kubernetes 探针：livenessProbe:
     httpGet:
       path: /actuator/health
       port: 8080
     initialDelaySeconds: 15
     periodSeconds: 10
2. 性能监控：
   • 使用 /actuator/metrics 集成 Prometheus 和 Grafana，监控 JVM 内存、HTTP 请求延迟等。
3. 动态日志管理：
   • 通过 /actuator/loggers 动态调整日志级别，无需重启应用。
4. 环境调试：
   • 使用 /actuator/env 检查配置属性是否正确加载。

注意事项

1. 生产环境：
   • 谨慎暴露端点，特别是 /env、/beans 等敏感端点。
   • 建议使用独立的 Actuator 端口并限制网络访问。
2. 版本差异：
   • Spring Boot 2.x 和 3.x 的 Actuator 功能有所不同。例如，3.x 更紧密集成 Micrometer 进行指标收集。
   • 升级时需检查配置文件和端点路径的变化。
3. 性能影响：
   • 启用过多端点（如 /beans 或 /mappings）可能增加内存和 CPU 消耗，需根据需求选择。

总结

Spring Boot 端点（通过 Actuator 实现）是监控和管理应用程序的强大工具，提供了丰富的内置功能和灵活的扩展能力。通过合理配置和安全保护，端点可以在开发、测试和生产环境中发挥重要作用。