Spring Boot Actuator 常用核心端点详解

🌟 Spring Boot Actuator 常用核心端点详解

Spring Boot Actuator 提供了多个内置端点（Endpoints），用于监控、调试和管理应用运行状态。以下是 最常用的核心端点 的详细说明，涵盖其功能、使用场景、配置方式和实际应用技巧。

---

1. /actuator/health —— 应用健康检查

🔍 功能

显示应用的健康状态，常用于负载均衡、Kubernetes 探针、服务注册中心（如 Eureka）的健康判断。

📊 默认响应

{
  "status": "UP"
}

🔧 启用详细信息

默认只显示 UP/DOWN，可通过配置查看组件详情：

management:
  endpoint:
    health:
      show-details: always  # 或 when-authorized, never

🌐 访问示例

GET /actuator/health

返回：

{
  "status": "UP",
  "components": {
    "diskSpace": {
      "status": "UP",
      "details": { "total": 500000000, "free": 200000000 }
    },
    "db": {
      "status": "UP",
      "details": { "database": "MySQL", "hello": 1 }
    },
    "redis": {
      "status": "UP"
    }
  }
}

✅ 常见健康指示器（Health Indicators）

• DiskSpaceHealthIndicator
• DataSourceHealthIndicator（数据库）
• RedisHealthIndicator
• RabbitHealthIndicator
• CassandraHealthIndicator
• 自定义健康检查（实现 HealthIndicator 接口）

💡 提示：可自定义健康检查逻辑，用于监控第三方服务。

---

2. /actuator/metrics —— 应用性能指标

🔍 功能

提供 JVM 和应用级别的度量指标，集成 Micrometer，支持 Prometheus、Graphite、InfluxDB 等。

📊 默认指标

• JVM 内存（jvm.memory.used）
• 线程数（jvm.threads.live）
• 系统负载（system.cpu.usage）
• HTTP 请求统计（http.server.requests）

🌐 查看所有指标

GET /actuator/metrics

返回：

{
  "names": [
    "jvm.memory.max",
    "jvm.memory.used",
    "http.server.requests",
    "system.cpu.usage"
  ]
}

🔍 查看特定指标

GET /actuator/metrics/http.server.requests

返回：

{
  "name": "http.server.requests",
  "measurements": [
    { "statistic": "COUNT", "value": 150 },
    { "statistic": "TOTAL_TIME", "value": 2.34 },
    { "statistic": "MEAN", "value": 0.0156 }
  ],
  "availableTags": [
    { "tag": "method", "values": ["GET", "POST"] },
    { "tag": "uri", "values": ["/api/user", "/login"] },
    { "tag": "status", "values": ["200", "404"] }
  ]
}

📈 业务指标监控

你也可以自定义指标：

@Autowired
private MeterRegistry registry;

public void processOrder() {
    Counter counter = registry.counter("order.processed");
    counter.increment();
}

然后访问 /actuator/metrics/order.processed 查看。

---

3. /actuator/env —— 环境变量与配置属性

🔍 功能

显示所有环境属性，包括：

• application.yml 配置
• 系统环境变量
• JVM 系统属性
• 命令行参数
• 配置中心（如 Nacos、Consul）的值

🌐 使用场景

• 调试配置未生效问题
• 验证 @Value 是否正确注入
• 检查多 Profile 下的配置差异

🌐 访问示例

GET /actuator/env

返回：

{
  "activeProfiles": ["prod"],
  "propertySources": [
    {
      "name": "server.ports",
      "properties": {
        "server.port": { "value": "8080", "origin": "class path resource ..." }
      }
    }
  ]
}

🔍 查看单个属性

GET /actuator/env/server.port

返回：

{ "property": { "value": "8080", "origin": "..." } }

⚠️ 安全警告：env 可能暴露数据库密码等敏感信息，生产环境建议禁用或限制访问。

---

4. /actuator/beans —— Spring Bean 列表

🔍 功能

列出 Spring IoC 容器中所有 Bean 的信息，包括：

• Bean 名称
• 类型
• 作用域（singleton / prototype）
• 依赖关系
• 来源配置类

🌐 访问示例

GET /actuator/beans

