一、前言前面我们已经学过Spring AOP 从原理到实战Spring AOP 进阶日志、TraceId、权限、限流这一篇继续升级。这篇的目标不是单独讲某个注解而是把项目中常见的基础能力做成一套可复制的工程模板统一返回 Result业务异常 BizException全局异常处理 GlobalExceptionHandlerAOP 通知类型工具箱TraceId 链路追踪请求日志 AOP操作日志 AOP权限校验 AOP限流 AOP日志通用工具类最终效果Controller 专注接收请求Service / Biz 专注业务逻辑Repository 专注数据访问shared 负责基础设施能力二、推荐项目结构project │ ├── modules │ ├── user │ ├── order │ ├── pay │ ├── ai │ └── inventory │ ├── gateway │ ├── shared │ ├── result │ │ ├── Result.java │ │ └── ResultCodeEnum.java │ │ │ ├── exception │ │ ├── BizException.java │ │ └── GlobalExceptionHandler.java │ │ │ ├── annotation │ │ ├── OperationLog.java │ │ ├── CheckPermission.java │ │ └── RateLimit.java │ │ │ ├── aop │ │ ├── BeforeLogAspect.java │ │ ├── AfterReturningLogAspect.java │ │ ├── AfterThrowingLogAspect.java │ │ ├── AfterLogAspect.java │ │ ├── TraceIdAspect.java │ │ ├── RequestLogAspect.java │ │ ├── OperationLogAspect.java │ │ ├── PermissionAspect.java │ │ └── RateLimitAspect.java │ │ │ └── util │ ├── JsonUtils.java │ ├── WebUtils.java │ ├── TraceIdUtils.java │ └── LogUtils.java │ ├── scheduler ├── resources └── ProjectApplication.java核心原则业务代码放 modules通用能力放 sharedAOP、异常、返回、工具类都属于 shared三、统一返回 Result1. ResultCodeEnumpackage com.xxx.shared.result; public enum ResultCodeEnum { SUCCESS(0, 成功), PARAM_ERROR(1001, 参数错误), USER_NOT_FOUND(1002, 用户不存在), USERNAME_EXIST(1003, 用户名已存在), NO_PERMISSION(1004, 没有权限), RATE_LIMIT(1005, 请求过于频繁), SYSTEM_ERROR(5000, 系统异常); private final Integer code; private final String message; ResultCodeEnum(Integer code, String message) { this.code code; this.message message; } public Integer getCode() { return code; } public String getMessage() { return message; } }2. Resultpackage com.xxx.shared.result; public class ResultT { private Integer code; private String message; private T data; public Result() { } private Result(Integer code, String message, T data) { this.code code; this.message message; this.data data; } public static T ResultT success() { return new Result( ResultCodeEnum.SUCCESS.getCode(), ResultCodeEnum.SUCCESS.getMessage(), null ); } public static T ResultT success(T data) { return new Result( ResultCodeEnum.SUCCESS.getCode(), ResultCodeEnum.SUCCESS.getMessage(), data ); } public static T ResultT fail(ResultCodeEnum codeEnum) { return new Result( codeEnum.getCode(), codeEnum.getMessage(), null ); } public static T ResultT fail(ResultCodeEnum codeEnum, String message) { return new Result( codeEnum.getCode(), message, null ); } public static T ResultT fail(Integer code, String message) { return new Result( code, message, null ); } public Integer getCode() { return code; } public void setCode(Integer code) { this.code code; } public String getMessage() { return message; } public void setMessage(String message) { this.message message; } public T getData() { return data; } public void setData(T data) { this.data data; } }Controller 中使用GetMapping(/info/{id}) public ResultUserResponse getUser(PathVariable Long id) { UserResponse response userQueryExecutor.getUser(id); return Result.success(response); }统一返回{code: 0,message: 成功,data: {id: 1,username: admin}}四、业务异常 BizExceptionpackage com.xxx.shared.exception; import com.xxx.shared.result.ResultCodeEnum; public class BizException extends RuntimeException { private final Integer code; public BizException(ResultCodeEnum codeEnum) { super(codeEnum.getMessage()); this.code codeEnum.getCode(); } public BizException(ResultCodeEnum codeEnum, String message) { super(message); this.code codeEnum.getCode(); } public BizException(Integer code, String message) { super(message); this.code code; } public Integer getCode() { return code; } }业务中使用if (user null) { throw new BizException(ResultCodeEnum.USER_NOT_FOUND); }五、全局异常处理 GlobalExceptionHandlerpackage com.xxx.shared.exception; import com.xxx.shared.result.Result; import com.xxx.shared.result.ResultCodeEnum; import lombok.extern.slf4j.Slf4j; import org.springframework.validation.BindException; import org.springframework.web.bind.MethodArgumentNotValidException; import org.springframework.web.bind.annotation.ExceptionHandler; import org.springframework.web.bind.annotation.RestControllerAdvice; RestControllerAdvice Slf4j public class GlobalExceptionHandler { ExceptionHandler(BizException.class) public ResultVoid handleBizException(BizException e) { log.warn(业务异常code{}, message{}, e.getCode(), e.getMessage()); return Result.fail(e.getCode(), e.getMessage()); } ExceptionHandler(MethodArgumentNotValidException.class) public ResultVoid handleMethodArgumentNotValidException(MethodArgumentNotValidException e) { String message e.getBindingResult() .getFieldErrors() .stream() .findFirst() .map(error - error.getField() error.getDefaultMessage()) .orElse(参数校验失败); log.warn(参数校验异常{}, message); return Result.fail(ResultCodeEnum.PARAM_ERROR, message); } ExceptionHandler(BindException.class) public ResultVoid handleBindException(BindException e) { String message e.getBindingResult() .getFieldErrors() .stream() .findFirst() .map(error - error.getField() error.getDefaultMessage()) .orElse(参数绑定失败); log.warn(参数绑定异常{}, message); return Result.fail(ResultCodeEnum.PARAM_ERROR, message); } ExceptionHandler(Exception.class) public ResultVoid handleException(Exception e) { log.error(系统异常, e); return Result.fail(ResultCodeEnum.SYSTEM_ERROR); } }这样业务异常会统一变成{code: 1002,message: 用户不存在,data: null}六、AOP 通知类型工具箱这一章是补充重点。AOP 不是只有Around常见通知类型有BeforeAfterReturningAfterThrowingAfterAround它们分别适合不同场景。1. Before方法执行前适合方法进入日志简单参数打印简单前置检查代码package com.xxx.shared.aop; import com.xxx.shared.util.JsonUtils; import com.xxx.shared.util.LogUtils; import lombok.extern.slf4j.Slf4j; import org.aspectj.lang.JoinPoint; import org.aspectj.lang.annotation.Aspect; import org.aspectj.lang.annotation.Before; import org.springframework.stereotype.Component; Aspect Component Slf4j public class BeforeLogAspect { Before(execution(* com.xxx.modules..controller..*(..))) public void before(JoinPoint joinPoint) { Object[] args LogUtils.filterArgs(joinPoint.getArgs()); log.info(Before方法开始method{}, args{}, joinPoint.getSignature().toShortString(), LogUtils.maskSensitive(JsonUtils.toJson(args))); } }特点能在方法前执行不能拿到返回值不能统计完整耗时不能决定方法是否执行2. AfterReturning成功返回后适合返回值日志成功统计成功后埋点代码package com.xxx.shared.aop; import com.xxx.shared.util.JsonUtils; import com.xxx.shared.util.LogUtils; import lombok.extern.slf4j.Slf4j; import org.aspectj.lang.JoinPoint; import org.aspectj.lang.annotation.AfterReturning; import org.aspectj.lang.annotation.Aspect; import org.springframework.stereotype.Component; Aspect Component Slf4j public class AfterReturningLogAspect { AfterReturning( pointcut execution(* com.xxx.modules..controller..*(..)), returning result ) public void afterReturning(JoinPoint joinPoint, Object result) { log.info(AfterReturning方法成功method{}, result{}, joinPoint.getSignature().toShortString(), LogUtils.maskSensitive(JsonUtils.toJson(result))); } }特点只在方法成功返回后执行异常时不会执行不能做异常日志不能包住完整流程3. AfterThrowing异常后适合异常日志异常统计异常报警触发代码package com.xxx.shared.aop; import lombok.extern.slf4j.Slf4j; import org.aspectj.lang.JoinPoint; import org.aspectj.lang.annotation.AfterThrowing; import org.aspectj.lang.annotation.Aspect; import org.springframework.stereotype.Component; Aspect Component Slf4j public class AfterThrowingLogAspect { AfterThrowing( pointcut execution(* com.xxx.modules..controller..*(..)), throwing e ) public void afterThrowing(JoinPoint joinPoint, Throwable e) { log.error(AfterThrowing方法异常method{}, joinPoint.getSignature().toShortString(), e); } }特点只在异常时执行适合记录异常不能处理成功返回4. After最终执行适合资源清理ThreadLocal 清理MDC 清理无论成功失败都要执行的逻辑代码package com.xxx.shared.aop; import lombok.extern.slf4j.Slf4j; import org.aspectj.lang.JoinPoint; import org.aspectj.lang.annotation.After; import org.aspectj.lang.annotation.Aspect; import org.springframework.stereotype.Component; Aspect Component Slf4j public class AfterLogAspect { After(execution(* com.xxx.modules..controller..*(..))) public void after(JoinPoint joinPoint) { log.info(After方法结束method{}, joinPoint.getSignature().toShortString()); } }特点无论成功失败都会执行拿不到返回值不知道是成功还是异常5. Around完整包裹适合请求日志耗时统计权限拦截限流重试降级TraceId代码package com.xxx.shared.aop; import lombok.extern.slf4j.Slf4j; import org.aspectj.lang.ProceedingJoinPoint; import org.aspectj.lang.annotation.Around; import org.aspectj.lang.annotation.Aspect; import org.springframework.stereotype.Component; Aspect Component Slf4j public class AroundDemoAspect { Around(execution(* com.xxx.modules..controller..*(..))) public Object around(ProceedingJoinPoint joinPoint) throws Throwable { long start System.currentTimeMillis(); try { Object result joinPoint.proceed(); long cost System.currentTimeMillis() - start; log.info(Around方法成功method{}, cost{}ms, joinPoint.getSignature().toShortString(), cost); return result; } catch (Throwable e) { log.error(Around方法异常method{}, joinPoint.getSignature().toShortString(), e); throw e; } } }特点最强可以控制方法是否执行可以拿到参数可以拿到返回值可以捕获异常可以统计耗时可以修改返回结果6. 怎么选择通知类型只想在执行前做点事→ Before只关心成功返回→ AfterReturning只关心异常→ AfterThrowing无论成功失败都要收尾→ After要控制完整流程→ Around真实项目中请求日志、权限、限流、TraceId优先用 Around原因是它能覆盖一次方法调用的完整生命周期七、AOP 通用注解tips注解Annotation1. OperationLogpackage com.xxx.shared.annotation; import java.lang.annotation.*; Target(ElementType.METHOD) Retention(RetentionPolicy.RUNTIME) Documented public interface OperationLog { String value() default ; String module() default ; String action() default ; }2. CheckPermissionpackage com.xxx.shared.annotation; import java.lang.annotation.*; Target(ElementType.METHOD) Retention(RetentionPolicy.RUNTIME) Documented public interface CheckPermission { String value(); }3. RateLimitpackage com.xxx.shared.annotation; import java.lang.annotation.*; Target(ElementType.METHOD) Retention(RetentionPolicy.RUNTIME) Documented public interface RateLimit { int limit() default 10; }八、AOP 通用工具类1. TraceIdUtilspackage com.xxx.shared.util; import java.util.UUID; public class TraceIdUtils { public static final String TRACE_ID traceId; private TraceIdUtils() { } public static String generateTraceId() { return UUID.randomUUID().toString().replace(-, ); } }2. JsonUtilspackage com.xxx.shared.util; import com.fasterxml.jackson.core.JsonProcessingException; import com.fasterxml.jackson.databind.ObjectMapper; public class JsonUtils { private static final ObjectMapper OBJECT_MAPPER new ObjectMapper(); private JsonUtils() { } public static String toJson(Object obj) { if (obj null) { return null; } try { return OBJECT_MAPPER.writeValueAsString(obj); } catch (JsonProcessingException e) { return String.valueOf(obj); } } }3. WebUtilspackage com.xxx.shared.util; import jakarta.servlet.http.HttpServletRequest; import org.springframework.web.context.request.RequestContextHolder; import org.springframework.web.context.request.ServletRequestAttributes; public class WebUtils { private WebUtils() { } public static HttpServletRequest getRequest() { ServletRequestAttributes attributes (ServletRequestAttributes) RequestContextHolder.getRequestAttributes(); if (attributes null) { return null; } return attributes.getRequest(); } public static String getRequestUri() { HttpServletRequest request getRequest(); return request null ? : request.getRequestURI(); } public static String getMethod() { HttpServletRequest request getRequest(); return request null ? : request.getMethod(); } public static String getIp() { HttpServletRequest request getRequest(); if (request null) { return ; } String ip request.getHeader(X-Forwarded-For); if (ip ! null !ip.isEmpty() !unknown.equalsIgnoreCase(ip)) { return ip.split(,)[0]; } ip request.getHeader(X-Real-IP); if (ip ! null !ip.isEmpty() !unknown.equalsIgnoreCase(ip)) { return ip; } return request.getRemoteAddr(); } }注意Spring Boot 3 使用 jakarta.servletSpring Boot 2 使用 javax.servlet4. LogUtilspackage com.xxx.shared.util; import jakarta.servlet.ServletRequest; import jakarta.servlet.ServletResponse; import org.springframework.web.multipart.MultipartFile; import java.util.Arrays; public class LogUtils { private LogUtils() { } public static Object[] filterArgs(Object[] args) { if (args null) { return new Object[0]; } return Arrays.stream(args) .filter(arg - !(arg instanceof ServletRequest)) .filter(arg - !(arg instanceof ServletResponse)) .filter(arg - !(arg instanceof MultipartFile)) .toArray(); } public static String maskSensitive(String text) { if (text null) { return null; } return text .replaceAll((\password\\\s*:\\s*\).*?(\), $1******$2) .replaceAll((\token\\\s*:\\s*\).*?(\), $1******$2) .replaceAll((\authorization\\\s*:\\s*\).*?(\), $1******$2); } }九、TraceIdAspectpackage com.xxx.shared.aop; import com.xxx.shared.util.TraceIdUtils; import org.aspectj.lang.ProceedingJoinPoint; import org.aspectj.lang.annotation.Around; import org.aspectj.lang.annotation.Aspect; import org.slf4j.MDC; import org.springframework.core.annotation.Order; import org.springframework.stereotype.Component; Aspect Component Order(1) public class TraceIdAspect { Around(execution(* com.xxx.modules..controller..*(..))) public Object trace(ProceedingJoinPoint joinPoint) throws Throwable { String traceId TraceIdUtils.generateTraceId(); MDC.put(TraceIdUtils.TRACE_ID, traceId); try { return joinPoint.proceed(); } finally { MDC.remove(TraceIdUtils.TRACE_ID); } } }说明TraceIdAspect 用 Around因为它需要1. 方法执行前放入 traceId2. 方法执行后清理 traceId十、RequestLogAspectpackage com.xxx.shared.aop; import com.xxx.shared.util.JsonUtils; import com.xxx.shared.util.LogUtils; import com.xxx.shared.util.WebUtils; import lombok.extern.slf4j.Slf4j; import org.aspectj.lang.ProceedingJoinPoint; import org.aspectj.lang.annotation.Around; import org.aspectj.lang.annotation.Aspect; import org.springframework.core.annotation.Order; import org.springframework.stereotype.Component; Aspect Component Slf4j Order(2) public class RequestLogAspect { Around(execution(* com.xxx.modules..controller..*(..))) public Object log(ProceedingJoinPoint joinPoint) throws Throwable { long start System.currentTimeMillis(); String uri WebUtils.getRequestUri(); String httpMethod WebUtils.getMethod(); String ip WebUtils.getIp(); String javaMethod joinPoint.getSignature().toShortString(); Object[] filteredArgs LogUtils.filterArgs(joinPoint.getArgs()); String argsJson LogUtils.maskSensitive(JsonUtils.toJson(filteredArgs)); log.info(请求开始uri{}, method{}, ip{}, javaMethod{}, args{}, uri, httpMethod, ip, javaMethod, argsJson); try { Object result joinPoint.proceed(); long cost System.currentTimeMillis() - start; String resultJson LogUtils.maskSensitive(JsonUtils.toJson(result)); log.info(请求结束uri{}, javaMethod{}, cost{}ms, result{}, uri, javaMethod, cost, resultJson); return result; } catch (Throwable e) { long cost System.currentTimeMillis() - start; log.error(请求异常uri{}, javaMethod{}, cost{}ms, uri, javaMethod, cost, e); throw e; } } }说明请求日志用 Around 最合适因为它需要同时处理请求前请求后耗时返回值异常十一、OperationLogAspectpackage com.xxx.shared.aop; import com.xxx.shared.annotation.OperationLog; import com.xxx.shared.util.WebUtils; import lombok.extern.slf4j.Slf4j; import org.aspectj.lang.ProceedingJoinPoint; import org.aspectj.lang.annotation.Around; import org.aspectj.lang.annotation.Aspect; import org.springframework.core.annotation.Order; import org.springframework.stereotype.Component; Aspect Component Slf4j Order(3) public class OperationLogAspect { Around(annotation(operationLog)) public Object operationLog(ProceedingJoinPoint joinPoint, OperationLog operationLog) throws Throwable { long start System.currentTimeMillis(); String module operationLog.module(); String action operationLog.action(); String value operationLog.value(); try { Object result joinPoint.proceed(); long cost System.currentTimeMillis() - start; log.info(操作日志module{}, action{}, value{}, uri{}, cost{}ms, module, action, value, WebUtils.getRequestUri(), cost); return result; } catch (Throwable e) { long cost System.currentTimeMillis() - start; log.error(操作异常module{}, action{}, value{}, uri{}, cost{}ms, module, action, value, WebUtils.getRequestUri(), cost, e); throw e; } } }使用OperationLog(module 用户模块, action 创建用户) PostMapping(/create) public ResultVoid createUser(RequestBody CreateUserRequest request) { userFacade.createUser(request); return Result.success(); }十二、PermissionAspectpackage com.xxx.shared.aop; import com.xxx.shared.annotation.CheckPermission; import com.xxx.shared.exception.BizException; import com.xxx.shared.result.ResultCodeEnum; import lombok.extern.slf4j.Slf4j; import org.aspectj.lang.ProceedingJoinPoint; import org.aspectj.lang.annotation.Around; import org.aspectj.lang.annotation.Aspect; import org.springframework.core.annotation.Order; import org.springframework.stereotype.Component; Aspect Component Slf4j Order(0) public class PermissionAspect { Around(annotation(checkPermission)) public Object check(ProceedingJoinPoint joinPoint, CheckPermission checkPermission) throws Throwable { String permission checkPermission.value(); if (!hasPermission(permission)) { log.warn(权限校验失败permission{}, permission); throw new BizException(ResultCodeEnum.NO_PERMISSION); } return joinPoint.proceed(); } private boolean hasPermission(String permission) { // 这里先写死 true // 后面可以从 JWT / Redis / 当前登录用户上下文中获取权限 return true; } }为什么必须用Around因为权限校验需要决定业务方法到底要不要执行十三、RateLimitAspectpackage com.xxx.shared.aop; import com.xxx.shared.annotation.RateLimit; import com.xxx.shared.exception.BizException; import com.xxx.shared.result.ResultCodeEnum; import lombok.extern.slf4j.Slf4j; import org.aspectj.lang.ProceedingJoinPoint; import org.aspectj.lang.annotation.Around; import org.aspectj.lang.annotation.Aspect; import org.springframework.core.annotation.Order; import org.springframework.stereotype.Component; import java.util.Map; import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.atomic.AtomicInteger; Aspect Component Slf4j Order(0) public class RateLimitAspect { private final MapString, AtomicInteger counter new ConcurrentHashMap(); Around(annotation(rateLimit)) public Object limit(ProceedingJoinPoint joinPoint, RateLimit rateLimit) throws Throwable { String key joinPoint.getSignature().toShortString(); counter.putIfAbsent(key, new AtomicInteger(0)); int count counter.get(key).incrementAndGet(); if (count rateLimit.limit()) { log.warn(接口限流key{}, count{}, limit{}, key, count, rateLimit.limit()); throw new BizException(ResultCodeEnum.RATE_LIMIT); } return joinPoint.proceed(); } }为什么用Around因为限流也要决定超过阈值时业务方法不执行注意这个是演示版真实生产一般用 Redis Lua / Sentinel / 网关限流十四、logback 配置 traceId路径resources/logback-spring.xml?xml version1.0 encodingUTF-8? configuration property nameLOG_PATTERN value%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [%X{traceId}] %-5level %logger{36} - %msg%n/ appender nameCONSOLE classch.qos.logback.core.ConsoleAppender encoder pattern${LOG_PATTERN}/pattern charsetUTF-8/charset /encoder /appender root levelINFO appender-ref refCONSOLE/ /root /configuration日志效果2026-04-25 10:00:01.123 [http-nio-8080-exec-1] [9f8a7b6c] INFO RequestLogAspect - 请求开始...2026-04-25 10:00:01.156 [http-nio-8080-exec-1] [9f8a7b6c] INFO RequestLogAspect - 请求结束...十五、Controller 示例package com.xxx.modules.user.controller; import com.xxx.shared.annotation.CheckPermission; import com.xxx.shared.annotation.OperationLog; import com.xxx.shared.annotation.RateLimit; import com.xxx.shared.result.Result; import org.springframework.web.bind.annotation.*; RestController RequestMapping(/user) public class UserController { OperationLog(module 用户模块, action 查询用户) GetMapping(/info/{id}) public ResultString getUser(PathVariable Long id) { return Result.success(用户ID id); } CheckPermission(user:create) OperationLog(module 用户模块, action 创建用户) PostMapping(/create) public ResultVoid createUser() { return Result.success(); } RateLimit(limit 5) GetMapping(/test-limit) public ResultString testLimit() { return Result.success(ok); } }十六、执行顺序说明当多个 AOP 同时存在时可以用Order控制顺序。Order 数字越小优先级越高建议顺序权限 / 限流 ↓ TraceId ↓ 请求日志 ↓ 操作日志 ↓ 业务方法示例Order(0) public class PermissionAspect { } Order(1) public class TraceIdAspect { } Order(2) public class RequestLogAspect { }十七、什么时候用哪个1. Before简单前置动作参数打印方法进入日志不适合权限拦截限流完整耗时统计2. AfterReturning成功返回日志成功统计成功埋点不适合异常处理完整链路日志3. AfterThrowing异常日志异常统计报警触发不适合成功返回控制业务流程4. After最终清理ThreadLocal 清理MDC 清理不适合返回值处理异常分类处理5. Around请求日志耗时统计权限拦截限流TraceId重试降级真实项目里最常用。十八、这套代码的价值这套工程化代码解决的是接口返回不统一异常处理混乱日志不好查没有请求链路权限判断散落限流逻辑侵入业务AOP 通知类型不知道怎么选完成后项目结构会更清晰Controller接请求Facade / Executor编排业务Biz / Service处理业务规则Repository处理数据shared处理基础设施能力十九、面试怎么讲可以这样说我在项目里做了一套基础工程化能力。首先接口统一使用 Result 返回结构包含 code、message、data方便前端统一处理。其次业务异常统一使用 BizException 抛出再通过 RestControllerAdvice 进行全局异常处理把异常转换成统一返回。然后我用 AOP 做了请求日志和 TraceId。TraceId 通过 MDC 放入日志上下文请求日志记录接口路径、请求方式、IP、参数、返回值、耗时和异常。另外我也梳理了 AOP 的几种通知类型Before 适合前置日志AfterReturning 适合成功返回统计AfterThrowing 适合异常日志After 适合清理资源Around 适合完整流程控制。在实际项目里权限校验、限流、请求日志、TraceId 这类需要控制完整流程的场景我会优先使用 Around。二十、总结这一篇的核心是把基础能力工程化几个核心关系Result 统一接口返回 BizException 主动抛业务异常 GlobalExceptionHandler 统一处理异常 Before / AfterReturning / AfterThrowing / After AOP 分段增强 Around AOP 完整流程控制 TraceId 串起一次请求的日志 RequestLogAspect 统一请求日志 OperationLogAspect 关键业务操作日志 PermissionAspect 权限校验 RateLimitAspect 限流保护最终形成请求进来↓权限 / 限流↓TraceId↓请求日志↓Controller↓Biz / Service↓异常统一处理↓Result 统一返回到这里Spring Boot 项目就从能跑的 demo升级成有企业工程结构的项目这就是中级后端必须具备的工程化意识。