SpringBoot 中 AOP 实现日志记录（操作日志）

上一篇我们吃透了 Spring AOP 的四大核心概念切面、通知、切点、织入很多同学留言说“概念懂了但还是不知道怎么落地”。今天就来讲讲Spring AOP最实用的实战场景——用 SpringBoot AOP 实现操作日志记录。操作日志是项目必备功能比如用户登录、接口调用、数据新增/修改/删除都需要记录操作人、操作时间、操作内容、接口地址等信息方便后续排查问题、审计追溯。一、明确操作日志要记录哪些信息先梳理操作日志的核心字段避免后续代码遗漏实战中可根据项目需求增减这里给出通用模板• 操作人当前登录用户的用户名/ID实战中结合 Spring Security 或 Token 获取• 操作时间接口执行的时间精确到毫秒• 操作模块比如“用户管理”“订单管理”“商品管理”标记当前操作属于哪个模块• 操作描述比如“新增用户”“删除订单”“查询商品列表”清晰说明操作内容• 接口地址被调用的接口 URL比如 /api/user/add• 请求方式GET/POST/PUT/DELETE• 请求参数接口接收的参数JSON 格式• 返回结果接口返回的数据JSON 格式• 执行状态成功/失败• 异常信息如果接口执行失败记录异常详情便于排查• 操作 IP调用接口的客户端 IP 地址。二、从零实现 AOP 操作日志步骤1搭建基础环境导入依赖SpringBoot 项目中实现 AOP 只需导入 spring-boot-starter-aop 依赖无需额外导入其他包在 pom.xml 中添加!-- Spring AOP 依赖 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-aop/artifactId /dependency !-- 工具包用于 JSON 格式化、IP 地址获取可选简化代码 -- dependency groupIdcom.alibaba/groupId artifactIdfastjson2/artifactId version2.0.32/version /dependency !-- 用于获取客户端 IP可选也可自己写工具类 -- dependency groupIdeu.bitwalker/groupId artifactIdUserAgentUtils/artifactId version1.21/version /dependency说明fastjson2 用于将请求参数、返回结果转为 JSON 字符串UserAgentUtils 用于获取客户端 IP 和浏览器信息可根据需求选择是否导入。步骤2创建操作日志实体类存储日志数据创建实体类 OperationLog对应操作日志的核心字段后续可直接映射到数据库这里省略数据库操作重点放在 AOP 实现import lombok.Data; import java.time.LocalDateTime; /** * 操作日志实体类 */ Data public class OperationLog { // 主键实战中可自增 private Long id; // 操作人用户名/ID private String operator; // 操作时间 private LocalDateTime operationTime; // 操作模块 private String module; // 操作描述 private String description; // 接口地址 private String requestUrl; // 请求方式 private String requestMethod; // 请求参数JSON 格式 private String requestParams; // 返回结果JSON 格式 private String responseResult; // 执行状态0-失败1-成功 private Integer status; // 异常信息失败时填写 private String errorMsg; // 操作 IP private String operationIp; }说明用 Data 注解lombok简化 getter/setter 方法实战中需导入 lombok 依赖如果未导入。步骤3创建自定义注解精准定位需要记录日志的接口我们用「自定义注解」来标记需要记录操作日志的接口这样可以灵活控制哪些接口需要记录日志哪些不需要——比直接用切点表达式匹配包/类更灵活。import java.lang.annotation.*; /** * 自定义操作日志注解 * Target注解作用范围METHOD作用在方法上 * Retention注解保留时机RUNTIME运行时保留AOP 可获取 * Documented生成文档时包含该注解 */ Target(ElementType.METHOD) // 只作用于方法 Retention(RetentionPolicy.RUNTIME) // 运行时生效 Documented public interface OperationLogAnnotation { // 操作模块必填比如“用户管理” String module() default ; // 操作描述必填比如“新增用户” String description() default ; }说明该注解有两个属性module操作模块和 description操作描述在需要记录日志的接口方法上添加该注解并填写对应属性即可。步骤4创建 AOP 切面实现日志记录这是本次实战的核心创建切面类定义切点匹配带有 OperationLogAnnotation 注解的方法、通知环绕通知实现日志记录逻辑完成日志的收集和处理。import com.alibaba.fastjson2.JSON; import eu.bitwalker.useragentutils.UserAgent; import org.aspectj.lang.ProceedingJoinPoint; import org.aspectj.lang.annotation.Around; import org.aspectj.lang.annotation.Aspect; import org.aspectj.lang.annotation.Pointcut; import org.aspectj.lang.reflect.MethodSignature; import org.springframework.stereotype.Component; import org.springframework.web.context.request.RequestContextHolder; import org.springframework.web.context.request.ServletRequestAttributes; import javax.servlet.http.HttpServletRequest; import java.lang.reflect.Method; import java.time.LocalDateTime; import java.util.Arrays; /** * 操作日志切面类 * Aspect标记此类为切面 * Component交给 Spring 管理让 Spring 扫描到该切面 */ Aspect Component public class OperationLogAspect { // 1. 定义切点匹配带有 OperationLogAnnotation 注解的方法 Pointcut(annotation(com.example.demo.annotation.OperationLogAnnotation)) public void operationLogPointcut() {} // 切点方法无实际逻辑仅用于标记 // 2. 定义环绕通知包裹切点方法可在方法执行前、执行后、异常时处理 Around(operationLogPointcut()) public Object recordOperationLog(ProceedingJoinPoint joinPoint) throws Throwable { // 1. 初始化操作日志对象 OperationLog operationLog new OperationLog(); // 2. 获取当前请求对象用于获取请求信息URL、请求方式、IP 等 ServletRequestAttributes attributes (ServletRequestAttributes) RequestContextHolder.getRequestAttributes(); HttpServletRequest request attributes.getRequest(); // 3. 填充日志基础信息无论接口成功/失败都需要记录 // 3.1 获取操作人实战中需结合 Spring Security/Token 获取这里模拟 admin operationLog.setOperator(admin); // 3.2 操作时间当前时间 operationLog.setOperationTime(LocalDateTime.now()); // 3.3 接口地址 operationLog.setRequestUrl(request.getRequestURI()); // 3.4 请求方式GET/POST operationLog.setRequestMethod(request.getMethod()); // 3.5 操作 IP获取客户端真实 IP operationLog.setOperationIp(getClientIp(request)); // 3.6 请求参数将方法参数转为 JSON 字符串 Object[] args joinPoint.getArgs(); operationLog.setRequestParams(JSON.toJSONString(args)); // 4. 获取自定义注解的属性模块、描述 MethodSignature signature (MethodSignature) joinPoint.getSignature(); Method method signature.getMethod(); OperationLogAnnotation annotation method.getAnnotation(OperationLogAnnotation.class); operationLog.setModule(annotation.module()); operationLog.setDescription(annotation.description()); // 5. 执行目标方法核心业务逻辑捕获执行结果和异常 Object result null; try { // 执行目标方法比如接口的核心逻辑 result joinPoint.proceed(); // 方法执行成功设置状态为 1成功记录返回结果 operationLog.setStatus(1); operationLog.setResponseResult(JSON.toJSONString(result)); } catch (Throwable throwable) { // 方法执行失败设置状态为 0失败记录异常信息 operationLog.setStatus(0); operationLog.setErrorMsg(throwable.getMessage()); // 抛出异常不影响原有业务逻辑的异常处理 throw throwable; } finally { // 6. 日志持久化实战中可存入数据库、ElasticSearch 等这里模拟打印 System.out.println(操作日志记录 JSON.toJSONString(operationLog, true)); // TODO: 实战中替换为数据库插入操作比如调用 OperationLogService.save(operationLog) } // 返回目标方法的执行结果不影响原有接口的返回值 return result; } /** * 工具方法获取客户端真实 IP处理代理场景比如 Nginx 代理 */ private String getClientIp(HttpServletRequest request) { String ip request.getHeader(x-forwarded-for); if (ip null || ip.length() 0 || unknown.equalsIgnoreCase(ip)) { ip request.getHeader(Proxy-Client-IP); } if (ip null || ip.length() 0 || unknown.equalsIgnoreCase(ip)) { ip request.getHeader(WL-Proxy-Client-IP); } if (ip null || ip.length() 0 || unknown.equalsIgnoreCase(ip)) { ip request.getRemoteAddr(); } // 处理多代理场景取第一个非 unknown 的 IP if (ip ! null ip.contains(,)) { ip ip.split(,)[0].trim(); } return ip; } }核心解读• 切点通过 annotation 匹配带有自定义注解的方法精准控制需要记录日志的接口• 环绕通知用 Around 包裹目标方法先收集请求信息、注解属性再执行目标方法最后处理日志成功/失败• IP 获取处理了 Nginx 代理等场景确保获取到客户端真实 IP• 异常处理捕获目标方法的异常记录异常信息同时重新抛出异常不影响原有业务的异常处理逻辑• 日志持久化这里用打印模拟实战中需替换为数据库插入、ES 存储等逻辑。步骤5接口测试验证日志记录效果创建一个测试接口添加自定义 OperationLogAnnotation 注解启动项目调用接口查看日志是否正常记录。import com.example.demo.annotation.OperationLogAnnotation; import org.springframework.web.bind.annotation.*; import java.util.HashMap; import java.util.Map; /** * 测试接口用户管理模块 */ RestController RequestMapping(/api/user) public class UserController { // 添加 OperationLogAnnotation 注解标记需要记录日志 OperationLogAnnotation(module 用户管理, description 新增用户) PostMapping(/add) public MapString, Object addUser(RequestBody MapString, String params) { // 模拟新增用户核心逻辑 MapString, Object result new HashMap(); result.put(code, 200); result.put(msg, 新增用户成功); result.put(data, params); return result; } // 测试异常场景 OperationLogAnnotation(module 用户管理, description 删除用户) DeleteMapping(/delete/{id}) public MapString, Object deleteUser(PathVariable Long id) { // 模拟异常比如删除不存在的用户 if (id 0) { throw new RuntimeException(用户ID非法无法删除); } MapString, Object result new HashMap(); result.put(code, 200); result.put(msg, 删除用户成功); return result; } }测试1调用新增用户接口请求地址http://localhost:8080/api/user/add请求方式POST请求参数{username:test,password:123456}控制台打印的日志格式化后操作日志记录{ description:新增用户, module:用户管理, operationIp:127.0.0.1, operationTime:2026-04-14T15:30:00, operator:admin, requestMethod:POST, requestParams:[{\password\:\123456\,\username\:\test\}], requestUrl:/api/user/add, responseResult:{\code\:200,\data\:{\password\:\123456\,\username\:\test\},\msg\:\新增用户成功\}, status:1 }测试2调用删除用户接口请求地址http://localhost:8080/api/user/delete/-1请求方式DELETE控制台打印的日志格式化后操作日志记录{ description:删除用户, errorMsg:用户ID非法无法删除, module:用户管理, operationIp:127.0.0.1, operationTime:2026-04-14T15:35:00, operator:admin, requestMethod:DELETE, requestParams:[-1], requestUrl:/api/user/delete/-1, responseResult:null, status:0 }验证结果两种场景的日志都正常记录包含了所有核心字段符合预期三、优化技巧上面的基础实现已经能满足大部分项目需求下面补充3个实战常用的优化点让日志功能更完善。优化1获取真实操作人替换模拟值实战中操作人不能用模拟的“admin”需结合 Spring Security 或 Token 解析获取当前登录用户// 结合 Spring Security 获取当前登录用户 Authentication authentication SecurityContextHolder.getContext().getAuthentication(); if (authentication ! null !(authentication.getPrincipal() instanceof String)) { UserDetails userDetails (UserDetails) authentication.getPrincipal(); operationLog.setOperator(userDetails.getUsername()); // 获取用户名 }优化2日志持久化存入数据库创建 OperationLogService 和 OperationLogMapper将日志对象存入数据库以 MyBatis-Plus 为例// 1. 注入 OperationLogService Autowired private OperationLogService operationLogService; // 2. 在 finally 中替换打印逻辑改为存入数据库 finally { operationLogService.save(operationLog); // MyBatis-Plus 自带的保存方法 }优化3忽略敏感参数避免日志泄露接口参数中可能包含密码、手机号等敏感信息需要忽略这些参数避免日志泄露可自定义注解拦截处理// 1. 自定义忽略敏感参数注解 Target(ElementType.FIELD) Retention(RetentionPolicy.RUNTIME) public interface IgnoreSensitive { } // 2. 在实体类敏感字段上添加注解 Data public class User { private Long id; private String username; IgnoreSensitive // 忽略密码字段 private String password; } // 3. 在切面中处理敏感参数替换为 **** // 核心逻辑反射获取字段判断是否有 IgnoreSensitive 注解有则替换值四、注意事项切面类忘记加 Component 注解❌ 错误做法只加 Aspect 标记切面忘记加 Component✅ 正确做法Aspect 只是标记切面必须加 Component 交给 Spring 管理否则 Spring 无法扫描到切面日志记录失效。环绕通知中忘记调用 joinPoint.proceed()❌ 错误做法只收集日志不执行目标方法导致接口无法正常返回✅ 正确做法必须调用 joinPoint.proceed() 执行目标方法同时接收返回结果否则核心业务逻辑无法执行。请求参数为 MultipartFile文件上传时JSON 格式化报错❌ 错误表现文件上传接口日志记录时JSON.toJSONString(args) 报错✅ 解决方案判断参数类型如果是 MultipartFile不进行 JSON 格式化直接标记为“文件上传”。文末小结用 SpringBoot AOP 实现操作日志核心就是“自定义注解标记接口 切面收集日志信息 环绕通知处理增强”全程无侵入式编码复用性极高。记住AOP 的核心是“解耦”把日志这种通用功能和核心业务逻辑分离既保证了核心代码的简洁又方便后续维护和扩展。如果你在实战中遇到问题比如切面不生效、IP 获取错误、敏感参数处理欢迎在评论区留言交流一起避坑、一起进步别忘了点赞在看收藏三连关注我解锁更多 SpringBoot 实战干货下期再见❤️