<!-- Spring AOP 依賴(lài) -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-aop</artifactId>
</dependency>
<!-- 工具包：用于 JSON 格式化、IP 地址獲?。蛇x，簡(jiǎn)化代碼） -->
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson2</artifactId>
    <version>2.0.32</version>
</dependency>
<!-- 用于獲取客戶(hù)端 IP（可選，也可自己寫(xiě)工具類(lèi)） -->
<dependency>
    <groupId>eu.bitwalker</groupId>
    <artifactId>UserAgentUtils</artifactId>
    <version>1.21</version>
</dependency>

import lombok.Data;
import java.time.LocalDateTime;
/**
 * 操作日志實(shí)體類(lèi)
 */
@Data
public class OperationLog {
    // 主鍵（實(shí)戰(zhàn)中可自增）
    private Long id;
    // 操作人（用戶(hù)名/ID）
    private String operator;
    // 操作時(shí)間
    private LocalDateTime operationTime;
    // 操作模塊
    private String module;
    // 操作描述
    private String description;
    // 接口地址
    private String requestUrl;
    // 請(qǐng)求方式
    private String requestMethod;
    // 請(qǐng)求參數(shù)（JSON 格式）
    private String requestParams;
    // 返回結(jié)果（JSON 格式）
    private String responseResult;
    // 執(zhí)行狀態(tài)（0-失敗，1-成功）
    private Integer status;
    // 異常信息（失敗時(shí)填寫(xiě)）
    private String errorMsg;
    // 操作 IP
    private String operationIp;
}

import java.lang.annotation.*;
/**
 * 自定義操作日志注解
 * @Target：注解作用范圍（METHOD：作用在方法上）
 * @Retention：注解保留時(shí)機(jī)（RUNTIME：運(yùn)行時(shí)保留，AOP 可獲?。?
 * @Documented：生成文檔時(shí)包含該注解
 */
@Target(ElementType.METHOD) // 只作用于方法
@Retention(RetentionPolicy.RUNTIME) // 運(yùn)行時(shí)生效
@Documented
public @interface OperationLogAnnotation {
    // 操作模塊（必填，比如“用戶(hù)管理”）
    String module() default "";
    // 操作描述（必填，比如“新增用戶(hù)”）
    String description() default "";
}

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;
/**
 * 操作日志切面類(lèi)
 * @Aspect：標(biāo)記此類(lèi)為切面
 * @Component：交給 Spring 管理，讓 Spring 掃描到該切面
 */