返回（简化）：

[
  {
    "bean": "userService",
    "dependencies": ["userRepository"],
    "scope": "singleton",
    "type": "com.example.UserService"
  },
  {
    "bean": "dataSource",
    "scope": "singleton",
    "type": "com.zaxxer.hikari.HikariDataSource"
  }
]

🛠️ 使用场景

• 分析 Bean 创建失败原因
• 检查循环依赖
• 调试 @Conditional 注解是否生效

💡 提示：结合 /mappings 可分析 Controller 与 Service 的依赖关系。

---

5. /actuator/loggers —— 日志级别动态管理

🔍 功能

查看和动态修改日志级别，无需重启应用。

🌐 查看所有日志器

GET /actuator/loggers

返回：

{
  "levels": ["OFF", "ERROR", "WARN", "INFO", "DEBUG", "TRACE"],
  "loggers": {
    "ROOT": { "configuredLevel": "INFO", "effectiveLevel": "INFO" },
    "com.example": { "configuredLevel": null, "effectiveLevel": "INFO" }
  }
}

🔍 查看特定 Logger

GET /actuator/loggers/com.example.service

✏️ 动态修改日志级别（POST）

curl -X POST http://localhost:8080/actuator/loggers/com.example.service \
  -H "Content-Type: application/json" \
  -d '{"configuredLevel": "DEBUG"}'

✅ 生产环境利器：临时开启 DEBUG 级别排查问题，完成后恢复为 INFO。

---

6. /actuator/mappings —— 请求映射路径

🔍 功能

显示所有 @RequestMapping 注解的路径映射，包括：

• @GetMapping, @PostMapping 等
• Handler 方法信息
• 所属 Controller 类

🌐 访问示例

GET /actuator/mappings

返回：

{
  "contexts": {
    "application": {
      "mappings": {
        "dispatcherHandlers": [
          {
            "handler": "com.example.UserController#getUser(String)",
            "predicate": "GET /api/user/{id}",
            "details": { ... }
          }
        ]
      }
    }
  }
}

🛠️ 使用场景

• 快速查找某个接口的 URL
• 检查是否有重复映射
• 调试 404 错误时确认路由是否存在

---

7. /actuator/threaddump —— 线程快照

🔍 功能

获取 JVM 当前所有线程的堆栈信息，用于分析：

• 死锁（Deadlock）
• 线程阻塞
• CPU 占用过高
• 请求卡住问题

🌐 访问示例

GET /actuator/threaddump

返回（部分）：

[
  {
    "threadName": "http-nio-8080-exec-1",
    "threadState": "RUNNABLE",
    "stackTrace": [
      "sun.management.ThreadImpl.dumpThreads(Native Method)",
      "com.example.service.UserService.process(UserService.java:45)",
      "..."
    ],
    "blockedCount": 0,
    "waitedCount": 0
  }
]

📊 分析建议

• 导出后使用 VisualVM、JConsole 或 fastthread.io 在线工具分析
• 关注 BLOCKED、WAITING 状态的线程
• 检查是否有死锁（deadlock 字段）

---

✅ 各端点使用场景总结

端点	主要用途	生产环境建议
/health	健康检查、服务探针	✅ 开启，建议显示详情（授权用户）
/metrics	性能监控、Prometheus 集成	✅ 强烈推荐
/env	配置调试	⚠️ 开发环境使用，生产慎用
/beans	Bean 依赖分析	⚠️ 仅调试时开启
/loggers	动态调日志级别	✅ 推荐，便于排查问题
/mappings	路由查看	✅ 安全，可开启
/threaddump	性能分析	✅ 必要时使用

---

🔐 安全提示

端点	风险	建议
env, beans	信息泄露	❌ 不暴露或权限控制
shutdown	可关闭服务	❌ 禁用或严格认证
heapdump	内存泄露分析	✅ 仅运维操作
所有端点	未授权访问	✅ 配合 Spring Security

---

🚀 小贴士

• 使用 Spring Boot Admin 可图形化展示所有端点信息。
• 结合 Prometheus + Grafana 实现指标可视化。
• 使用 Micrometer 自定义业务指标（如订单量、支付成功率）。