<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-aop</artifactId>
  <version>2.7.15</version>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
  <version>2.7.15</version>
</dependency>

package com.demo.aop.annotation;

import java.lang.annotation.*;

// 簡(jiǎn)單日志級(jí)別枚舉，用于控制切面日志輸出級(jí)別
public enum LogLevel { TRACE, DEBUG, INFO, WARN, ERROR }

// 日志注解：可標(biāo)在類或方法上，控制是否記錄日志以及日志細(xì)節(jié)
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiLog {
  // 業(yè)務(wù)含義描述，例如“查詢訂單”“用戶登錄”
  String value() default "";
  // 是否忽略當(dāng)前方法（即使類上加了 ApiLog）
  boolean ignore() default false;
  // 日志級(jí)別，默認(rèn)為 INFO
  LogLevel level() default LogLevel.INFO;
  // 是否隱藏響應(yīng)體（例如大對(duì)象或隱私數(shù)據(jù)）
  boolean hideResp() default false;
}

// 權(quán)限注解：可標(biāo)在類或方法上，聲明允許訪問的角色
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface RequireRole {
  // 支持多個(gè)角色，只要命中其中一個(gè)即可訪問
  String[] value();
}

package com.demo.aop.common;

public class ApiResponse<T> {
  // 業(yè)務(wù)狀態(tài)碼，0 表示成功，其他表示失敗
  private int code;
  // 業(yè)務(wù)提示信息
  private String message;
  // 真實(shí)數(shù)據(jù)載體
  private T data;
  // 快捷構(gòu)造成功返回
  public static <T> ApiResponse<T> ok(T d){ return of(0,"OK",d); }
  // 快捷構(gòu)造失敗返回
  public static <T> ApiResponse<T> fail(String msg){ return of(-1,msg,null); }
  private static <T> ApiResponse<T> of(int c,String m,T d){
    ApiResponse<T> r=new ApiResponse<>(); r.code=c; r.message=m; r.data=d; return r;
  }
}

// 自定義權(quán)限異常，統(tǒng)一由全局異常處理器攔截
public class PermissionDeniedException extends RuntimeException {
  public PermissionDeniedException(String msg){ super(msg); }
}

@RestControllerAdvice
public class GlobalExceptionHandler {
  // 捕獲權(quán)限異常，統(tǒng)一轉(zhuǎn)成 ApiResponse JSON 返回
  @ExceptionHandler(PermissionDeniedException.class)
  public ApiResponse<Void> handlePermission(PermissionDeniedException e){
    return ApiResponse.fail(e.getMessage());
  }
}

package com.demo.aop.aspect;

import com.demo.aop.annotation.ApiLog;
import com.demo.aop.annotation.LogLevel;
import com.demo.aop.common.ApiResponse;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.*;
import org.springframework.core.annotation.Order;
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.util.*;

@Aspect
@Component
@Order(2) // 權(quán)限優(yōu)先，日志在后
public class ApiLogAspect {

  // Slf4j 日志器
  private static final org.slf4j.Logger log = org.slf4j.LoggerFactory.getLogger(ApiLogAspect.class);
  // 統(tǒng)一 JSON 序列化
  private final ObjectMapper mapper = new ObjectMapper();

  // 切入點(diǎn)：匹配標(biāo)了 @ApiLog 的方法或類
  @Pointcut("@annotation(com.demo.aop.annotation.ApiLog) || @within(com.demo.aop.annotation.ApiLog)")
  public void apiLogPointcut() {}

  // 環(huán)繞通知：在目標(biāo)方法前后插入日志邏輯
  @Around("apiLogPointcut()")
  public Object recordLog(ProceedingJoinPoint pjp) throws Throwable {
    // 兼容方法級(jí) / 類級(jí)注解
    ApiLog ann = findAnnotation(pjp);
    if (ann == null || ann.ignore()) { return pjp.proceed(); }

    // 記錄開始時(shí)間，用于計(jì)算耗時(shí)
    long start = System.currentTimeMillis();
    // 從請(qǐng)求上下文中獲取 HttpServletRequest，非 Web 環(huán)境直接放行
    ServletRequestAttributes attrs = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
    if (attrs == null) { // 非 Web 環(huán)境兜底
      return pjp.proceed();
    }
    HttpServletRequest req = attrs.getRequest();

    // TraceId：從 header 取，沒有則生成一個(gè)新的
    String traceId = Optional.ofNullable(req.getHeader("X-Trace-Id"))
            .orElse(UUID.randomUUID().toString());
    // 基本請(qǐng)求信息
    String url = req.getRequestURI();
    String method = req.getMethod();
    String user = Optional.ofNullable(req.getHeader("X-User")).orElse("anonymous");
    // IP：優(yōu)先使用 X-Forwarded-For 頭（兼容網(wǎng)關(guān) / 負(fù)載）
    String ip = Optional.ofNullable(req.getHeader("X-Forwarded-For"))
            .map(s -> s.split(",")[0].trim()).orElse(req.getRemoteAddr());
    // 客戶端標(biāo)識(shí)
    String ua = Optional.ofNullable(req.getHeader("User-Agent")).orElse("unknown");
    // 請(qǐng)求參數(shù) Map
    Map<String, String[]> params = req.getParameterMap();
    // 將參數(shù)轉(zhuǎn) JSON 并脫敏
    String args = mask(toJsonSafe(params));

    Object result = null; Throwable ex = null;
    try {
      // 繼續(xù)執(zhí)行真實(shí)業(yè)務(wù)方法
      result = pjp.proceed();
      return result;
    } catch (Throwable t) {
      // 記錄異常并向上拋出
      ex = t; throw t;
    } finally {
      long cost = System.currentTimeMillis() - start;
      // 根據(jù)注解配置決定是否輸出響應(yīng)體
      String resp = ann.hideResp() ? "<hidden>" : toJsonSafe(result);
      // 按指定日志級(jí)別輸出
      logWithLevel(ann.level(), "[API-LOG] trace={} {} {} user={} ip={} ua={} cost={}ms args={} resp={} err={}",
              traceId, method, url, user, ip, ua, cost, args, resp, ex == null ? "none" : ex.getMessage());
    }
  }