@Aspect
@Component
public class OperationLogAspect {
    // 1. 定義切點(diǎn)：匹配帶有 @OperationLogAnnotation 注解的方法
    @Pointcut("@annotation(com.example.demo.annotation.OperationLogAnnotation)")
    public void operationLogPointcut() {} // 切點(diǎn)方法，無(wú)實(shí)際邏輯，僅用于標(biāo)記
    // 2. 定義環(huán)繞通知：包裹切點(diǎn)方法，可在方法執(zhí)行前、執(zhí)行后、異常時(shí)處理
    @Around("operationLogPointcut()")
    public Object recordOperationLog(ProceedingJoinPoint joinPoint) throws Throwable {
        // 1. 初始化操作日志對(duì)象
        OperationLog operationLog = new OperationLog();
        // 2. 獲取當(dāng)前請(qǐng)求對(duì)象，用于獲取請(qǐng)求信息（URL、請(qǐng)求方式、IP 等）
        ServletRequestAttributes attributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
        HttpServletRequest request = attributes.getRequest();
        // 3. 填充日志基礎(chǔ)信息（無(wú)論接口成功/失敗，都需要記錄）
        // 3.1 獲取操作人（實(shí)戰(zhàn)中需結(jié)合 Spring Security/Token 獲取，這里模擬 admin）
        operationLog.setOperator("admin");
        // 3.2 操作時(shí)間（當(dāng)前時(shí)間）
        operationLog.setOperationTime(LocalDateTime.now());
        // 3.3 接口地址
        operationLog.setRequestUrl(request.getRequestURI());
        // 3.4 請(qǐng)求方式（GET/POST）
        operationLog.setRequestMethod(request.getMethod());
        // 3.5 操作 IP（獲取客戶(hù)端真實(shí) IP）
        operationLog.setOperationIp(getClientIp(request));
        // 3.6 請(qǐng)求參數(shù)（將方法參數(shù)轉(zhuǎn)為 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. 執(zhí)行目標(biāo)方法（核心業(yè)務(wù)邏輯），捕獲執(zhí)行結(jié)果和異常
        Object result = null;
        try {
            // 執(zhí)行目標(biāo)方法（比如接口的核心邏輯）
            result = joinPoint.proceed();
            // 方法執(zhí)行成功：設(shè)置狀態(tài)為 1（成功），記錄返回結(jié)果
            operationLog.setStatus(1);
            operationLog.setResponseResult(JSON.toJSONString(result));
        } catch (Throwable throwable) {
            // 方法執(zhí)行失?。涸O(shè)置狀態(tài)為 0（失敗），記錄異常信息
            operationLog.setStatus(0);
            operationLog.setErrorMsg(throwable.getMessage());
            // 拋出異常，不影響原有業(yè)務(wù)邏輯的異常處理
            throw throwable;
        } finally {
            // 6. 日志持久化（實(shí)戰(zhàn)中可存入數(shù)據(jù)庫(kù)、ElasticSearch 等，這里模擬打印）
            System.out.println("操作日志記錄：" + JSON.toJSONString(operationLog, true));
            // TODO: 實(shí)戰(zhàn)中替換為數(shù)據(jù)庫(kù)插入操作（比如調(diào)用 OperationLogService.save(operationLog)）
        }
        // 返回目標(biāo)方法的執(zhí)行結(jié)果，不影響原有接口的返回值
        return result;
    }
    /**
     * 工具方法：獲取客戶(hù)端真實(shí) IP（處理代理場(chǎng)景，比如 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();
        }
        // 處理多代理場(chǎng)景，取第一個(gè)非 unknown 的 IP
        if (ip != null && ip.contains(",")) {
            ip = ip.split(",")[0].trim();
        }
        return ip;
    }
}

import com.example.demo.annotation.OperationLogAnnotation;
import org.springframework.web.bind.annotation.*;
import java.util.HashMap;
import java.util.Map;
/**
 * 測(cè)試接口：用戶(hù)管理模塊
 */
@RestController
@RequestMapping("/api/user")
public class UserController {
    // 添加 @OperationLogAnnotation 注解，標(biāo)記需要記錄日志
    @OperationLogAnnotation(module = "用戶(hù)管理", description = "新增用戶(hù)")
    @PostMapping("/add")
    public Map<String, Object> addUser(@RequestBody Map<String, String> params) {
        // 模擬新增用戶(hù)核心邏輯
        Map<String, Object> result = new HashMap<>();
        result.put("code", 200);
        result.put("msg", "新增用戶(hù)成功");
        result.put("data", params);
        return result;
    }
    // 測(cè)試異常場(chǎng)景
    @OperationLogAnnotation(module = "用戶(hù)管理", description = "刪除用戶(hù)")
    @DeleteMapping("/delete/{id}")
    public Map<String, Object> deleteUser(@PathVariable Long id) {
        // 模擬異常（比如刪除不存在的用戶(hù)）
        if (id <= 0) {
            throw new RuntimeException("用戶(hù)ID非法，無(wú)法刪除");
        }
        Map<String, Object> result = new HashMap<>();
        result.put("code", 200);
        result.put("msg", "刪除用戶(hù)成功");
        return result;
    }
}

操作日志記錄：{
    "description":"新增用戶(hù)",
    "module":"用戶(hù)管理",
    "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\":\"新增用戶(hù)成功\"}",
    "status":1
}

操作日志記錄：{
    "description":"刪除用戶(hù)",
    "errorMsg":"用戶(hù)ID非法，無(wú)法刪除",
    "module":"用戶(hù)管理",
    "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
}

// 結(jié)合 Spring Security 獲取當(dāng)前登錄用戶(hù)
Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
if (authentication != null && !(authentication.getPrincipal() instanceof String)) {
    UserDetails userDetails = (UserDetails) authentication.getPrincipal();
    operationLog.setOperator(userDetails.getUsername()); // 獲取用戶(hù)名
}

// 1. 注入 OperationLogService
@Autowired
private OperationLogService operationLogService;
// 2. 在 finally 中替換打印邏輯，改為存入數(shù)據(jù)庫(kù)
finally {
    operationLogService.save(operationLog); // MyBatis-Plus 自帶的保存方法
}

// 1. 自定義忽略敏感參數(shù)注解
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface IgnoreSensitive {
}
// 2. 在實(shí)體類(lèi)敏感字段上添加注解
@Data
public class User {
    private Long id;
    private String username;
    @IgnoreSensitive // 忽略密碼字段
    private String password;
}
// 3. 在切面中，處理敏感參數(shù)（替換為 ****）
// （核心邏輯：反射獲取字段，判斷是否有 @IgnoreSensitive 注解，有則替換值）