SpringBoot使用AOP优雅的实现系统操作日志的持久化！

基于AOP+Spring实现操作日志记录：从设计到落地全指南

在日常开发中，操作日志是系统不可或缺的一部分——它用于追溯用户行为、排查问题、审计安全操作。但如果在每个业务方法中硬编码日志逻辑，会导致代码耦合度高、重复工作量大、维护困难。本文将基于 AOP（面向切面编程） 思想，结合Spring生态，实现一套“业务与日志解耦、可复用、易扩展”的操作日志方案，附完整代码和关键问题解决方案。
一、方案背景与核心设计

1.1 为什么选择AOP？

传统日志实现的痛点：

• 日志逻辑与业务逻辑混杂（如每个Service方法都写“记录日志”代码）；
  
• 新增日志需求时，需修改所有相关业务代码；
  
• 日志格式/内容调整时，全局修改成本高。
  

AOP的优势恰好解决这些问题：

• 解耦：日志逻辑作为“切面”独立存在，不侵入业务代码；
  
• 复用：通过“切点”批量拦截目标方法，统一日志逻辑；
  
• 灵活：新增/修改日志规则时，只需调整切面，无需改动业务。
  

1.2 核心架构设计

本方案采用“注解标记+AOP拦截+接口解耦+数据库存储”的架构，避免模块间循环依赖，同时保证扩展性。架构图如下：
flowchart TD    A[Aspect
（切面）] --> P[Pointcut
（切点）]    A --> Ad[Advice
（处理）]    A --> W[Weaving
（织入）]    W --> T[Target
（目标对象）]    T --> JP[joinPoint
（连接点）]        P --> E[execution
（路径表达式）]    P --> An[annotation
（注解）]    An --> SysA[系统注解]    An --> CusA[自定义注解]        Ad --> Time[处理时机]    Ad --> Content[处理内容]    Time --> Before[Before
（前置处理）]    Time --> After[After
（后置处理）]    Time --> Around[Around
（环绕处理）]    Time --> AfterReturning[AfterReturning
（后置返回通知）]    Time --> AfterThrowing[AfterThrowing
（异常抛出通知）]各组件职责：

• @OperationLog注解：标记需要记录日志的业务方法，指定“操作模块”“操作描述”；
  
• AOP切面（OperationLogAspect）：拦截注解标记的方法，收集请求IP、方法信息、参数、耗时等；
  
• LogHandler接口：定义日志保存规范，解耦Common模块与业务模块（避免循环依赖）；
  
• SysOperationLog实体：封装日志数据，映射数据库表；
  
• 数据库表：持久化存储日志数据。
  

二、环境准备

需引入的核心依赖（Spring Boot项目为例）：

1. <dependency>
2.     <groupId>org.springframework.boot</groupId>
3.     spring-boot-starter-aop</artifactId>
4. </dependency>
6. <dependency>
7.     <groupId>org.mybatis.spring.boot</groupId>
8.     mybatis-spring-boot-starter</artifactId>
9.     <version>2.3.0</version>
10. </dependency>
12. <dependency>
13.     <groupId>org.projectlombok</groupId>
14.     lombok</artifactId>
15.     <optional>true</optional>
16. </dependency>
18. <dependency>
19.     <groupId>com.mysql</groupId>
20.     mysql-connector-j</artifactId>
21.     <scope>runtime</scope>
22. </dependency>
24. <dependency>
25.     <groupId>org.mybatis</groupId>
26.     mybatis-typehandlers-jsr310</artifactId>
27.     <version>1.0.1</version>
28. </dependency>

复制代码

三、分步实现详解

3.1 步骤1：自定义操作日志注解（@OperationLog）

通过注解标记需要记录日志的方法，并携带“操作模块”“操作描述”等元信息（放在Common公共模块）。

1. import java.lang.annotation.*;
3. /**
4. * 自定义操作日志注解：标记需要记录日志的方法
5. */
6. @Target({ElementType.METHOD}) // 仅作用于方法
7. @Retention(RetentionPolicy.RUNTIME) // 运行时生效（AOP需动态获取注解信息）
8. @Documented // 生成JavaDoc时包含该注解
9. public @interface OperationLog {
10.     /** 操作模块（如：用户管理、订单处理） */
11.     String module() default "";
13.     /** 操作描述（如：新增用户、删除订单） */
14.     String description() default "";
15. }