  // 查找方法 / 類上的 ApiLog 注解
  private ApiLog findAnnotation(ProceedingJoinPoint pjp) {
    ApiLog methodAnn = org.springframework.core.annotation.AnnotationUtils
            .findAnnotation(((org.aspectj.lang.reflect.MethodSignature) pjp.getSignature()).getMethod(), ApiLog.class);
    ApiLog typeAnn = org.springframework.core.annotation.AnnotationUtils
            .findAnnotation(pjp.getTarget().getClass(), ApiLog.class);
    return methodAnn != null ? methodAnn : typeAnn;
  }

  // 安全 JSON 序列化，失敗時(shí)給出占位字符串
  private String toJsonSafe(Object obj){
    try { return mapper.writeValueAsString(obj); }
    catch (JsonProcessingException e){
      log.warn("json serialize fail", e);
      return "<json-error>";
    }
  }

  // 簡(jiǎn)單脫敏：隱藏密碼與手機(jī)號(hào)中間四位
  private String mask(String json){
    if (json == null) return null;
    // password/pwd 字段統(tǒng)一替換為 ****
    return json.replaceAll("(?i)(password|pwd)\":\"[^\"]+\"", "$1\":\"****\"")
            // phone 字段保留前 3 位和后 4 位，中間打 ***
            .replaceAll("(\"phone\"\\s*:\\s*\")\\d{3}\\d{4}(\\d{4}\")", "$1***$2");
  }

  // 根據(jù)注解上的日志級(jí)別動(dòng)態(tài)選擇輸出方法
  private void logWithLevel(LogLevel level, String msg, Object... args){
    switch (level){
      case TRACE: log.trace(msg, args); break;
      case DEBUG: log.debug(msg, args); break;
      case WARN:  log.warn(msg, args); break;
      case ERROR: log.error(msg, args); break;
      default:    log.info(msg, args);
    }
  }
}

package com.demo.aop.aspect;

import com.demo.aop.annotation.RequireRole;
import com.demo.aop.common.PermissionDeniedException;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.*;
import org.springframework.core.annotation.Order;
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.util.Arrays;

@Aspect
@Component
@Order(1) // 先校驗(yàn)權(quán)限，再記錄日志
public class AuthAspect {

  @Pointcut("@annotation(com.demo.aop.annotation.RequireRole) || @within(com.demo.aop.annotation.RequireRole)")
  public void authPointcut() {}

  @Around("authPointcut() && @annotation(requireRole)")
  public Object checkRole(ProceedingJoinPoint pjp, RequireRole requireRole) throws Throwable {
    // 獲取當(dāng)前請(qǐng)求上下文，非 Web 環(huán)境直接略過權(quán)限校驗(yàn)
    ServletRequestAttributes attrs = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
    if (attrs == null) { return pjp.proceed(); } // 非 Web 環(huán)境直接放行
    HttpServletRequest req = attrs.getRequest();

    // 1) 從 Header 中讀取角色（演示用，真實(shí)場(chǎng)景多為 JWT / Session）
    String role = req.getHeader("X-Role");
    // 2) JWT 極簡(jiǎn)示例（偽代碼）
    // String role = JwtUtil.parseRole(req.getHeader("Authorization"));
    // 3) DB 極簡(jiǎn)示例（偽代碼）
    // List<String> roles = roleRepo.findRolesByUser(req.getHeader("X-User"));

    // 只要當(dāng)前角色命中注解聲明的任一角色，就視為通過
    boolean ok = role != null && Arrays.stream(requireRole.value())
            .anyMatch(r -> r.equalsIgnoreCase(role));
    // 未通過則拋出權(quán)限異常，由全局異常處理器統(tǒng)一返回 JSON
    if (!ok) { throw new PermissionDeniedException("無訪問權(quán)限，需角色: " + String.join("/", requireRole.value())); }
    return pjp.proceed();
  }
}

package com.demo.aop.controller;

import com.demo.aop.annotation.ApiLog;
import com.demo.aop.annotation.LogLevel;
import com.demo.aop.annotation.RequireRole;
import com.demo.aop.common.ApiResponse;
import org.springframework.web.bind.annotation.*;

// 類級(jí)別加上 ApiLog：該 Controller 所有接口默認(rèn)記錄日志
@ApiLog(value="類級(jí)日志", level=LogLevel.DEBUG)
@RestController
@RequestMapping("/demo")
public class DemoController {

    // 查詢訂單接口：?jiǎn)为?dú)指定日志描述，并要求 ADMIN/OPS 角色
    @ApiLog(value="查詢訂單", hideResp=false)
    @RequireRole({"ADMIN","OPS"})
    @GetMapping("/order")
    public ApiResponse<String> getOrder(@RequestParam String id) {
        // 真實(shí)場(chǎng)景可查詢數(shù)據(jù)庫，這里僅返回一個(gè)拼接字符串
        return ApiResponse.ok("order-" + id);
    }

    // 健康檢查接口：可被監(jiān)控系統(tǒng)頻繁調(diào)用，隱藏響應(yīng)體減少日志噪音
    @ApiLog(value="健康檢查", ignore=false, hideResp=true)
    @GetMapping("/ping")
    public ApiResponse<String> ping() {
        return ApiResponse.ok("pong");
    }
}