引言
在业务系统中,审计日志记录至关重要。系统需要记录用户的操作日志,特别是在用户操作数据库修改、查询、删除重要数据时,系统应追踪操作人的身份、操作的对象、操作的时间等关键数据。这不仅对运维、合规性有帮助,同时也能提高系统的可审计性和安全性。
本篇文章将深入讲解如何在 Spring Boot 中通过注解和拦截器实现审计日志功能。通过自定义注解,可以在不同模块、不同操作上灵活地记录审计信息,包括操作模块、操作对象属性、用户信息和 IP 地址。同时,这一方案具有高度的拓展性,可以适配于不同业务场景。
我们将以电商交易系统为案例进行详细说明,提供表结构设计和完整的代码示例。
1. 项目环境与依赖
在实现审计日志功能之前,我们需要确保项目的环境和依赖配置正确。本例使用的技术栈如下:
- Spring Boot 2.x
- Maven
- JDK 8+
- MySQL (用于存储审计日志)
- Lombok (简化 POJO 开发)
1.1 Maven 依赖
首先,在 pom.xml
文件中加入所需的依赖。主要包含 Spring Web、MyBatis 和 Lombok。
<dependencies>
<!-- Spring Boot Web Starter -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- MyBatis Starter -->
<dependency>
<groupId>org.mybatis.spring.boot</groupId>
<artifactId>mybatis-spring-boot-starter</artifactId>
<version>2.1.4</version>
</dependency>
<!-- Lombok -->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<scope>provided</scope>
</dependency>
<!-- MySQL Driver -->
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<scope>runtime</scope>
</dependency>
<!-- Spring Boot DevTools (for development) -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-devtools</artifactId>
<scope>runtime</scope>
</dependency>
</dependencies>
1.2 数据库配置
在 application.yml
中配置数据库连接信息。
spring:
datasource:
url: jdbc:mysql://localhost:3306/ecommerce_db?useSSL=false&serverTimezone=UTC
username: root
password: password
driver-class-name: com.mysql.cj.jdbc.Driver
mybatis:
mapper-locations: classpath:mapper/*.xml
type-aliases-package: com.example.ecommerce.model
2. 数据库表结构设计
为了记录审计日志,我们需要设计一个用于存储日志信息的数据库表。这里,我们设计一个 audit_logs
表,用于保存操作模块、操作的对象信息、操作用户、IP 地址等审计数据。
2.1 审计日志表 audit_logs
CREATE TABLE `audit_logs` (
`id` BIGINT PRIMARY KEY AUTO_INCREMENT,
`module_name` VARCHAR(255) NOT NULL, -- 操作模块
`object_id` VARCHAR(255) NOT NULL, -- 操作对象的ID(例如订单ID、用户ID等)
`object_detail` TEXT, -- 操作对象的详细信息(可选)
`operation` VARCHAR(255) NOT NULL, -- 操作类型,如创建、修改、删除
`user_id` BIGINT NOT NULL, -- 操作用户的ID
`username` VARCHAR(255) NOT NULL, -- 操作用户的名称
`ip_address` VARCHAR(50), -- 用户的IP地址
`created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP -- 记录时间
);
字段解释:
- module_name:记录操作发生在哪个模块,比如"订单模块"或"用户模块"。
- object_id:记录操作对象的主键 ID,如修改的是订单,记录订单 ID。
- object_detail:操作对象的详细信息,如订单的具体信息,方便后续审计。
- operation:记录用户的操作类型,如创建、修改、删除等。
- user_id 和 username:操作用户的信息。
- ip_address:用户操作时的 IP 地址。
- created_at:记录审计日志创建的时间。
3. 自定义注解 @AuditLog
3.1 注解设计
通过自定义注解 @AuditLog
,我们可以标记在需要记录日志的地方,比如在 Service 层或 Controller 层。注解的参数可以包括操作模块名、需要记录的对象属性等。
package com.example.ecommerce.annotation;
import java.lang.annotation.*;
/**
* 用于记录操作审计日志的自定义注解
*/
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface AuditLog {
/**
* 操作模块名称(如 "订单模块", "用户模块")
*/
String moduleName();
/**
* 操作类型(如 "创建", "修改", "删除")
*/
String operation();
/**
* 指定操作对象的属性(如 "orderId" 或 "userId")
*/
String objectId() default "id";
}
- moduleName:指定操作的模块名,便于区分日志来源。
- operation:操作类型,如创建、修改、删除等。
- objectId:用于标识操作对象的主键属性。
4. 实现审计日志拦截器
4.1 用户上下文 UserContext
首先我们创建一个用户上下文 UserContext
,用来保存当前用户的登录信息和 IP 地址。在实际应用中,用户登录信息一般是通过 JWT 或 Session 获取的,这里为了简化,假设这些信息已经存在。
package com.example.ecommerce.util;
public class UserContext {
private static final ThreadLocal<Long> userId = new ThreadLocal<>();
private static final ThreadLocal<String> username = new ThreadLocal<>();
private static final ThreadLocal<String> ipAddress = new ThreadLocal<>();
public static void setUserId(Long id) {
userId.set(id);
}
public static Long getUserId() {
return userId.get();
}
public static void setUsername(String name) {
username.set(name);
}
public static String getUsername() {
return username.get();
}
public static void setIpAddress(String ip) {
ipAddress.set(ip);
}
public static String getIpAddress() {
return ipAddress.get();
}
public static void clear() {
userId.remove();
username.remove();
ipAddress.remove();
}
}
4.2 审计日志拦截器
接下来,我们实现一个 Spring 的 HandlerInterceptor
拦截器,用于拦截带有 @AuditLog
注解的方法,并记录日志。
package com.example.ecommerce.interceptor;
import com.example.ecommerce.annotation.AuditLog;
import com.example.ecommerce.model.AuditLogRecord;
import com.example.ecommerce.service.AuditLogService;
import com.example.ecommerce.util.UserContext;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
import javax.servlet.http.HttpServletRequest;
import java.lang.reflect.Method;
/**
* 用于记录审计日志的拦截器
*/
@Aspect
@Component
public class AuditLogInterceptor {
@Autowired
private AuditLogService auditLogService;
@Autowired
private HttpServletRequest request;
@Around("@annotation(com.example.ecommerce.annotation.AuditLog)")
public Object logAudit(ProceedingJoinPoint joinPoint) throws Throwable {
Method method = getTargetMethod(joinPoint);
if (method == null) {
return joinPoint.proceed();
}
AuditLog auditLog = method.getAnnotation(AuditLog.class);
if (auditLog != null) {
// 获取用户信息和 IP 地址
Long userId = UserContext.getUserId();
String username = UserContext.getUsername();
String ipAddress = request.getRemoteAddr();
// 获取操作对象的ID
Object[] args = joinPoint.getArgs();
String objectId = getObjectId(args, auditLog.objectId());
// 执行目标方法
Object result = joinPoint.proceed();
// 创建日志记录
AuditLogRecord record = new AuditLogRecord();
record.setModuleName(auditLog.moduleName());
record.setOperation(auditLog.operation());
record.setUserId(userId);
record.setUsername(username);
record.setIpAddress(ipAddress);
record.setObjectId(objectId);
// 保存日志
auditLogService.saveLog(record);
return result;
}
return joinPoint.proceed();
}
private Method getTargetMethod(ProceedingJoinPoint joinPoint) {
Method method = null;
try {
method = joinPoint.getTarget().getClass().getMethod(joinPoint.getSignature().getName(),
((MethodSignature) joinPoint.getSignature()).getParameterTypes());
} catch (NoSuchMethodException e) {
e.printStackTrace();
}
return method;
}
private String getObjectId(Object[] args, String objectIdField) {
try {
for (Object arg : args) {
Field field = arg.getClass().getDeclaredField(objectIdField);
field.setAccessible(true);
return String.valueOf(field.get(arg));
}
} catch (Exception e) {
// log the error
}
return null;
}
}
4.3 日志服务
我们需要提供一个 AuditLogService
,用来保存日志信息。
package com.example.ecommerce.service;
import com.example.ecommerce.model.AuditLogRecord;
import com.example.ecommerce.mapper.AuditLogMapper;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
@Service
public class AuditLogService {
@Autowired
private AuditLogMapper auditLogMapper;
public void saveLog(AuditLogRecord record) {
auditLogMapper.insert(record);
}
}
4.4 日志记录实体
package com.example.ecommerce.model;
import lombok.Data;
@Data
public class AuditLogRecord {
private Long id;
private String moduleName;
private String operation;
private String objectId;
private String objectDetail;
private Long userId;
private String username;
private String ipAddress;
private String createdAt;
}
4.5 Mapper 定义
package com.example.ecommerce.mapper;
import com.example.ecommerce.model.AuditLogRecord;
import org.apache.ibatis.annotations.Insert;
import org.apache.ibatis.annotations.Mapper;
@Mapper
public interface AuditLogMapper {
@Insert("INSERT INTO audit_logs(module_name, operation, object_id, user_id, username, ip_address, created_at) " +
"VALUES (#{moduleName}, #{operation}, #{objectId}, #{userId}, #{username}, #{ipAddress}, NOW())")
void insert(AuditLogRecord logRecord);
}
5. 示例使用
在 OrderService
中,我们可以通过 @AuditLog
注解来记录订单的创建操作。
package com.example.ecommerce.service;
import com.example.ecommerce.annotation.AuditLog;
import com.example.ecommerce.model.Order;
import org.springframework.stereotype.Service;
@Service
public class OrderService {
@AuditLog(moduleName = "订单模块", operation = "创建订单", objectId = "orderId")
public void createOrder(Order order) {
// 订单创建逻辑
}
}
在执行 createOrder
方法时,日志将自动记录到 audit_logs
表中。
6. 注解拦截器实现异步审计日志功能
通过自定义注解 @AuditLog
结合拦截器,实现了审计日志功能,记录用户的操作日志。然而,审计日志功能属于辅助功能,它的执行不应该影响到主流程的性能,尤其是在高并发的场景中,日志记录操作可能会成为性能瓶颈。
进一步优化审计日志的实现,将日志记录功能改为异步处理,从而提高接口的性能和响应速度。
6.1 异步处理的必要性
在实际场景中,审计日志功能仅用于记录用户的操作行为,这类操作通常是写入数据库或记录到日志系统中。虽然日志写入过程本身并不复杂,但如果将日志写入与主业务逻辑串行执行,可能会增加响应时间,特别是在高并发场景下。
通过异步化处理,我们可以将日志的记录放到后台线程中执行,主业务流程无需等待日志记录完成,从而提升接口的性能。
6.2 启用异步支持
首先,在 Spring Boot 的主类上添加 @EnableAsync
注解,启用异步功能。
package com.example.ecommerce;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.scheduling.annotation.EnableAsync;
@SpringBootApplication
@EnableAsync
public class EcommerceApplication {
public static void main(String[] args) {
SpringApplication.run(EcommerceApplication.class, args);
}
}
6.3 配置线程池
为了更好地处理异步任务,我们可以自定义一个线程池用于执行异步任务。通过线程池可以更好地控制并发数量以及任务的执行速度。
在 config
包下创建一个 AsyncConfig
类来配置线程池。
package com.example.ecommerce.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.scheduling.annotation.EnableAsync;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
import java.util.concurrent.Executor;
@Configuration
@EnableAsync
public class AsyncConfig {
@Bean(name = "auditLogExecutor")
public Executor asyncExecutor() {
ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
executor.setCorePoolSize(5); // 核心线程数
executor.setMaxPoolSize(10); // 最大线程数
executor.setQueueCapacity(500); // 队列容量
executor.setThreadNamePrefix("AuditLog-"); // 线程名称前缀
executor.initialize();
return executor;
}
}
在上述配置中,ThreadPoolTaskExecutor
用于处理异步任务,auditLogExecutor
线程池负责异步执行日志记录任务。配置中我们设置了核心线程数为 5,最大线程数为 10,队列容量为 500。可以根据实际需求调整这些参数。
6.4 修改日志服务
接下来,我们将之前的 AuditLogService
进行修改,使其能够异步记录日志。只需要在日志保存方法上加上 @Async
注解,并指定执行的线程池。
package com.example.ecommerce.service;
import com.example.ecommerce.model.AuditLogRecord;
import com.example.ecommerce.mapper.AuditLogMapper;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.scheduling.annotation.Async;
import org.springframework.stereotype.Service;
@Service
public class AuditLogService {
@Autowired
private AuditLogMapper auditLogMapper;
/**
* 异步保存审计日志
*/
@Async("auditLogExecutor")
public void saveLog(AuditLogRecord record) {
// 模拟一个较为耗时的日志记录操作
try {
Thread.sleep(200); // 模拟耗时操作
} catch (InterruptedException e) {
e.printStackTrace();
}
// 保存日志记录到数据库
auditLogMapper.insert(record);
}
}
在 saveLog
方法上,添加了 @Async("auditLogExecutor")
注解,表示该方法会在我们之前配置的 auditLogExecutor
线程池中异步执行。当该方法被调用时,Spring 会将其丢到异步线程中执行,而不会阻塞主线程。
6.5 审计日志拦截器保持不变
我们之前的审计日志拦截器实现并不需要修改,拦截器依旧会在标记有 @AuditLog
注解的方法执行前后进行日志记录操作。唯一的不同是 AuditLogService.saveLog
现在是异步执行的,因此不会阻塞业务方法的执行。
package com.example.ecommerce.interceptor;
import com.example.ecommerce.annotation.AuditLog;
import com.example.ecommerce.model.AuditLogRecord;
import com.example.ecommerce.service.AuditLogService;
import com.example.ecommerce.util.UserContext;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
import javax.servlet.http.HttpServletRequest;
import java.lang.reflect.Method;
@Aspect
@Component
public class AuditLogInterceptor {
@Autowired
private AuditLogService auditLogService;
@Autowired
private HttpServletRequest request;
@Around("@annotation(com.example.ecommerce.annotation.AuditLog)")
public Object logAudit(ProceedingJoinPoint joinPoint) throws Throwable {
Method method = getTargetMethod(joinPoint);
if (method == null) {
return joinPoint.proceed();
}
AuditLog auditLog = method.getAnnotation(AuditLog.class);
if (auditLog != null) {
// 获取用户信息和 IP 地址
Long userId = UserContext.getUserId();
String username = UserContext.getUsername();
String ipAddress = request.getRemoteAddr();
// 获取操作对象的ID
Object[] args = joinPoint.getArgs();
String objectId = getObjectId(args, auditLog.objectId());
// 执行目标方法
Object result = joinPoint.proceed();
// 创建日志记录
AuditLogRecord record = new AuditLogRecord();
record.setModuleName(auditLog.moduleName());
record.setOperation(auditLog.operation());
record.setUserId(userId);
record.setUsername(username);
record.setIpAddress(ipAddress);
record.setObjectId(objectId);
// 异步保存日志
auditLogService.saveLog(record);
return result;
}
return joinPoint.proceed();
}
private Method getTargetMethod(ProceedingJoinPoint joinPoint) {
Method method = null;
try {
method = joinPoint.getTarget().getClass().getMethod(joinPoint.getSignature().getName(),
((MethodSignature) joinPoint.getSignature()).getParameterTypes());
} catch (NoSuchMethodException e) {
e.printStackTrace();
}
return method;
}
private String getObjectId(Object[] args, String objectIdField) {
try {
for (Object arg : args) {
Field field = arg.getClass().getDeclaredField(objectIdField);
field.setAccessible(true);
return String.valueOf(field.get(arg));
}
} catch (Exception e) {
// log the error
}
return null;
}
}
6.6 示例使用
假设我们有一个订单模块的 OrderService
,通过 @AuditLog
注解,我们可以记录订单创建的操作。由于审计日志的记录现在是异步进行的,因此不会影响接口的响应性能。
package com.example.ecommerce.service;
import com.example.ecommerce.annotation.AuditLog;
import com.example.ecommerce.model.Order;
import org.springframework.stereotype.Service;
@Service
public class OrderService {
@AuditLog(moduleName = "订单模块", operation = "创建订单", objectId = "orderId")
public void createOrder(Order order) {
// 订单创建逻辑
}
}
在 createOrder
方法执行时,日志记录的操作会被异步提交给后台线程处理,从而确保主业务的执行不受影响。即便日志记录出现一些延迟,也不会影响主流程的性能。
6.7 日志输出
假设 OrderService.createOrder()
方法被调用,并且当前用户的 ID 为 1,用户名为 john_doe
,操作的 IP 地址为 192.168.1.1
,记录的审计日志最终会存储在数据库的 audit_logs
表中。
日志记录的 SQL 如下:
INSERT INTO audit_logs (module_name, operation, object_id, user_id, username, ip_address, created_at)
VALUES ('订单模块', '创建订单', '12345', 1, 'john_doe', '192.168.1.1', NOW());
7. 总结
通过自定义注解和拦截器,我们可以轻松实现审计日志的自动化记录。通过该方案,系统不仅可以动态记录用户的操作,还可以灵活地扩展到不同的模块和业务场景。
通过将审计日志的记录改为异步执行,整个系统的性能得到了显著提升。主流程执行完毕后,无需等待日志写入的