复制代码

3.2 步骤2：定义日志实体类（SysOperationLog）

封装日志的所有字段，与数据库表sys_operation_log一一对应（放在Common模块）。

1. import lombok.Data;
2. import java.time.LocalDateTime;
4. /**
5. * 操作日志实体类：映射数据库表sys_operation_log
6. */
7. @Data // Lombok自动生成getter/setter/toString
8. public class SysOperationLog {
9.     /** 日志ID（自增主键） */
10.     private Long id;
11.     /** 操作用户（用户名/账号） */
12.     private String username;
13.     /** 操作时间 */
14.     private LocalDateTime operationTime;
15.     /** 操作模块（如：用户管理） */
16.     private String module;
17.     /** 操作描述（如：新增用户） */
18.     private String description;
19.     /** 操作方法全路径（如：com.example.service.UserService.addUser） */
20.     private String method;
21.     /** 方法参数（JSON格式） */
22.     private Object params;
23.     /** 操作结果（成功/失败，JSON格式） */
24.     private Object result;
25.     /** 异常信息（失败时记录） */
26.     private String exception;
27.     /** 操作耗时（毫秒） */
28.     private Long costTime;
29.     /** 客户端IP */
30.     private String clientIp;
31. }

复制代码

3.3 步骤3：定义日志处理接口（LogHandler）

为避免Common模块直接依赖业务模块（导致循环依赖），通过接口定义日志保存规范，业务模块实现该接口（放在Common模块）。

1. import com.wuxi.common.log.entity.SysOperationLog;
3. /**
4. * 日志处理接口：Common模块定义规范，业务模块实现具体逻辑
5. * 作用：解耦Common与业务模块，避免循环依赖
6. */
7. public interface LogHandler {
8.     /**
9.      * 保存操作日志
10.      * @param sysOperationLog 日志实体
11.      */
12.     void saveOperationLog(SysOperationLog sysOperationLog);
13. }

复制代码

3.4 步骤4：实现AOP切面核心逻辑（OperationLogAspect）

AOP切面是日志收集的核心，负责拦截注解标记的方法、收集日志信息、调用LogHandler保存日志（放在Common模块）。

