SpringBoot如何监听接口调用情况

在SpringBoot项目中，监控接口的调用情况是个常见的需求。调用次数、传入参数、返回参数、响应耗时——这些数据对于性能分析、问题定位和业务统计都至关重要。本文将介绍几种实现方案，从轻量的日志记录到生产级的可视化监控，涵盖了大多数开发场景。 ## 章节阅读路线图 1. **AOP 切面方案（最推荐）** → 使用 Spring AOP 无侵入式监控所有接口 2. **自定义注解方案** → 选择性监控，只针对关键接口 3. **HandlerInterceptor 拦截器方案** → 基于 Spring MVC 拦截器实现 4. **Micrometer + Actuator 生产级方案** → 接入 Prometheus + Grafana 可视化监控 5. **方案对比与总结** → 根据场景选择最合适的方案 ## 1. AOP 切面方案（最推荐） > 使用 Spring AOP 无侵入式监控所有或者指定接口，记录调用次数、参数、返回值和耗时 AOP嘛，Spring框架的核心特性之一，可以在不修改原有代码的情况下对方法进行增强。利用AOP，只需要编写一个切面类，就能统一拦截所有Controller方法，实现接口监控。这个方案最大的好处就是无侵入——现有的业务代码完全不需要改动。 ### 1.1 引入依赖 ```xml org.springframework.boot spring-boot-starter-aop com.alibaba fastjson 2.0.x ``` > spring-boot-starter-aop 已包含 AspectJ 依赖。fastjson 用于将参数和返回值序列化为 JSON 字符串，也可以用 Jackson（SpringBoot 默认自带）。 ### 1.2 编写切面类 切面类的核心逻辑并不复杂：通过环绕通知，在方法执行前后分别记录时间，再结合请求上下文提取URL、IP等基本信息，最后将数据组装输出。 ```ja va package com.example.aspect; // 包名根据实际项目调整 import com.alibaba.fastjson.JSON; // 引入 JSON 序列化工具，用于格式化参数和返回值 import lombok.extern.slf4j.Slf4j; // 引入 Slf4j 注解，自动生成 log 日志对象 import org.aspectj.lang.ProceedingJoinPoint; // 引入 ProceedingJoinPoint，用于执行目标方法并获取上下文 import org.aspectj.lang.annotation.Around; // 引入环绕通知注解，@Around 可以包裹目标方法的执行 import org.aspectj.lang.annotation.Aspect; // 引入切面注解，标识该类为 AOP 切面 import org.aspectj.lang.annotation.Pointcut; // 引入切点注解，定义拦截规则 import org.springframework.stereotype.Component; // 引入 Component 注解，将切面注入 Spring 容器 import org.springframework.web.context.request.RequestContextHolder; // 引入 RequestContextHolder，获取当前请求的上下文 import org.springframework.web.context.request.ServletRequestAttributes; // 引入 ServletRequestAttributes，获取 HttpServletRequest import ja vax.servlet.http.HttpServletRequest; // 引入 HttpServletRequest，用于获取请求 URL、方法类型等 import ja va.util.Arrays; // 引入 Arrays 工具类，用于数组操作 import ja va.util.Map; // 引入 Map 接口，用于存储调用次数统计 import ja va.util.concurrent.ConcurrentHashMap; // 引入 ConcurrentHashMap，线程安全的计数器容器 import ja va.util.concurrent.atomic.AtomicLong; // 引入 AtomicLong，线程安全的原子计数器 /** * 接口监控切面 * * 功能：统计每个接口的调用次数、记录传入参数、返回参数、响应耗时 * * Args: * 无 * * Returns: * 无（通过 log 输出监控信息） * * Example: * 自动生效，无需手动调用 */ @Slf4j // Lombok 注解，自动生成 log 字段，示例：log.info("消息") @Aspect // 标识当前类为切面类 @Component // 将当前类注入 Spring 容器 public class ApiMonitorAspect { // 线程安全的调用次数统计容器 // Key: 接口方法名（类名+方法名），Value: 原子计数器 // 示例：{"UserController.getUser" → 42, "OrderController.createOrder" → 15} private final Map callCountMap = new ConcurrentHashMap<>(); /** * 定义切点：拦截 com.example.controller 包下所有类的所有方法 * * Args: * 无 * * Returns: * 无 * * Example: * execution(* com.example.controller.*.*(..)) 表示拦截 controller 包下所有方法 */ @Pointcut("execution(* com.example.controller.*.*(..))") public void controllerPointcut() { // 切点方法，无实际逻辑，仅用于定义拦截规则 } /** * 环绕通知：在目标方法执行前后插入监控逻辑 * * Args: * joinPoint: 连接点对象，包含目标方法的全部上下文信息 * * Returns: * Object: 目标方法的返回值，原封不动返回 * * Example: * @Around("controllerPointcut()") * public Object monitorApi(ProceedingJoinPoint joinPoint) */ @Around("controllerPointcut()") public Object monitorApi(ProceedingJoinPoint joinPoint) throws Throwable { // ===== 1. 获取请求上下文信息 ===== // 通过 RequestContextHolder 获取当前线程绑定的 Servlet 请求属性 // 数据流动：HttpServletRequest → RequestContextHolder → 提取 URL/Method/IP ServletRequestAttributes attributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes(); HttpServletRequest request = attributes.getRequest(); String requestUrl = request.getRequestURL().toString(); // 获取完整请求 URL，示例："http://localhost:8080/api/user/list" String httpMethod = request.getMethod(); // 获取 HTTP 方法类型，示例："GET"、"POST" String clientIp = request.getRemoteAddr(); // 获取客户端 IP 地址，示例："127.0.0.1" // ===== 2. 获取方法信息 ===== // 获取目标方法的全限定名（包名+类名+方法名） // 数据流动：joinPoint.getSignature() → 方法签名 → 类名.方法名 String className = joinPoint.getTarget().getClass().getSimpleName(); // 获取类名，示例："UserController" String methodName = className + "." + joinPoint.getSignature().getName(); // 组装方法名，示例："UserController.getUser" // ===== 3. 统计调用次数 ===== // 从 callCountMap 中获取或创建该方法的原子计数器，然后自增 // 数据流动：methodName → ConcurrentHashMap.get() → AtomicLong.incrementAndGet() → 返回递增后的值 long currentCount = callCountMap.computeIfAbsent(methodName, k -> new AtomicLong(0)).incrementAndGet(); // ===== 4. 获取传入参数 ===== // 获取目标方法的所有参数值列表 // 数据流动：joinPoint.getArgs() → Object[] → JSON.toJSONString() → JSON 字符串 Object[] args = joinPoint.getArgs(); String requestParams = JSON.toJSONString(args); // 将参数数组序列化为 JSON，示例："[{"id":1,"name":"张三"}]" // ===== 5. 记录开始时间 ===== // 记录当前时间戳，用于后续计算接口耗时 long startTime = System.currentTimeMillis(); // ===== 6. 执行目标方法 ===== // proceed() 会执行被拦截的原始方法，返回原始结果 // 数据流动：joinPoint.proceed() → 目标方法执行 → 返回 Object 类型结果 Object result = joinPoint.proceed(); // ===== 7. 计算响应耗时 ===== // 用结束时间减去开始时间，得到接口处理耗时 long elapsed = System.currentTimeMillis() - startTime; // 计算耗时，单位：毫秒 // ===== 8. 获取返回参数 ===== // 将方法返回值序列化为 JSON 字符串 // 数据流动：result Object → JSON.toJSONString() → JSON 字符串 String responseResult = JSON.toJSONString(result); // ===== 9. 输出监控日志 ===== // 汇总所有监控信息，统一输出 log.info("n========================================n" + "接口监控信息：n" + " 请求地址: {} {}n" + " 客户端IP: {}n" + " 接口方法: {}n" + " 调用次数(累计): {}n" + " 传入参数: {}n" + " 返回参数: {}n" + " 响应耗时: {}msn" + "========================================", httpMethod, requestUrl, // 填充请求地址 clientIp, // 填充客户端 IP methodName, // 填充接口方法名 currentCount, // 填充累计调用次数 requestParams.length() > 500 ? requestParams.substring(0, 500) + "..." : requestParams, // 参数过长时截断 responseResult.length() > 500 ? responseResult.substring(0, 500) + "..." : responseResult, // 返回值过长时截断 elapsed); // 填充响应耗时 // 原封不动返回目标方法的执行结果，不对业务逻辑产生任何影响 return result; } /** * 获取指定接口的累计调用次数 * * Args: * methodName: 方法名，格式为 "类名.方法名"，示例："UserController.getUser" * * Returns: * long: 该接口的累计调用次数，如果未找到返回 0 * * Example: * long count = apiMonitorAspect.getCallCount("UserController.getUser"); */ public long getCallCount(String methodName) { AtomicLong counter = callCountMap.get(methodName); // 从 Map 中查询指定方法的计数器 return counter != null ? counter.get() : 0; // 如果存在则返回计数，否则返回 0 } /** * 获取所有接口的调用次数统计（可用于对外暴露 API） * * Args: * 无 * * Returns: * Map: 所有接口的调用次数映射表，示例：{"UserController.getUser": 42} * * Example: * Map allStats = apiMonitorAspect.getAllCallCounts(); */ public Map getAllCallCounts() { Map result = new ConcurrentHashMap<>(); // 创建结果容器 callCountMap.forEach((key, value) -> result.put(key, value.get())); // 遍历并转换 AtomicLong 为普通 Long return result; // 返回不可修改的统计视图 } } ``` ### 1.3 输出示例 从输出可以看到，监控信息完整覆盖了需求中的四个维度 ``` 2026-05-28 14:30:22.156 [http-nio-8080-exec-1] INFO c.e.aspect.ApiMonitorAspect - ======================================== 接口监控信息： 请求地址: GET http://localhost:8080/api/user/list 客户端IP: 127.0.0.1 接口方法: UserController.getUserList 调用次数(累计): 1 传入参数: [{"page":1,"size":10}] 返回参数: {"code":200,"data":[{"id":1,"name":"张三"}],"msg":"成功"} 响应耗时: 45ms ======================================== 2026-05-28 14:30:25.891 [http-nio-8080-exec-2] INFO c.e.aspect.ApiMonitorAspect - ======================================== 接口监控信息： 请求地址: POST http://localhost:8080/api/user/create 客户端IP: 192.168.1.100 接口方法: UserController.createUser 调用次数(累计): 1 传入参数: [{"name":"李四","age":25,"email":"lisi@example.com"}] 返回参数: {"code":200,"data":{"id":2},"msg":"创建成功"} 响应耗时: 120ms ======================================== ``` 从输出可以看到，监控信息完整覆盖了需求中的四个维度： - 调用次数：调用次数(累计): 1 - 传入参数：传入参数: [{"page":1,"size":10}] - 返回参数：返回参数: {"code":200,"data":[...]} - 响应耗时：响应耗时: 45ms ## 2. 自定义注解方案（选择性监控） > 通过自定义注解实现选择性监控，只对关键接口生效 如果不想监控所有接口，而是希望有针对性地监控某些关键方法（比如支付、登录这些核心业务），自定义注解方案会更好用。 ### 2.1 定义注解 首先定义一个注解，加上可选的描述信息属性： ```ja va package com.example.annotation; // 包名根据实际项目调整 import ja va.lang.annotation.ElementType; // 引入 ElementType 枚举，用于指定注解的适用范围 import ja va.lang.annotation.Retention; // 引入 Retention 枚举，用于指定注解的生命周期 import ja va.lang.annotation.RetentionPolicy; // 引入 RetentionPolicy，RetentionPolicy.RUNTIME 表示运行时保留 import ja va.lang.annotation.Target; // 引入 Target 注解，用于限制注解能标注的位置 /** * 接口监控注解 * * 用于标记需要监控调用次数、参数、耗时等信息的接口方法 * * Args: * value: 接口描述信息，可选，示例："用户登录接口" * * Returns: * 无（注解本身不返回值） * * Example: * @Monitored("用户登录接口") * public Result login(@RequestBody LoginDTO dto) */ @Target(ElementType.METHOD) // 注解只能标注在方法上 @Retention(RetentionPolicy.RUNTIME) // 注解在运行时保留，AOP 才能在运行时读取 public @interface Monitored { /** * 接口描述信息 * * Args: * 无 * * Returns: * String: 接口的描述说明，默认为空字符串 * * Example: * @Monitored("用户登录接口") */ String value() default ""; // 可选属性，用于描述接口用途 } ``` ### 2.2 修改切面类 切点表达式改为匹配标注了 `@Monitored` 注解的方法。 ```ja va /** * 基于自定义注解的接口监控切面 * * 功能：只对标注了 @Monitored 注解的方法进行监控 * * Args: * 无 * * Returns: * 无（通过 log 输出监控信息） * * Example: * 在 Controller 方法上添加 @Monitored 即可生效 */ @Slf4j @Aspect @Component public class MonitoredApiAspect { // 线程安全的调用次数统计容器 // Key: 接口方法名，Value: 原子计数器 private final Map callCountMap = new ConcurrentHashMap<>(); /** * 定义切点：拦截所有标注了 @Monitored 注解的方法 * * Args: * monitored: 注入的注解实例，可在通知中读取注解属性 * * Returns: * 无 * * Example: * @annotation(com.example.annotation.Monitored) 匹配所有标有 @Monitored 的方法 */ @Pointcut("@annotation(com.example.annotation.Monitored)") public void monitoredPointcut() { // 切点方法，无实际逻辑 } /** * 环绕通知：拦截并监控标注了 @Monitored 的方法 * * Args: * joinPoint: 连接点对象，包含目标方法的全部上下文信息 * monitored: 目标方法上的 @Monitored 注解实例，可读取 value 属性 * * Returns: * Object: 目标方法的返回值 * * Example: * @Around("monitoredPointcut() && @annotation(monitored)") */ @Around("monitoredPointcut() && @annotation(monitored)") public Object monitorAnnotatedApi(ProceedingJoinPoint joinPoint, Monitored monitored) throws Throwable { // 获取注解中填写的接口描述，示例："用户登录接口" String description = monitored.value(); // 获取方法信息 String methodName = joinPoint.getTarget().getClass().getSimpleName() + "." + joinPoint.getSignature().getName(); // 统计调用次数 long currentCount = callCountMap.computeIfAbsent(methodName, k -> new AtomicLong(0)).incrementAndGet(); // 获取传入参数 Object[] args = joinPoint.getArgs(); String requestParams = JSON.toJSONString(args); // 获取请求信息 ServletRequestAttributes attributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes(); HttpServletRequest request = attributes.getRequest(); // 记录开始时间 long startTime = System.currentTimeMillis(); // 执行目标方法 Object result = joinPoint.proceed(); // 计算耗时 long elapsed = System.currentTimeMillis() - startTime; // 输出监控日志 log.info("[接口监控] {} | {} | 方法: {} | 累计调用: {} | 参数: {} | 耗时: {}ms | 返回: {}", request.getMethod(), request.getRequestURL(), methodName, currentCount, requestParams, elapsed, JSON.toJSONString(result)); return result; } } ``` ### 2.3 使用方式 在需要监控的接口方法上加一行注解即可，未标注的方法不受影响。 ```ja va @RestController @RequestMapping("/api/user") public class UserController { @Monitored("用户登录接口") // 标注需要监控的方法 @PostMapping("/login") public Result login(@RequestBody LoginDTO loginDTO) { // 业务逻辑 return Result.success("登录成功"); } @GetMapping("/list") // 未标注 @Monitored，不会被监控 public Result list() { return Result.success(userService.list()); } } ``` ## 3. HandlerInterceptor 拦截器方案 > 使用 Spring MVC 的 HandlerInterceptor，在请求处理前后插入监控逻辑 Interceptor 是 Spring MVC 特有的拦截机制，在请求进入 Controller 之前和响应返回之后执行。相比AOP方案，它的优势在于对HTTP请求的处理更原生，但缺点是只能拿到请求层面的信息，无法直接获取Controller方法的参数和返回值。 ### 3.1 实现拦截器 ```ja va package com.example.interceptor; // 包名根据实际项目调整 import com.alibaba.fastjson.JSON; // 引入 JSON 序列化工具，用于格式化请求参数 import lombok.extern.slf4j.Slf4j; // 引入 Slf4j 注解 import org.springframework.stereotype.Component; // 引入 Component 注解，将拦截器注入 Spring 容器 import org.springframework.web.servlet.HandlerInterceptor; // 引入 HandlerInterceptor 接口，需要实现 preHandle 和 afterCompletion import org.springframework.web.servlet.ModelAndView; // 引入 ModelAndView 类 import ja vax.servlet.http.HttpServletRequest; // 引入 HttpServletRequest import ja vax.servlet.http.HttpServletResponse; // 引入 HttpServletResponse import ja va.util.Map; // 引入 Map 接口，用于存储统计信息 import ja va.util.concurrent.ConcurrentHashMap; // 引入 ConcurrentHashMap，线程安全的统计容器 import ja va.util.concurrent.atomic.AtomicLong; // 引入 AtomicLong，线程安全的计数器 /** * 接口监控拦截器 * * 功能：在请求处理前后记录调用次数、参数、耗时等监控信息 * * Args: * 无 * * Returns: * 无（通过 log 输出监控信息） * * Example: * 在 WebConfig 中注册该拦截器即可生效 */ @Slf4j @Component public class ApiMonitorInterceptor implements HandlerInterceptor { // 线程安全的统计容器 // Key: URL（请求路径），Value: 原子计数器 // 示例：{"/api/user/list": 42, "/api/user/create": 15} private final Map urlCountMap = new ConcurrentHashMap<>(); // 使用 ThreadLocal 存储每个请求的开始时间，确保线程隔离 // 数据流动：preHandle 中 set(startTime) → afterCompletion 中 get() 计算耗时 → finally 中 remove() 清理 private final ThreadLocal startTimeHolder = new ThreadLocal<>(); // 使用 ThreadLocal 存储每个请求的 URL，用于在 afterCompletion 中统计 private final ThreadLocal urlHolder = new ThreadLocal<>(); /** * 请求处理前执行 * * Args: * request: HTTP 请求对象 * response: HTTP 响应对象 * handler: 处理该请求的处理器（Controller 方法） * * Returns: * boolean: true 表示继续执行，false 表示中断请求 * * Example: * preHandle 中记录开始时间和请求参数 */ @Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { // 获取请求 URL，示例："/api/user/list" String requestUrl = request.getRequestURI(); // 将请求 URL 存入 ThreadLocal，供 afterCompletion 使用 urlHolder.set(requestUrl); // 该请求的调用次数加 1 // 数据流动：urlCountMap.get(requestUrl) → AtomicLong.incrementAndGet() → 返回自增后的值 long currentCount = urlCountMap.computeIfAbsent(requestUrl, k -> new AtomicLong(0)).incrementAndGet(); // 记录请求开始时间，存入 ThreadLocal startTimeHolder.set(System.currentTimeMillis()); // 记录请求信息 log.info("[请求开始] {} {} | 累计调用: {} | 参数: {}", request.getMethod(), // HTTP 方法，示例："GET" requestUrl, // 请求路径，示例："/api/user/list" currentCount, // 累计调用次数 JSON.toJSONString(request.getParameterMap()) // 请求参数 Map，示例：{"page":["1"],"size":["10"]} ); return true; // 返回 true，继续执行后续处理 } /** * 请求完成后执行（无论是否异常） * * Args: * request: HTTP 请求对象 * response: HTTP 响应对象 * handler: 处理该请求的处理器 * ex: 处理过程中抛出的异常（如果有） * * Returns: * 无 * * Example: * afterCompletion 中计算耗时并输出日志 */ @Override public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) { try { // 从 ThreadLocal 中取出开始时间 Long startTime = startTimeHolder.get(); if (startTime == null) { // 安全校验：如果 startTime 为空，说明 preHandle 未执行成功 return; // 直接返回，不进行后续处理 } // 计算处理耗时，单位：毫秒 // 数据流动：结束时间戳 - 开始时间戳 → 耗时毫秒数 long elapsed = System.currentTimeMillis() - startTime; // 获取请求 URL String requestUrl = urlHolder.get(); // 获取 HTTP 状态码，示例：200、404、500 int status = response.getStatus(); // 输出监控日志 log.info("[请求结束] {} | 状态: {} | 耗时: {}ms{}", requestUrl, // 请求路径 status, // HTTP 状态码 elapsed, // 响应耗时 ex != null ? " | 异常: " + ex.getMessage() : "" // 如果有异常则追加异常信息 ); } finally { // 清理 ThreadLocal，防止内存泄漏（线程池中的线程会被复用） startTimeHolder.remove(); urlHolder.remove(); } } } ``` ### 3.2 注册拦截器 别忘了把拦截器注册到Spring MVC的拦截器链中。 ```ja va package com.example.config; // 包名根据实际项目调整 import com.example.interceptor.ApiMonitorInterceptor; // 引入自定义拦截器 import org.springframework.beans.factory.annotation.Autowired; // 引入自动注入注解 import org.springframework.context.annotation.Configuration; // 引入 Configuration 注解，标识为配置类 import org.springframework.web.servlet.config.annotation.InterceptorRegistry; // 引入拦截器注册器 import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; // 引入 WebMvcConfigurer 接口，用于自定义 Spring MVC 配置 /** * Web MVC 配置类 * * 功能：注册自定义拦截器到 Spring MVC 拦截器链中 * * Args: * 无 * * Returns: * 无 * * Example: * @Configuration 注解的类会自动被 Spring 扫描并加载配置 */ @Configuration // 标识为配置类 public class WebConfig implements WebMvcConfigurer { @Autowired private ApiMonitorInterceptor apiMonitorInterceptor; // 注入自定义的接口监控拦截器 /** * 添加拦截器到 Spring MVC 框架 * * Args: * registry: 拦截器注册器，用于添加和配置拦截器 * * Returns: * 无 * * Example: * registry.addInterceptor(interceptor).addPathPatterns("/**"); */ @Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(apiMonitorInterceptor) // 添加自定义拦截器 .addPathPatterns("/**"); // 拦截所有请求路径 } } ``` ## 4. Micrometer + Actuator 生产级方案 > 使用 Micrometer 指标框架 + Spring Actuator 暴露指标，接入 Prometheus + Grafana 实现可视化监控 前面几种方案适合开发调试和简单日志监控，但在生产环境中，我们需要持久化的指标存储和可视化看板。Micrometer 是 Spring Boot 官方推荐的指标采集框架，可以无缝对接 Prometheus、InfluxDB 等监控系统。 ### 4.1 引入依赖 ```xml org.springframework.boot spring-boot-starter-actuator io.micrometer micrometer-registry-prometheus ``` ### 4.2 配置 application.yml 配置文件中需要暴露Prometheus端点，并启用HTTP请求的百分位数直方图。 ```yaml spring: application: name: my-api-service # 应用名称，作为 Prometheus 指标的标签 management: endpoints: web: exposure: include: prometheus,metrics,health # 暴露 Prometheus、Metrics、Health 端点 metrics: tags: application: ${spring.application.name} # 为所有指标添加 application 标签 distribution: percentiles-histogram: http.server.requests: true # 为 HTTP 请求指标启用百分位数直方图 slo: http.server.requests: 10ms, 50ms, 100ms, 200ms, 500ms, 1s # 定义服务级别目标（SLO）的耗时边界 ``` ### 4.3 验证指标端点 启动应用后，访问 `http://localhost:8080/actuator/prometheus`，可以看到类似以下输出： ``` # HELP http_server_requests_seconds # TYPE http_server_requests_seconds summary http_server_requests_seconds_count{application="my-api-service",method="GET",outcome="SUCCESS",status="200",uri="/api/user/list"} 15.0 http_server_requests_seconds_sum{application="my-api-service",method="GET",outcome="SUCCESS",status="200",uri="/api/user/list"} 0.892 http_server_requests_seconds_max{application="my-api-service",method="GET",outcome="SUCCESS",status="200",uri="/api/user/list"} 0.124 ``` 指标含义： | 指标 | 含义 | |---|---| | http_server_requests_seconds_count | 接口调用总次数 | | http_server_requests_seconds_sum | 接口调用累计耗时（秒） | | http_server_requests_seconds_max | 接口调用最大耗时（秒） | ### 4.4 自定义业务指标 除了框架自动采集的HTTP指标，还可以自定义业务指标，比如按接口记录调用次数和耗时。下面这个切面专门用来做这件事： ```ja va package com.example.metrics; // 包名根据实际项目调整 import io.micrometer.core.instrument.Counter; // 引入 Micrometer 计数器，用于统计调用次数 import io.micrometer.core.instrument.MeterRegistry; // 引入 MeterRegistry，Micrometer 指标注册中心 import io.micrometer.core.instrument.Timer; // 引入 Micrometer 计时器，用于统计耗时 import lombok.extern.slf4j.Slf4j; // 引入 Slf4j 注解 import org.aspectj.lang.ProceedingJoinPoint; // 引入 ProceedingJoinPoint import org.aspectj.lang.annotation.Around; // 引入环绕通知注解 import org.aspectj.lang.annotation.Aspect; // 引入切面注解 import org.aspectj.lang.annotation.Pointcut; // 引入切点注解 import org.springframework.stereotype.Component; // 引入 Component 注解 import ja va.util.concurrent.TimeUnit; // 引入 TimeUnit，用于时间单位转换 /** * Micrometer 自定义指标切面 * * 功能：统计每个接口的调用次数和耗时，以 Prometheus 指标格式暴露 * * Args: * 无 * * Returns: * 无（指标数据自动注册到 MeterRegistry） * * Example: * 结合 Actuator + Prometheus + Grafana 实现可视化监控 */ @Slf4j @Aspect @Component public class MicrometerMetricsAspect { private final MeterRegistry meterRegistry; // Micrometer 指标注册中心，用于创建和管理指标 /** * 构造方法注入 MeterRegistry * * Args: * meterRegistry: Spring Boot 自动配置的 MeterRegistry 实例 * * Returns: * 无 */ public MicrometerMetricsAspect(MeterRegistry meterRegistry) { this.meterRegistry = meterRegistry; } /** * 定义切点：拦截所有 Controller 方法 */ @Pointcut("execution(* com.example.controller.*.*(..))") public void controllerPointcut() {} /** * 环绕通知：采集接口调用次数和耗时指标 * * Args: * joinPoint: 连接点对象 * * Returns: * Object: 目标方法的返回值 */ @Around("controllerPointcut()") public Object recordMetrics(ProceedingJoinPoint joinPoint) throws Throwable { // 获取接口名称，用于指标标签 String methodName = joinPoint.getTarget().getClass().getSimpleName() + "." + joinPoint.getSignature().getName(); // 创建计时器：统计该接口的耗时分布 // 数据流动：Timer.Sample 记录开始 → 方法执行 → sample.stop() 记录结束 → 指标注册到 Prometheus Timer.Sample sample = Timer.start(meterRegistry); try { // 执行目标方法 Object result = joinPoint.proceed(); return result; } finally { // 停止计时器，并将指标注册到 MeterRegistry // 数据流动：sample.stop(timer) → /actuator/prometheus 暴露 → Prometheus 采集 → Grafana 展示 sample.stop(Timer.builder("api.call.duration") // 指标名称 .description("接口调用耗时") // 指标描述 .tag("method", methodName) // 标签：接口方法名 .tag("class", joinPoint.getTarget().getClass().getSimpleName()) // 标签：类名 .register(meterRegistry)); // 注册到 MeterRegistry // 增加调用次数计数器 // 数据流动：Counter.increment() → 指标值 +1 → Prometheus 采集 Counter counter = Counter.builder("api.call.count") // 指标名称 .description("接口调用次数") // 指标描述 .tag("method", methodName) // 标签：接口方法名 .register(meterRegistry); // 注册到 MeterRegistry counter.increment(); // 计数器加 1 } } } ``` 配置完成后，`/actuator/prometheus` 端点会额外输出自定义指标： ``` # HELP api_call_duration_seconds 接口调用耗时 # TYPE api_call_duration_seconds summary api_call_duration_seconds_count{method="UserController.getUserList",} 5.0 api_call_duration_seconds_sum{method="UserController.getUserList",} 0.345 # HELP api_call_count_total 接口调用次数 # TYPE api_call_count_total counter api_call_count_total{method="UserController.getUserList",} 5.0 ``` ## 5. 基于事件监听方案 > 使用 Spring 框架的 ServletRequestHandledEvent 事件监听 HTTP 请求处理完成事件 Spring 框架在每次 HTTP 请求处理完成后会发布 `ServletRequestHandledEvent` 事件，包含了请求的详细信息。只需监听该事件即可获取接口耗时，无需任何切面或拦截器配置。 **注意**：此方案只能获取耗时和基本请求信息（URL、方法、状态码），**无法获取传入参数和返回参数**。 ```ja va package com.example.listener; // 包名根据实际项目调整 import lombok.extern.slf4j.Slf4j; // 引入 Slf4j 注解 import org.springframework.context.ApplicationListener; // 引入 ApplicationListener 接口 import org.springframework.stereotype.Component; // 引入 Component 注解 import org.springframework.web.context.support.ServletRequestHandledEvent; // 引入请求处理事件类 /** * 请求耗时事件监听器 * * 功能：监听 ServletRequestHandledEvent 事件，记录每个接口的调用耗时 * 注意：此方案无法获取请求参数和返回参数，仅能获取 URL、方法、耗时 * * Args: * 无 * * Returns: * 无（通过 log 输出监控信息） * * Example: * 自动生效，无需额外配置 */ @Slf4j @Component public class RequestTimeEventListener implements ApplicationListener { /** * 事件处理方法：ServletRequestHandledEvent 发布时自动调用 * * Args: * event: ServletRequestHandledEvent 事件对象，包含请求的 URL、方法、耗时、客户端地址等信息 * * Returns: * 无 * * Example: * 请求完成后自动触发，输出： * "clientAddress=127.0.0.1, requestUrl=/api/user/list, method=GET, costTime=45ms" */ @Override public void onApplicationEvent(ServletRequestHandledEvent event) { // 获取客户端 IP 地址，示例："127.0.0.1" String clientAddress = event.getClientAddress(); // 获取请求 URL，示例："/api/user/list" String requestUrl = event.getRequestUrl(); // 获取 HTTP 方法类型，示例："GET"、"POST" String method = event.getMethod(); // 获取请求处理耗时，单位：毫秒 // 数据流动：Spring 框架自动计时 → event.getProcessingTimeMillis() → 输出日志 long processingTimeMillis = event.getProcessingTimeMillis(); // 获取失败原因（如果有异常） Throwable failureCause = event.getFailureCause(); String failureMessage = failureCause == null ? "" : failureCause.getMessage(); // 根据是否有异常，分别输出不同级别的日志 if (failureCause == null) { // 请求成功：输出 INFO 级别日志 log.info("clientAddress={}, requestUrl={}, method={}, costTime={}ms", clientAddress, requestUrl, method, processingTimeMillis); } else { // 请求失败：输出 ERROR 级别日志，包含异常信息 log.error("clientAddress={}, requestUrl={}, method={}, costTime={}ms, error={}", clientAddress, requestUrl, method, processingTimeMillis, failureMessage); } } } ``` ## 6. 方案对比与总结 | 特性 | AOP 切面 | 自定义注解 | HandlerInterceptor | Micrometer + Actuator | 事件监听 | |---|---|---|---|---|---| | 调用次数 | ✅ | ✅ | ✅ | ✅（自动采集） | ❌ | | 传入参数 | ✅ | ✅ | ✅（仅 URL 参数） | ❌ | ❌ | | 返回参数 | ✅ | ✅ | ❌ | ❌ | ❌ | | 响应耗时 | ✅ | ✅ | ✅ | ✅（自动采集） | ✅ | | 代码入侵 | 无 | 需加注解 | 无 | 需自定义指标 | 无 | | 生产可用 | 开发调试 | 开发调试 | 开发调试 | ✅ 生产级 | 轻量监控 | | 可视化 | ❌（日志） | ❌（日志） | ❌（日志） | ✅（Grafana） | ❌（日志） | | 实现难度 | ⭐⭐ | ⭐⭐ | ⭐ | ⭐⭐⭐ | ⭐ | ### 场景推荐 | 场景 | 推荐方案 | |---|---| | 开发/测试环境临时统计 | AOP 切面（方案 1） | | 只监控关键接口 | 自定义注解（方案 2） | | 需要请求参数+返回参数完整记录 | AOP 切面（方案 1） | | 只需监控 HTTP 请求基本信息 | HandlerInterceptor（方案 3） | | 生产环境可视化监控大屏 | Micrometer + Prometheus + Grafana（方案 4） | | 最轻量级、零配置 | 事件监听（方案 5） | ### 实际项目建议 在实际项目中，通常组合使用多种方案： 1. **生产环境**以 Micrometer + Prometheus + Grafana 为基础监控设施，用于实时告警和历史趋势分析 2. **开发测试阶段**辅以 AOP 切面记录详细的请求参数和返回参数，方便定位问题 3. **关键业务接口**（如支付、登录）使用自定义注解进行重点监控 这种分层监控策略既能满足生产环境的稳定性要求，又能提供足够的调试信息，是大型 SpringBoot 项目的推荐实践。