Spring Boot Actuator深度解析与实战
🧩 一、什么是 Spring Boot Actuator？
Actuator = “执行器” / “控制器”
它是 Spring Boot 提供的一个模块，用于：
- 查看应用运行状态（如内存、线程、健康状况）
- 监控性能指标（metrics）
- 执行管理操作（如关闭应用、刷新配置）
这些功能通过一系列 HTTP 接口（称为“端点 endpoints”） 暴露出来。
默认路径：/actuator
例如：
GET /actuator/health→ 查看服务是否健康GET /actuator/metrics→ 获取 JVM 内存、CPU 使用率等GET /actuator/env→ 查看环境变量
🔍 分章节详解
✅ 6.2.5. Hypermedia for Actuator Web Endpoints（超媒体发现页）
核心意思：
提供一个“入口页面”，列出所有可用的 Actuator 端点链接。
关键点解释：
| 内容 | 解释 |
|---|---|
/actuator 是“发现页” | 访问这个 URL，会返回一个 JSON 列表，包含所有已启用的 endpoint 链接（比如 /health, /metrics） |
| 自定义管理路径时自动迁移 | 如果你在 application.yml 中设置了 management.server.base-path=/manage，那么发现页就变成 /manage |
设置为 / 时禁用 | 如果把 management context path 设成根路径 /，为了避免和其他接口冲突，发现页会被关闭 |
📌 示例：
访问 http://localhost:8080/actuator 得到如下结果（部分）：
{"_links": {"self": { "href": "/actuator" },"health": { "href": "/actuator/health" },"metrics": { "href": "/actuator/metrics" },"env": { "href": "/actuator/env" }}
}
👉 这叫 HATEOAS 风格（Hypermedia as the Engine of Application State），即“通过链接导航系统”。
✅ 6.2.6. CORS Support（跨域支持）
核心意思：
允许浏览器从其他域名访问 Actuator 的 API（比如前端管理系统调用后端的 /actuator/health）。
默认情况：
❌ CORS 被禁用
只有当你显式配置了 allowed-origins，才开启。
示例配置（application.yml）：
management:endpoints:web:cors:allowed-origins: https://example.comallowed-methods: GET,POSTallowed-headers: "*"max-age: 3600
这表示：
- 允许来自
https://example.com的请求 - 只能使用 GET 和 POST 方法
- 支持任意 header
- 缓存预检请求 1 小时
💡 注意：需要 Spring MVC 或 WebFlux 才能生效。
✅ 6.2.7. Implementing Custom Endpoints（实现自定义端点）
你可以自己写代码来添加新的监控接口！
方法一：通用端点 @Endpoint（推荐 ✅）
@Component
@Endpoint(id = "custom")
public class CustomEndpoint {@ReadOperationpublic CustomData getData() {return new CustomData("test", 5);}@WriteOperationpublic void updateData(String name, int counter) {// 处理更新逻辑}
}
✅ 特点：
- 同时暴露在 JMX 和 HTTP 上
- 技术无关（不依赖 Spring MVC/Jersey）
- 推荐用于通用场景
| 注解 | 对应 HTTP 方法 | 场景 |
|---|---|---|
@ReadOperation | GET | 查询数据 |
@WriteOperation | POST | 修改数据 |
@DeleteOperation | DELETE | 删除数据 |
方法二：Web 专属端点（@WebEndpoint）
@WebEndpoint(id = "webonly")
public class WebOnlyEndpoint {@ReadOperationpublic String status() {return "OK";}
}
⚠️ 特点：
- 只暴露在 HTTP 上
- 不出现在 JMX 中
- 更轻量，适合只做 Web 监控
方法三：增强已有端点（@EndpointWebExtension）
你想给现有的 health 端点加个额外的 Web 功能？可以用这个。
@EndpointWebExtension(endpoint = HealthEndpoint.class)
public class CustomHealthWebExtension {@ReadOperationpublic Map<String, Object> customHealthInfo() {return Collections.singletonMap("custom", "info");}
}
这样就在原有 /actuator/health 基础上增加了新能力。
方法四：完全自由控制（@ControllerEndpoint / @RestControllerEndpoint）
如果你非要使用 Spring MVC 的注解（如 @GetMapping, @RequestBody），可以这么做：
@RestControllerEndpoint(id = "admin")
public class AdminController {@GetMapping("/pause")public String pauseApp() {// 暂停应用逻辑return "paused";}
}
⚠️ 缺点：
- ❌ 不能用于 JMX
- ❌ 不能用于 Jersey 或非 Spring Web 框架
- ❌ 可移植性差
👉 所以官方建议：优先使用 @Endpoint，除非必须用 MVC 注解。
🔁 输入参数处理（Receiving Input）
如何接收参数？
无论是 GET 参数还是 POST JSON，都可以直接作为方法参数注入。
示例：
@WriteOperation
public void updateUser(String name, int age) {// name 来自 query 参数或 JSON 字段// age 同理
}
请求示例：
POST /actuator/custom?name=Tom
Content-Type: application/json{"age": 25
}
→ name="Tom" 来自 URL 参数
→ age=25 来自 JSON body
✅ 自动拼接！
注意事项：
- 默认参数是必填的
- 加
@Nullable表示可选 - 方法签名只能用基本类型或简单对象字段映射（不能传整个复杂对象）
- Java 编译需加
-parameters（Maven/Gradle 插件默认已开启）
⚙️ Web Endpoint Request Predicates（请求匹配规则）
每个端点的操作都会自动生成一个“请求匹配器”。
1. 路径（Path）
格式：/{base-path}/{endpoint-id}
默认 base-path = /actuator
例子：
- 端点 ID 是
sessions→ 路径是/actuator/sessions - 如果加了
@Selector：
@ReadOperation
public Session getSession(@Selector String id) {// ...
}
→ 路径变成 /actuator/sessions/{id}
支持通配符：
@ReadOperation
public List<String> list(@Selector(match = ALL_REMAINING) String[] parts) {// 匹配 /actuator/path/to/file
}
2. HTTP 方法映射
| Operation | HTTP Method |
|---|---|
@ReadOperation | GET |
@WriteOperation | POST |
@DeleteOperation | DELETE |
3. Content-Type（Consumes）
| 操作类型 | consumes 类型 |
|---|---|
@WriteOperation（带 body） | application/vnd.spring-boot.actuator.v2+json, application/json |
| 其他操作 | 空（不限制） |
👉 支持版本化媒体类型，便于未来升级协议。
4. 返回类型（Produces）
根据返回值决定响应类型：
| 返回值 | Produces |
|---|---|
void / Void | （无 content-type） |
Resource（文件） | application/octet-stream |
| 其他对象 | application/vnd.spring-boot.actuator.v2+json, application/json |
5. 响应状态码（Status Code）
| 情况 | HTTP Status |
|---|---|
@ReadOperation 返回值 | 200 OK |
@ReadOperation 无返回值 | 404 Not Found |
@WriteOperation / @DeleteOperation 有返回值 | 200 OK |
@WriteOperation / @DeleteOperation 无返回值 | 204 No Content |
| 缺少必要参数 or 类型转换失败 | 400 Bad Request |
6. Range 请求（断点续传）
如果返回的是 Resource（比如日志文件），并且使用的是 Spring MVC 或 WebFlux，则支持 HTTP Range 请求（可用于下载大文件的部分内容）。
🚫 不支持 Jersey。
7. 安全控制（Security）
可以在方法参数中获取当前用户信息：
@ReadOperation
public String secureData(Principal principal) {if (principal == null) {return "anonymous";}return "Hello " + principal.getName();
}// 或者更强大的权限判断
@ReadOperation
public boolean isAdmin(SecurityContext securityContext) {return securityContext.isUserInRole("ADMIN");
}
👉 可与 Spring Security 集成，做细粒度权限控制。
8. Servlet 端点（@ServletEndpoint）
如果你想封装一个已有的 Servlet 作为监控端点：
@ServletEndpoint(id = "my-servlet")
public class MyServletEndpoint implements Supplier<EndpointServlet> {@Overridepublic EndpointServlet get() {return new EndpointServlet(MyLegacyServlet.class);}
}
⚠️ 局限性强，仅限 Servlet 容器使用。
✅ 总结：四种创建端点的方式对比
| 方式 | 注解 | 是否支持 JMX | 是否支持 Web | 是否可移植 | 推荐程度 |
|---|---|---|---|---|---|
| 通用端点 | @Endpoint | ✅ | ✅ | ✅ 最高 | ⭐⭐⭐⭐⭐ |
| Web 专属 | @WebEndpoint | ❌ | ✅ | ✅ | ⭐⭐⭐⭐ |
| 扩展已有端点 | @EndpointWebExtension | ❌ | ✅ | ✅ | ⭐⭐⭐⭐ |
| MVC 控制器风格 | @ControllerEndpoint | ❌ | ✅（仅 Spring Web） | ❌ | ⭐⭐ |
💡 实际应用场景举例
场景 1：做一个“清理缓存”的管理接口
@Endpoint(id = "clearcache")
public class ClearCacheEndpoint {@Autowiredprivate CacheManager cacheManager;@WriteOperationpublic String clearAllCaches() {cacheManager.getCacheNames().forEach(name ->cacheManager.getCache(name).clear());return "All caches cleared.";}
}
访问：POST /actuator/clearcache
场景 2：查看某个任务的状态（带 ID）
@Endpoint(id = "tasks")
public class TaskEndpoint {@ReadOperationpublic TaskStatus getStatus(@Selector String taskId) {return taskService.getStatus(taskId);}
}
访问：GET /actuator/tasks/login-job
✅ 最佳实践建议
- 优先使用
@Endpoint+@ReadOperation/@WriteOperation - 避免使用
@ControllerEndpoint，除非必须用@RequestBody等高级特性 - 编译时确保开启
-parameters（Spring Boot 默认已开） - 敏感端点要加安全认证（配合 Spring Security）
- 生产环境不要暴露所有端点！
# application-prod.yml
management:endpoints:web:exposure:include: health,info
📚 学习资源
- 官方文档：https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html
- Actuator endpoints 列表：
GET /actuator
✅ 一句话总结：
这段文档讲的是：如何通过标准和自定义方式，在 Spring Boot 中暴露监控接口，并精确控制它们的路径、参数、安全性、输出格式等行为。
如果你正在开发微服务监控平台、内部运维工具或需要深度集成健康检查系统，这部分知识非常关键！
需要我给你写一个完整的自定义 Actuator 端点示例吗？包括 Maven 配置、Java 代码、测试请求等。