1. import lombok.RequiredArgsConstructor;
2. import lombok.extern.slf4j.Slf4j;
3. import org.aspectj.lang.ProceedingJoinPoint;
4. import org.aspectj.lang.annotation.Around;
5. import org.aspectj.lang.annotation.Aspect;
6. import org.aspectj.lang.annotation.Pointcut;
7. import org.aspectj.lang.reflect.MethodSignature;
8. import org.springframework.web.context.request.RequestContextHolder;
9. import org.springframework.web.context.request.ServletRequestAttributes;
11. import javax.servlet.http.HttpServletRequest;
12. import java.lang.reflect.Method;
13. import java.time.LocalDateTime;
14. import java.util.Arrays;
16. /**
17. * 操作日志AOP切面：核心日志收集逻辑
18. */
19. @Slf4j // Lombok自动生成日志对象
20. @Aspect // 标记为AOP切面
21. @Component // 纳入Spring容器管理
22. @RequiredArgsConstructor // Lombok自动生成构造函数，注入LogHandler
23. public class OperationLogAspect {
25.     // 注入日志处理接口（业务模块实现），避免依赖具体业务
26.     private final LogHandler logHandler;
28.     /**
29.      * 定义切点：拦截所有添加@OperationLog注解的方法
30.      */
31.     @Pointcut("@annotation(com.wuxi.common.log.annotation.OperationLog)")
32.     public void logPointCut() {}
34.     /**
35.      * 环绕通知：在方法执行前后拦截，收集日志信息
36.      * 优势：可获取方法执行前（如开始时间）、执行后（如结果、耗时）、异常信息
37.      */
38.     @Around("logPointCut()")
39.     public Object around(ProceedingJoinPoint joinPoint) throws Throwable {
40.         // 1. 记录方法开始时间（用于计算耗时）
41.         long startTime = System.currentTimeMillis();
43.         // 2. 初始化日志实体
44.         SysOperationLog logEntity = new SysOperationLog();
45.         logEntity.setOperationTime(LocalDateTime.now()); // 操作时间
47.         // 3. 获取客户端IP（从请求上下文获取）
48.         ServletRequestAttributes requestAttributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
49.         if (requestAttributes != null) {
50.             HttpServletRequest request = requestAttributes.getRequest();
51.             logEntity.setClientIp(request.getRemoteAddr()); // 客户端IP
52.         }
54.         // 4. 获取方法信息（全路径、参数）
55.         MethodSignature signature = (MethodSignature) joinPoint.getSignature();
56.         Method method = signature.getMethod();
57.         // 方法全路径：包名+类名+方法名
58.         logEntity.setMethod(method.getDeclaringClass().getName() + "." + method.getName());
59.         // 方法参数：数组转字符串（后续需序列化为JSON）
60.         logEntity.setParams(Arrays.toString(joinPoint.getArgs()));
62.         // 5. 获取@OperationLog注解信息（模块、描述）
63.         OperationLog operationLog = method.getAnnotation(OperationLog.class);
64.         logEntity.setModule(operationLog.module());
65.         logEntity.setDescription(operationLog.description());
67.         // 6. 获取操作用户（从登录上下文获取，如Spring Security）
68.         logEntity.setUsername(getCurrentUsername());
70.         Object businessResult = null; // 业务方法返回结果
71.         try {
72.             // 执行目标业务方法（核心业务逻辑）
73.             businessResult = joinPoint.proceed();
74.             // 方法执行成功：标记结果
75.             logEntity.setResult("成功");
76.             // 若需记录业务返回结果，可序列化后赋值：logEntity.setResult(JSON.toJSONString(businessResult));
77.         } catch (Exception e) {
78.             // 方法执行失败：记录异常信息
79.             logEntity.setResult("失败");
80.             logEntity.setException(e.getMessage()); // 异常信息（简化，可记录堆栈）
81.             throw e; // 重新抛出异常，不影响原有业务异常处理逻辑
82.         } finally {
83.             // 7. 计算操作耗时（结束时间-开始时间）
84.             logEntity.setCostTime(System.currentTimeMillis() - startTime);
86.             // 8. 保存日志（调用业务模块实现的LogHandler）
87.             saveOperationLog(logEntity);
88.         }
90.         // 返回业务方法结果，不影响业务流程
91.         return businessResult;
92.     }
94.     /**
95.      * 从登录上下文获取当前用户（实际项目需替换为真实逻辑）
96.      * 示例：Spring Security可通过SecurityContextHolder获取
97.      */
98.     private String getCurrentUsername() {
99.         // 模拟：从自定义UserContext获取（实际项目需实现上下文管理）
100.         String currentUser = UserContext.getUser();
101.         // 若未获取到用户（如系统操作），默认赋值为"system"
102.         return currentUser == null ? "system" : currentUser;
103.     }
105.     /**
106.      * 调用LogHandler保存日志，捕获异常避免影响主业务
107.      */
108.     private void saveOperationLog(SysOperationLog logEntity) {
109.         try {
110.             logHandler.saveOperationLog(logEntity);
111.         } catch (Exception e) {
112.             // 日志保存失败不影响主业务，仅记录日志告警
113.             log.error("记录系统操作日志失败，日志信息：{}", logEntity, e);
114.             // 若日志为核心审计需求，可抛出自定义异常：throw new DbException("记录日志失败", e);
115.         }
116.     }
117. }

复制代码

3.5 步骤5：数据库表设计（sys_operation_log）

创建日志存储表，字段与SysOperationLog实体对应，添加索引优化查询（如按时间、用户查询）。

