直接切入：如果你已经在Spring Boot项目里用过AOP，大概率最先接触的是@Before、@AfterReturning这类前置或后置通知。用着用着会发现，它们拆开写确实简单，但要拿到一次完整调用链路的上下文、要统一处理异常、要在方法执行前后共享一份数据，就非常别扭。这时候就该上环绕通知（@Around）了。
这一篇我完整讲清楚环绕通知：它和其他通知的关系、底层原理、实际项目中怎么封装才不踩坑，以及我踩过之后回头梳理出来的一套设计习惯。内容偏实战，适合已经在用Spring Boot做业务开发、想在项目里用AOP做日志、权限、性能监控、重试机制的同学。
1. 为什么必须有环绕通知：其他四种通知的致命短板
1.1 四种基础通知的职责边界
Spring AOP里一共有五种通知类型，除了@Around，还有@Before、@AfterReturning、@AfterThrowing、@After。很多人最开始学的时候，会觉得“既然前置通知和后置通知都有了，还要环绕通知干什么？”
我举个具体场景你就明白。假设你要给一个下单接口加操作日志，需要记录这么几个信息：
- 方法入参是什么
- 方法返回值是什么
- 方法执行耗时多少
- 如果抛异常，异常信息是什么
用@Before + @AfterReturning + @AfterThrowing三件套，你也能抓数据，但数据是割裂的：@Before里拿到入参，存到一个成员变量或ThreadLocal里；@AfterReturning里拿到返回值，再存一份；@AfterThrowing里拿异常，又存一份。最后想去凑一份完整的日志时，需要跨多个通知方法去拼装，还得处理“前置通知执行了但后置通知没执行”这种状态分支。代码量翻倍不说，数据传递全靠上下文容器，并联调排错都很难受。
更要命的是，如果要在方法执行前判断“参数非法直接拦截”，在@Before里你能干这事，但你没有“终止方法继续执行”的控制权。你只能抛异常，让业务代码跟异常谷堆缠在一起。可如果你想优雅地返回一个默认值或错误码呢？在@Before里几乎做不到。
1.2 环绕通知的控制权：拦截、放行、改写一把抓
@Around是唯一一个能够完全包住目标方法执行过程的通知。它能代替前置、后置、异常、最终通知四者的组合，而且拥有三项独有能力：
第一，可以决定目标方法是否真正执行。参数校验不过，直接返回错误结果，不调用proceed()方法；想要幂等拦截，同样在proceed()之前就能挡住。
第二，可以篡改目标方法的返回值。无论原方法返回什么，环绕通知都可以在拿到结果后做包装、脱敏、二次计算，再返回给调用方。这在做接口统一响应包装时非常有用。
第三，可以在目标方法执行前后共享同一份上下文。一个方法体内，前后逻辑天然共享局部变量，不用再依赖外部容器传递数据。
从实现模型上看，环绕通知就是一个典型的装饰器模式：它包裹住真实的方法调用，调用方甚至感知不到这层装饰的存在。这也是AOP的核心价值——在不入侵业务代码的前提下，包裹一层通用逻辑。
所以在我的项目里，日志记录、耗时统计、限流控制、权限校验这类通用横切逻辑，我全部统一用@Around做。其他四种通知，基本只在我需要做极轻量的、单一维度的横切操作时才会用到。
2. 环绕通知的底层原理：ProceedingJoinPoint与代理机制
2.1 核心参数ProceedingJoinPoint到底是什么
@Around通知方法的入参必须是ProceedingJoinPoint，这是它与所有其他通知最明显的区别。其他通知拿的是JoinPoint，只有环绕通知能拿到ProceedingJoinPoint，因为ProceedingJoinPoint多了一个proceed()方法。
很多初学者第一次看到proceed()时会问：这个proceed()到底是怎么帮我执行原方法的？
其实拆开看就清楚了。ProceedingJoinPoint内部持有目标对象、目标方法、方法参数这三样核心信息。proceed()的作用就是通过反射、或者说通过代理链路，把当前拦截到的目标方法真实地调用一次。你把它理解成“调原方法的开关”：调用几次proceed()，原方法就被执行几次；一次都不调用，原方法就不会被触发。
这里有个非常重要的细节：proceed()可以被调用多次。比如我做重试机制时，第一次调用失败后，可以在catch块里再调用一次proceed()，实现方法级别的重试。这在其他通知类型里完全做不到。
ProceedingJoinPoint常用的方法有：
- getSignature()：拿到方法签名，从中获取方法名、类名、参数类型等信息
- getArgs()：拿到当前请求的参数数组，可以读取，也可以修改
- getTarget()：拿到目标对象实例（注意，是代理背后的真实对象）
- proceed()：执行目标方法
- proceed(Object[] args)：以新的参数数组执行目标方法，相当于可以动态篡改入参
其中proceed(Object[] args)用途很广，比如在AOP层对入参做统一加解密时，解密后通过新的参数数组放行，业务代码拿到的就是明文数据，完全无感知。
2.2 代理机制：JDK动态代理与CGLIB的抉择
Spring AOP底层依赖代理模式。一个类被AOP切中后，Spring不会直接把这个类的对象交给你用，而是生成一个代理对象。调用方实际调用的是代理对象的方法，代理对象再沿着通知链依次处理后，最终反射调用真实目标方法。
Spring Boot 2.x+默认使用CGLIB代理，这和Spring Boot 1.x时代默认JDK动态代理不同。两者核心区别在于：
- JDK动态代理只能代理接口，生成一个实现该接口的匿名代理类
- CGLIB通过生成目标类的子类来实现代理，不要求目标类实现接口
这一差异在实际项目中会带来一个典型坑：如果目标类不是接口实现类，并且你的Spring版本里默认策略还是JDK动态代理，AOP就会直接失效。Spring Boot 2.x之后默认开了CGLIB，所以大多数场景下不会遇到这个问题，但如果你是老项目升级或者手动构建代理，必须注意检查proxyTargetClass配置。
另外，CGLIB代理方式下，目标方法不能是final的，目标类也最好别是final的。因为CGLIB靠继承子类来覆盖方法，如果方法是final的，子类无法覆盖，通知自然也无法织入。这个在写切面时要时刻记得，避免给被切方法加final修饰。
2.3 通知链的调用顺序：环形嵌套结构
当多个切面同时命中同一个方法时，会组成一条通知链。环绕通知的执行顺序不是单纯的“先来后到”，而是嵌套结构：
切面A的@Around开始 -> 切面B的@Around开始 -> 目标方法执行 -> 切面B的@Around结束 -> 切面A的@Around结束
这种模型很像洋葱圈，或者一层套一层的俄罗斯套娃。每一个@Around方法都是“进入”和“出口”之间的一个完整闭环。这个机制直接影响了我们对切面顺序的认知：你在@Around前半部分写的逻辑，越靠外层切面越先执行；后半部分写的逻辑，越靠外层切面越后执行。
实际项目中，我使用@Order注解显式控制切面顺序，数字小的先执行。比如日志切面设为1，权限切面设为2，缓存切面设为3。没有特殊需求就别依赖默认顺序，因为不同版本、不同切面定义方式下默认顺序可能完全不一样，真出现问题时排查成本极高。
3. 完整实战：一个通用环绕通知模板的落地过程
3.1 先明确需求清单
在看代码之前，先统一认识：我们要写的这个环绕通知到底解决什么问题。我拿最通用的“接口日志记录与耗时统计”来演示，把它拆成需求点：
- 记录被调用方法的类名、方法名、入参、返回结果、异常信息、耗时
- 入参做脱敏处理，不能把密码、身份证这类敏感字段直接打出来
- 异常场景也要完整记录，但异常要继续往上抛，不能影响业务方原有的异常处理逻辑
- 提供一个开关，在配置中心动态控制日志切面的开启与关闭
这些需求点很典型，也几乎覆盖了环绕通知的核心能力。下面我按步骤落地。
3.2 自定义注解与切面骨架
第一步，定义一个注解，用来标记哪些方法需要被环绕通知管理。这样比直接写execution表达式精确得多，也更好维护。
@Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) public @interface OpLog { // 操作模块，比如"订单管理""用户中心" String module() default ""; // 操作类型，比如"insert""update""delete""query" String type() default ""; }第二步，定义切面类。这里我先给出一个完整的骨架，把核心流程写在startLog()方法里。
@Aspect @Component public class OpLogAspect { private static final Logger log = LoggerFactory.getLogger(OpLogAspect.class); @Around("@annotation(operationLog)") public Object around(ProceedingJoinPoint joinPoint, OpLog operationLog) throws Throwable { // 前置：记录开始时间、解析方法信息、打印入参 long start = System.currentTimeMillis(); String methodInfo = buildMethodInfo(joinPoint); Object[] args = joinPoint.getArgs(); if (log.isInfoEnabled()) { log.info("[OpLog] 开始 | {} | 入参: {}", methodInfo, LogMask.maskArgs(args)); } Object result = null; Throwable throwable = null; try { // 核心：放行目标方法 result = joinPoint.proceed(); return result; } catch (Throwable t) { throwable = t; throw t; } finally { long cost = System.currentTimeMillis() - start; if (throwable != null) { log.error("[OpLog] 异常 | {} | 异常信息: {} | 耗时: {}ms", methodInfo, throwable.getMessage(), cost); } else { log.info("[OpLog] 结束 | {} | 返回: {} | 耗时: {}ms", methodInfo, LogMask.maskResult(result), cost); } } } private String buildMethodInfo(ProceedingJoinPoint joinPoint) { MethodSignature signature = (MethodSignature) joinPoint.getSignature(); String className = signature.getDeclaringTypeName(); String methodName = signature.getName(); return className + "#" + methodName; } }注意两个关键点：
第一，我用了try-finally而不是try-catch-finally，并且在catch里将异常重新抛出。这样做的目的是既拿到异常信息用于记录，又不改变原方法的异常传播路径。很多初学者会在catch里打印完日志后忘记重新抛出，结果上层业务完全感知不到异常，数据还能正常提交，这在业务系统中是非常严重的事故。
第二，我特意把result和throwable两个变量定义在try外部，是为了在finally里能够同时判断是否发生异常。如果你在catch里直接打印日志，那正常路径的日志就得在try块最后单独打一份，代码就冗余了。
3.3 入参脱敏：一个容易被忽略的细节
日志切面的最大隐患是“把不该打的打出来了”，比如用户密码、身份证、手机号明文。以前我们做过一次线上复盘，就是因为日志里打印了完整密码，然后日志文件又被泄露出去，导致用户隐私事件。所以我在日志切面里强制加了脱敏处理。
public class LogMask { public static String maskArgs(Object[] args) { if (args == null || args.length == 0) { return "[]"; } List<String> maskedList = new ArrayList<>(); for (Object arg : args) { maskedList.add(maskObject(arg)); } return maskedList.toString(); } private static String maskObject(Object obj) { if (obj == null) { return "null"; } // 如果对象包含敏感字段，统一转JSON后按key脱敏 try { String json = JSON.toJSONString(obj); json = json.replaceAll("(\"password\"\\s*:\\s*)\"[^\"]*\"", "$1\"******\""); json = json.replaceAll("(\"idCard\"\\s*:\\s*)\"[^\"]*\"", "$1\"******\""); return json; } catch (Exception e) { return obj.toString(); } } }这里的正则替换方式适合演示，真实项目里更推荐写一个通用的脱敏工具类，基于Jackson的ValueFilter或者自定义序列化器来实现。对于返回结果的脱敏同理，但这里有个实战建议：返回结果如果是一个大型分页对象，全部序列化会导致日志体积非常大，建议只截取前几百个字符，后面用省略号表示。
3.4 配置开关：让切面可以随时下线
切面挂在核心业务上时最怕什么？最怕切面自身逻辑出问题，比如序列化超时、日志打印卡IO，导致整个接口变慢甚至报错。所以线上规范里我会要求日志切面必须有开关，可以随时通过配置中心一键下线。
@Component @ConfigurationProperties(prefix = "oplog") public class OpLogConfig { // 是否开启操作日志切面，默认开启 private boolean enabled = true; // getter、setter省略 }然后在切面方法开头加一个判断：
@Around("@annotation(operationLog)") public Object around(ProceedingJoinPoint joinPoint, OpLog operationLog) throws Throwable { if (!opLogConfig.isEnabled()) { return joinPoint.proceed(); } // 原有逻辑... }这个判断必须放在切面方法的第一行，而且开关关闭时直接放行目标方法，不做任何额外处理。这样即使后续有人往切面里塞了很重的逻辑，只要开关关掉，整条切面链路就等于没存在过。这个点在技术上很简单，但极少有人一开始就做到，等你真被线上日志切面拖垮过一次就长记性了。
4. 环绕通知的高阶玩法：重试、限流、缓存穿透防护
4.1 基于proceed()多次调用的方法重试
上一节讲了日志切面，这一节我把环绕通知更硬核的用法展开。之所以环绕通知能实现重试，核心就在proceed()可以被调用多次。
举个例子，假设我们的支付结果查询接口偶尔因为网络抖动会抛出通讯异常，业务上允许重试两次。我们用环绕通知来实现一个通用的重试切面：
@Aspect @Component public class RetryAspect { @Around("@annotation(retry)") public Object retry(ProceedingJoinPoint joinPoint, Retry retry) throws Throwable { int maxAttempts = retry.attempts(); Throwable lastThrowable = null; for (int i = 0; i < maxAttempts; i++) { try { // 执行目标方法，如果成功则直接返回，不进入下一次循环 return joinPoint.proceed(); } catch (Throwable t) { lastThrowable = t; // 判断是否应该重试：按条件过滤，比如只对网络异常重试 if (!shouldRetry(t, retry)) { throw t; } // 等待间隔，避免快速连续重试加重下游压力 Thread.sleep(retry.intervalMillis()); } } // 达到最大重试次数仍然失败，抛出最后一次异常 throw lastThrowable; } private boolean shouldRetry(Throwable t, Retry retry) { for (Class<? extends Throwable> clazz : retry.retryFor()) { if (clazz.isAssignableFrom(t.getClass())) { return true; } } return false; } }这样定义的好处是重试策略跟业务解耦，你只需要在需要重试的方法上打一个@Retry注解，业务代码里完全不用写循环。我在项目里还加了一个时间衰减策略：第一次重试间隔100ms，第二次200ms，避免重试流量瞬间洪峰打到下游。
但这里必须提醒一句：重试切面只能解决瞬时异常，对于幂等性要求极高的写操作，要谨慎。如果目标方法已经写入了数据但在返回前抛异常，重试就可能导致重复插入。写操作要用重试，必须在业务表里带上幂等键，否则宁可只对查询或对通讯类操作做重试。
4.2 基于方法级参数的简单限流
限流在Spring Boot里通常会引入Guava的RateLimiter或Redis+Lua脚本，但如果你只想对极少数热点方法做一层轻量保护，用环绕通知也能快速实现。
我先给出一个基于Guava RateLimiter演示版：
@Component public class RateLimitAspect { private final Map<String, RateLimiter> limiterMap = new ConcurrentHashMap<>(); @Around("@annotation(rateLimit)") public Object limit(ProceedingJoinPoint joinPoint, RateLimit rateLimit) throws Throwable { RateLimiter limiter = limiterMap.computeIfAbsent(rateLimit.key(), k -> RateLimiter.create(rateLimit.qps())); // 尝试获取令牌 boolean acquired = limiter.tryAcquire(rateLimit.timeout(), TimeUnit.MILLISECONDS); if (!acquired) { // 限流触发，返回降级结果 throw new RateLimitException("当前请求过多，请稍后再试"); } return joinPoint.proceed(); } }这里我用了ConcurrentHashMap缓存每个方法对应的RateLimiter对象，避免每次请求都重新构建一个令牌桶。如果项目已经接了Redis，推荐用Redis+Lua做分布式限流，因为单机RateLimiter在微服务多实例部署时会导致整体限流失效，每台机器的阈值叠加后就不是你配置的QPS了。
4.3 缓存穿透的场景：环绕通知里做空值缓存
缓存切面也经常用@Around实现。但有一类细节值得单独讲，就是缓存空值。
假设一个用户详情接口，先查缓存，缓存没有就查数据库，查不到则返回null。如果直接对null做缓存，很多缓存框架默认不支持缓存空值，导致每次请求都会穿透到数据库，数据库压力全被打满。
在环绕通知里你可以这样做：拿到proceed()的结果后，如果发现结果为空且允许缓存空值，就手动构造一个空对象占位，并设置较短过期时间。这样就可以有效缓存穿透。
Object result = joinPoint.proceed(); if (result == null && cacheNull) { // 设置短过期时间的占位空值，比如 5 分钟 cacheService.set(cacheKey, NULL_PLACEHOLDER, 300); } return result;这种细节在面试里经常被拿出来问，但在实际项目里它往往比高深的技术更能救命。缓存穿透、击穿、雪崩三重问题里，穿透是最好解决也最容易被忽略的，靠一个短时空值就能挡掉大量无效DB查询。
5. 环绕通知高频踩坑清单：每一个都是线上教训
5.1 自调用导致AOP失效
这是新手最容易踩的第一个大坑，我来演示一个典型的例子：
@Service public class OrderService { public void createOrder(Order order) { // 业务逻辑... sendMessage(order.getId()); } @OpLog(module = "消息通知") public void sendMessage(Long orderId) { // 业务逻辑... } }当你从createOrder()方法内部直接调用this.sendMessage()时，@OpLog切面不会生效。因为这里是普通方法调用，走的是真实对象引用，而不是代理对象。只有从外部注入OrderService时，拿到的才是代理对象，调用代理对象的方法时AOP才会拦截。
解决办法有几种：
第一种：把需要被切的逻辑拆到另一个Service里，注入后调用。这是最推荐的做法，结构清晰，代理能正常生效。
第二种：在类内部注入自身代理，比如通过ObjectProvider或@Lazy注入，然后通过代理对象调用自身方法。这种方式能够达到目的，但代码可读性差，不推荐在多人协作项目里铺开。
第三种：使用AopContext.currentProxy()，前提是配置exposeProxy=true。这种方式效率不高，而且依赖上下文，容易出问题。
5.2 在环绕通知里吞掉异常导致事务失效
这个坑在校招同学写的代码里出现次数非常高，而且后果很严重。
很多人在环绕通知里写了try-catch后，把异常吞掉或者只记录日志不抛出，然后继续返回一个默认结果。对于GetMapping接口来说这可能看起来没啥问题，但一旦目标方法上标了@Transactional，这个坑就会破坏事务。
Spring事务的本质是：事务管理器拦截方法，方法抛出异常时触发回滚。如果你的环绕通知在事务通知的外层把异常吞掉了，事务管理器根本感知不到异常，自然就不会回滚。结果就是数据已经写了，上层还觉得调用成功了，线上数据出现“诡异的部分写入”状态。
我的建议是：环绕通知永远不要吞异常。除非你有非常明确的降级语义，并且业务方能接受降级结果，否则异常一定要原样抛出。如果你确实需要既记录异常又继续向上抛，就用我前面日志切面里的写法：catch后重新throw。
5.3 切点表达式写得太宽，误伤无关方法
@Around配上execution(* com.example...(..))这种粗粒度表达式，会拦截到所有类所有方法，包括Spring内部的一些回调方法也会被卷入，常常导致意想不到的问题。比如有些对象在Spring容器初始化阶段被代理，切面里又依赖了更高优先级的Bean，就可能触发循环依赖或初始化顺序异常。
我的习惯是优先用自定义注解标记目标方法，比如@OpLog、@Retry，而不是用execution表达式一把梭。自定义注解的好处有三个：第一，精确控制范围，避免误伤；第二，同一个注解可以携带参数，让切面逻辑更通用；第三，代码仓库里搜注解就能知道哪些接口被切了，可维护性远高于纯表达式。
如果你想用execution表达式控制范围，尽量按方法级签名来写，并且严格控制包路径，定期做Review。真实线上出现过一次事故：有人把execution表达式写成com.example...(..) 拦截了所有Service方法，导致日志切面为每次查询都做了一次JSON序列化和一次性全量日志输出，整个接口RT从50ms涨到2秒。
5.4 环绕通知里的性能开销问题
环绕通知虽然好用，但也不是免费的。每一次代理调用都会增加栈深度、反射调用开销以及切面自身代码的执行消耗。如果切面里还有大对象序列化、远程调用、加锁操作，那对主链路的影响会非常明显。
一个经验值：日志类切面里，不要同步打印太长的内容，如果确实要打全量日志，建议用异步日志框架或直接发到消息队列。入参和返回值的JSON序列化只在log.isInfoEnabled()为true时才执行，避免在生产环境日志级别调整后白白付出序列化成本。还有，切面里的代码尽量保持轻量，任何缓存、限流、鉴权逻辑都提前评估耗时，超过毫秒级就要考虑是否值得放在这条链路上。
我见过一个真实案例：某团队在环绕通知里加了反作弊查询，每次调用都查一次远程规则库，接口平均耗时增加了900ms，最后上线第二天就被迫下线。核心问题不是切面方案不对，而是把一个重操作塞进了通用拦截链路，导致所有被切接口都遭殃。
5.5 多切面协作时的顺序混乱
当多个环绕通知同时作用于一个方法时，顺序控制是多切面开发中最容易失控的地方。在没有@Order注解的情况下，切面顺序完全取决于Spring内部对Bean的加载顺序，显得相当随机。
我建议在一个项目里建立以下规范：
- 所有切面类都必须指定@Order
- 按业务优先级从高到低排序：性能监控（最高，尽量靠外） > 日志 > 幂等/防重 > 缓存 > 事务 > 异常转换（最靠内）
- 编号统一从0开始，每5一档预留扩展位
为什么性能监控要放在最外层？因为如果要统计整条AOP链路上的完整耗时，性能监控切面必须被第一个进入、最后一个退出。越外层的切面，记录的耗时越接近API整体耗时。如果你把性能监控放在最内层，它统计出的就只是目标方法本身的时间，链路开销全丢了。
5.6 加解密、脱敏等AOP操作与参数修改的边界
最后提一个很实际的问题：环绕通知对参数和返回值的修改，作用范围到底有多大？
通过proceed(args)修改参数时，修改的是传给被代理方法的参数值，这会影响调用链上的下游逻辑。但如果目标方法内部把参数对象引用赋值给了其他局部变量，你再改同一个对象引用指向的属性，是能同步生效的。所以这里有个重要区分：修改参数对象的内容是生效的，直接替换整个参数对象则需要通过proceed(newArgs)传入。
返回值同理。你可以在环绕通知里对返回值做包装、脱敏、二次处理。但如果目标方法返回值是final的或者基础类型，只能通过重新构造新值返回。切面的处理结果最终会替代原返回值传给上层调用方，所以在做返回值包装时一定注意接口契约，比如原方法返回null表示“未找到”，你的切面就不该擅自改成一个空对象，否则上层判空逻辑会直接失效。
6. 从“会用@Around”到“写好多层切面”的思路升级
我看了很多项目里的AOP代码，最大的问题不是不会用@Around，而是没有把切面当成一个独立的“中间件”来设计。环绕通知的写法本身不难，难的是把切面之间的层次感设计出来、把每个切面的职责边界划定清楚。
好的实践应该是：每个切面只做一件事。日志切面只负责记录，不掺和权限判断；权限切面只负责校验，不顺手改业务返回值；缓存切面只负责存取，不把缓存空值时长写死。如果两个切面都要改动目标方法的返回值，你需要非常明确它们的前后顺序以及各自改动的范围，否则日志里打印的可能就是权限切面包装过的结果，而不是目标方法的原始返回。
我在做团队Code Review时，会特别关注环绕通知里的代码规模。一个@Around方法超过50行，通常意味着职责过重，请拆开。一句简单的原则：环绕通知包裹的是目标方法，但它本身也是一段需要能被读懂的代码。当别人打开你的切面类时，他应该能在10秒内说出这个切面做了什么、会影响到哪些方法、出问题时怎么关掉它。
Spring AOP是个好工具，但它只是众多横切手段的一种。环绕通知能搞定的事，往往也意味着你正在往业务代码里塞一些通用的逻辑。如果你的项目里已经有了这种通用切面，建议给它们配上完整的开关和监控指标，有开关才有兜底方案，有指标才能提前发现异常增长。
这一篇把环绕通知从原理到实战到踩坑都梳理了一遍，希望对正在做Spring Boot项目的同学有帮助。如果你在做AOP方案时遇到过更隐蔽的问题，欢迎在评论区交流。