1. CREATE TABLE `sys_operation_log` (
2.   `id` bigint NOT NULL AUTO_INCREMENT COMMENT '日志ID（自增主键）',
3.   `username` varchar(50) NOT NULL COMMENT '操作用户',
4.   `operation_time` datetime NOT NULL COMMENT '操作时间',
5.   `module` varchar(100) NOT NULL COMMENT '操作模块（如：用户管理）',
6.   `description` varchar(255) DEFAULT NULL COMMENT '操作描述（如：新增用户）',
7.   `method` varchar(255) NOT NULL COMMENT '操作方法全路径',
8.   `params` text COMMENT '方法参数（JSON格式）',
9.   `result` text COMMENT '操作结果（成功/失败，JSON格式）',
10.   `exception` text COMMENT '异常信息（失败时记录）',
11.   `cost_time` bigint DEFAULT NULL COMMENT '操作耗时（毫秒）',
12.   `client_ip` varchar(50) DEFAULT NULL COMMENT '客户端IP',
13.   PRIMARY KEY (`id`),
14.   KEY `idx_operation_time` (`operation_time`) COMMENT '按操作时间查询索引',
15.   KEY `idx_username` (`username`) COMMENT '按用户查询索引'
16. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='系统操作日志表';

复制代码

3.6 步骤6：实现LogHandler接口（业务模块）

在业务模块（如用户服务、订单服务）中实现LogHandler接口，调用MyBatis将日志插入数据库（避免Common模块依赖业务）。

1. import com.wuxi.common.log.entity.SysOperationLog;
2. import com.wuxi.common.log.handler.LogHandler;
3. import com.wuxi.user.mapper.SysOperationLogMapper;
4. import lombok.RequiredArgsConstructor;
5. import org.springframework.stereotype.Component;
6. import com.alibaba.fastjson.JSON; // 需引入FastJSON依赖
8. /**
9. * 日志处理实现类：业务模块实现，负责将日志插入数据库
10. */
11. @Component
12. @RequiredArgsConstructor
13. public class LogHandlerImpl implements LogHandler {
15.     // 注入MyBatis Mapper（操作数据库）
16.     private final SysOperationLogMapper sysOperationLogMapper;
18.     @Override
19.     public void saveOperationLog(SysOperationLog sysOperationLog) {
20.         // 关键：将Object类型的params/result序列化为JSON字符串（适配数据库text类型）
21.         if (sysOperationLog.getParams() != null) {
22.             sysOperationLog.setParams(JSON.toJSONString(sysOperationLog.getParams()));
23.         }
24.         if (sysOperationLog.getResult() != null) {
25.             sysOperationLog.setResult(JSON.toJSONString(sysOperationLog.getResult()));
26.         }
28.         // 调用MyBatis Mapper插入数据库
29.         sysOperationLogMapper.insert(sysOperationLog);
30.     }
31. }

复制代码

3.7 步骤7：MyBatis映射（插入日志）

编写MyBatis Mapper接口和XML映射文件，实现日志插入逻辑。
7.1 Mapper接口

1. import com.wuxi.common.log.entity.SysOperationLog;
2. import org.apache.ibatis.annotations.Insert;
3. import org.apache.ibatis.annotations.Options;
5. /**
6. * 操作日志MyBatis Mapper
7. */
8. public interface SysOperationLogMapper {
10.     /**
11.      * 插入操作日志
12.      * @Options：自增主键回写（将数据库生成的id赋值给实体类的id字段）
13.      */
14.     @Insert("INSERT INTO sys_operation_log (" +
15.             "username, operation_time, module, description, method, " +
16.             "params, result, exception, cost_time, client_ip" +
17.             ") VALUES (" +
18.             "#{username}, #{operationTime}, #{module}, #{description}, #{method}, " +
19.             "#{params}, #{result}, #{exception}, #{costTime}, #{clientIp}" +
20.             ")")
21.     @Options(useGeneratedKeys = true, keyProperty = "id")
22.     int insert(SysOperationLog sysOperationLog);
23. }

复制代码

7.2 （可选）XML映射文件

若偏好XML配置，可替换为以下方式（SysOperationLogMapper.xml）：

1. <?xml version="1.0" encoding="UTF-8"?>
2. <!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
3. <mapper namespace="com.wuxi.user.mapper.SysOperationLogMapper">
5.    
6.     <insert id="insert" parameterType="com.wuxi.common.log.entity.SysOperationLog"
7.             useGeneratedKeys="true" keyProperty="id">
8.         INSERT INTO sys_operation_log (
9.             username, operation_time, module, description, method,
10.             params, result, exception, cost_time, client_ip
11.         ) VALUES (
12.             #{username}, #{operationTime}, #{module}, #{description}, #{method},
13.             #{params}, #{result}, #{exception}, #{costTime}, #{clientIp}
14.         )
15.     </insert>
17. </mapper>

复制代码

四、实际使用示例

在业务方法上添加@OperationLog注解，即可自动记录日志，无需额外编写日志代码。

1. import com.wuxi.common.log.annotation.OperationLog;
2. import com.wuxi.user.entity.User;
3. import com.wuxi.user.service.UserService;
4. import lombok.RequiredArgsConstructor;
5. import org.springframework.web.bind.annotation.PostMapping;
6. import org.springframework.web.bind.annotation.RequestBody;
7. import org.springframework.web.bind.annotation.RestController;
9. @RestController
10. @RequiredArgsConstructor
11. public class UserController {
13.     private final UserService userService;
15.     /**
16.      * 新增用户接口：添加@OperationLog注解，自动记录日志
17.      */
18.     @PostMapping("/user/add")
19.     @OperationLog(module = "用户管理", description = "新增用户")
20.     public String addUser(@RequestBody User user) {
21.         userService.saveUser(user);
22.         return "新增用户成功";
23.     }
25.     /**
26.      * 删除用户接口：记录日志
27.      */
28.     @PostMapping("/user/delete")
29.     @OperationLog(module = "用户管理", description = "删除用户")
30.     public String deleteUser(Long userId) {
31.         userService.deleteUser(userId);
32.         return "删除用户成功";
33.     }
34. }

复制代码

五、关键问题与解决方案

5.1 如何避免循环依赖？

问题：Common模块需调用业务模块的日志保存逻辑，若Common直接依赖业务模块，会形成“Common→业务→Common”的循环依赖。
解决方案：接口解耦

• Common模块定义LogHandler接口，不依赖业务；
  
• 业务模块实现LogHandler接口，依赖Common模块；
  
• 最终依赖链：业务模块→Common模块（单向依赖，无循环）。
  

5.2 Object类型参数/结果如何存储？

问题：SysOperationLog的params和result是Object类型，数据库是text类型，直接存储会报错。
解决方案：JSON序列化
使用FastJSON/Jackson将Object序列化为JSON字符串，存储到数据库（如LogHandlerImpl中JSON.toJSONString()）。
5.3 LocalDateTime与MySQL datetime映射问题？

问题：Java 8的LocalDateTime与MySQL的datetime类型默认不兼容，会报类型转换错误。
解决方案：

• 引入mybatis-typehandlers-jsr310依赖（已在环境准备中添加）；
  
• MyBatis自动识别该类型处理器，无需额外配置。
  

5.4 日志保存失败影响主业务？

问题：若数据库异常导致日志保存失败，不能阻断核心业务流程。
解决方案：异常隔离
在AOP的saveOperationLog方法中捕获异常，仅记录告警日志，不抛出异常（除非是核心审计日志，需强制记录）。
六、方案优化方向

• 异步保存日志：通过@Async注解异步执行日志保存，避免日志操作阻塞主业务（需开启Spring异步支持@EnableAsync）；
  
• 日志脱敏：对敏感参数（如密码、手机号）进行脱敏处理后再存储（如用***替换中间字符）；
  
• 日志分表：日志数据量较大时，按时间分表（如每月一张表），提升查询性能；
  
• 分布式日志：微服务场景下，可将日志发送到ELK（Elasticsearch+Logstash+Kibana），实现日志集中查询与分析。
  

七、总结

本文基于AOP+Spring实现的操作日志方案，核心优势在于：

• 解耦：日志逻辑与业务逻辑完全分离，无侵入；
  
• 可扩展：新增日志字段或修改保存逻辑，只需调整切面或LogHandler实现；
  
• 易用性：业务方法只需添加注解，即可自动记录日志。
  

该方案适用于单体应用和微服务架构，可根据实际需求扩展异步、脱敏、分表等功能，是企业级系统操作日志的最佳实践之一。

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！