/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后,紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}
文章目录
- 一、为什么需要 AOP
- 二、准备可运行项目
-
- 2.1 项目结构
- 2.2 Maven 依赖
- 2.3 启动类与业务类
- 三、第一个切面:统计方法耗时
-
- 3.1 编写环绕通知
- 3.2 为什么使用 try/finally
- 3.3 用测试触发切面
- 四、必须分清的核心概念
-
- 4.1 切面 Aspect
- 4.2 连接点与切点不是一回事
- 4.3 目标对象与代理对象
- 4.4 织入 Weaving
- 五、五类通知详解
-
- 5.1 @Before:前置通知
- 5.2 @AfterReturning:返回后通知
- 5.3 @AfterThrowing:异常后通知
- 5.4 @After:后置通知
- 5.5 @Around:环绕通知
- 六、JoinPoint 能获取什么
- 七、用 @Pointcut 复用切点
-
- 7.1 为什么不要到处复制表达式
- 7.2 把公共切点集中管理
- 八、execution 切点表达式
-
- 8.1 基本结构
- 8.2 常见示例
-
- 匹配某个类的所有方法
- 只匹配 public 方法
- 只匹配返回 String 的方法
- 匹配只有一个 String 参数的方法
- 第一个参数是 String,后面可以有其他参数
- 匹配当前包及子包中各类的方法
- 匹配名称以 Service 结尾的类
- 8.3 通配符速查
- 8.4 编写表达式的实用方法
- 九、其他常用切点指示符与组合
-
- 9.1 within
- 9.2 bean
- 9.3 this 与 target
- 9.4 组合切点
- 十、自定义注解:只增强标记的方法
-
- 10.1 定义注解
- 10.2 标记业务方法
- 10.3 在切面中绑定注解
- 十一、多个切面怎样排序
- 十二、正常返回与异常退出分别发生什么
-
- 12.1 成功路径
- 12.2 异常路径
- 12.3 环绕通知不要吞异常
- 十三、代理模式:理解 Spring AOP 的前置知识
-
- 13.1 静态代理
- 13.2 JDK 动态代理
- 十四、Spring 的 JDK 代理与 CGLIB 代理
-
- 14.1 Spring Framework 的基本选择
- 14.2 Spring Boot 默认使用 CGLIB
- 14.3 AspectJ 自动代理配置
- 十五、为什么有些方法不会被增强
-
- 15.1 自调用失效
- 15.2 final 类与 final 方法
- 15.3 private 方法
- 15.4 对象不是 Spring Bean
- 15.5 切点没有匹配
- 十六、Spring AOP 与 AspectJ 的关系
- 十七、完整整合示例
-
- 17.1 OrderService
- 17.2 TimeAspect
- 17.3 OperationLogAspect
- 17.4 OrderLifecycleAspect
- 17.5 预期行为
- 十八、怎样测试 AOP,而不只是看日志
-
- 18.1 测试返回值与异常传播
- 18.2 用测试切面记录通知是否执行
- 18.3 测试多个切面的嵌套顺序
- 十九、实战中的设计原则
-
- 19.1 一个切面聚焦一种职责
- 19.2 优先使用能力最弱的通知
- 19.3 不要把 AOP 日志变成敏感数据出口
- 19.4 不要在通用切面里随意重试
- 19.5 注意通知自身的异常
- 19.6 AOP 不等于所有横切问题的唯一答案
- 二十、常见问题排查表
- 二十一、上线前检查清单
-
- 切点与通知
- 参数与注解
- 代理与顺序
- 业务安全
- 二十二、总结
- 参考资料
-
适合读者:已经能创建 Spring Boot 项目、编写简单的 Service,但对 AOP 注解、切点表达式和代理机制还不熟悉的开发者。
-
验证基线:JDK 17、Spring Boot 3.5.8、Maven。这个版本只是示例的验证环境,并不表示它是所有项目唯一可用的版本。
-
示例验证:正常返回、异常退出、五类通知、注解绑定、自调用失效、多个切面的顺序以及 Spring Boot 默认 CGLIB 代理均已通过自动化测试。
一、为什么需要 AOP
假设订单服务中有三个业务方法:
public String createOrder(String item) {
long start = System.nanoTime();
System.out.println("开始创建订单,商品:" + item);
String result = doCreateOrder(item);
System.out.println("创建订单结束");
System.out.println("耗时:" + (System.nanoTime() – start) + " ns");
return result;
}
public String cancelOrder(String orderId) {
long start = System.nanoTime();
System.out.println("开始取消订单,订单号:" + orderId);
String result = doCancelOrder(orderId);
System.out.println("取消订单结束");
System.out.println("耗时:" + (System.nanoTime() – start) + " ns");
return result;
}
业务逻辑本来只有“创建订单”和“取消订单”,但耗时统计、操作日志却散落到了每个方法中。继续增加权限检查、审计记录后,会出现三个问题:
这类横跨多个模块、又不是某个模块核心职责的逻辑,称为横切关注点(cross-cutting concern)。典型例子包括日志、事务、安全检查和性能统计。AOP,即 Aspect-Oriented Programming 面向切面编程,提供了一种把这些逻辑模块化,再应用到目标方法上的方式。
AOP 不是替代 OOP,而是补充 OOP:
| OOP | 用对象封装数据与业务行为 | Order、OrderService、库存对象 |
| AOP | 用切面封装跨对象的通用行为 | 操作日志、耗时统计、事务边界 |
Spring AOP 的目标不是拦截 Java 程序中的一切动作,而是为 Spring 管理的对象提供一种简洁的企业级 AOP 能力。它常与 Spring IoC 容器配合使用,切面本身也可以是普通 Spring Bean。
二、准备可运行项目
2.1 项目结构
先创建一个 Maven 项目:
aop-demo
├── pom.xml
└── src
├── main
│ ├── java/com/example/demo
│ │ ├── DemoApplication.java
│ │ ├── OrderService.java
│ │ ├── TimeAspect.java
│ │ ├── OrderLifecycleAspect.java
│ │ ├── OperationLog.java
│ │ └── OperationLogAspect.java
│ └── resources
│ └── application.yml
└── test
└── java/com/example/demo
└── DemoApplicationTests.java
快速入门只需要前三个业务相关文件。后面的类会用于演示五类通知、自定义注解和参数绑定。
2.2 Maven 依赖
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.5.8</version>
<relativePath/>
</parent>
<groupId>com.example</groupId>
<artifactId>aop-demo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<properties>
<java.version>17</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-aop</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
spring-boot-starter-aop 会带入 Spring AOP 和 @AspectJ 风格所需的 AspectJ Weaver 组件。这里使用的是 AspectJ 的注解、表达式和解析能力,不意味着项目已经启用了 AspectJ 编译器或加载期织入。
2.3 启动类与业务类
启动类:
package com.example.demo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}
业务类:
package com.example.demo;
import org.springframework.stereotype.Service;
@Service
public class OrderService {
public String createOrder(String item) {
return "ORDER-" + item;
}
public String fail() {
throw new IllegalStateException("库存不足");
}
}
application.yml 可以先只写应用名:
spring:
application:
name: aop–demo
三、第一个切面:统计方法耗时
3.1 编写环绕通知
package com.example.demo;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;
@Aspect
@Component
public class TimeAspect {
private static final Logger log = LoggerFactory.getLogger(TimeAspect.class);
@Around("execution(* com.example.demo.OrderService.*(..))")
public Object recordTime(ProceedingJoinPoint pjp) throws Throwable {
long start = System.nanoTime();
try {
return pjp.proceed();
} finally {
long elapsedMillis = (System.nanoTime() – start) / 1_000_000;
log.info("{} 执行耗时 {} ms", pjp.getSignature(), elapsedMillis);
}
}
}
这段代码包含两个必要注解:
- @Aspect:告诉 Spring 这个类包含切面逻辑;
- @Component:把切面注册为 Spring Bean。
只写 @Aspect、不让 Spring 管理这个对象,是“切面不生效”的常见原因之一。在 Spring Boot 的组件扫描范围内,两个注解一起使用是最直接的方式。
@Around 表示环绕通知。切点表达式匹配 OrderService 的所有方法,pjp.proceed() 表示继续执行调用链。若后面还有其他通知,就先执行下一个通知;到达调用链末端时,才执行真正的业务方法。
3.2 为什么使用 try/finally
下面这种写法只统计成功调用:
long start = System.nanoTime();
Object result = pjp.proceed();
long elapsedMillis = (System.nanoTime() – start) / 1_000_000;
log.info("执行耗时 {} ms", elapsedMillis);
return result;
一旦 proceed() 抛出异常,后面的日志就不会执行。使用 try/finally 后,无论目标正常返回还是异常退出,都能记录耗时,同时不会吞掉异常。
耗时测量使用 System.nanoTime(),是因为它适合计算时间间隔;System.currentTimeMillis() 表示墙上时钟,可能受系统时间校准影响。日志只用于观察,不要据此把纳秒差值当作高精度性能基准测试。
3.3 用测试触发切面
在 src/test/java/com/example/demo/DemoApplicationTests.java 中写入:
package com.example.demo;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
@SpringBootTest
class DemoApplicationTests {
@Autowired
private OrderService orderService;
@Test
void createOrderReturnsResult() {
assertThat(orderService.createOrder("BOOK"))
.isEqualTo("ORDER-BOOK");
}
@Test
void exceptionStillPropagates() {
assertThatThrownBy(orderService::fail)
.isInstanceOf(IllegalStateException.class)
.hasMessage("库存不足");
}
}
运行:
mvn clean test
测试日志中会出现方法签名和耗时。第二个测试还说明:环绕通知记录日志后,业务异常仍继续向调用方传播,没有被意外吞掉。
四、必须分清的核心概念
AOP 术语较多,但它们分别回答不同问题。
| Aspect | 切面 | 通用逻辑封装在哪里? | TimeAspect |
| Join point | 连接点 | 程序执行到了哪个可增强的位置? | 调用 createOrder 方法 |
| Pointcut | 切点、切入点 | 哪些连接点需要匹配? | OrderService 的所有方法 |
| Advice | 通知、增强 | 匹配后执行什么动作? | 记录耗时 |
| Target object | 目标对象 | 真正执行业务逻辑的是谁? | 原始 OrderService 对象 |
| AOP proxy | AOP 代理 | 调用方实际拿到的是谁? | Spring 创建的代理对象 |
| Weaving | 织入 | 切面怎样与目标结合? | Spring AOP 在运行时创建代理 |
4.1 切面 Aspect
切面是横切关注点的模块化封装。一个切面通常包含:
- 一个或多个切点;
- 一个或多个通知;
- 通知需要的辅助状态或依赖。
下面是一个最小结构:
@Aspect
@Component
public class TimeAspect {
@Around("某个切点表达式")
public Object recordTime(ProceedingJoinPoint pjp) throws Throwable {
return pjp.proceed();
}
}
@Around 方法中的代码是通知,字符串表达式是切点,整个类是切面。
4.2 连接点与切点不是一回事
连接点是程序执行过程中的一个点。在 Spring AOP 中,连接点始终表示方法执行。切点则是一个用于匹配连接点的谓词。 不能把它理解成“被切点匹配之后才叫连接点”。正确关系是:
候选方法执行连接点
↓
切点进行匹配
↓
匹配成功 → 应用通知
匹配失败 → 不应用该通知
4.3 目标对象与代理对象
目标对象包含真正的业务代码。Spring 为它创建代理后,容器中的相关 Bean 引用通常指向代理。外部调用先进入代理,代理再组织通知链和目标方法调用。
调用方
↓
AOP 代理
↓
前置、环绕等通知
↓
目标对象的业务方法
↓
通知链按规则返回
↓
调用方得到结果或异常
这也是自调用失效、方法可见性限制等问题的根源,后面会专门分析。
4.4 织入 Weaving
织入是把切面与目标类型或对象结合起来的过程。完整 AspectJ 支持编译期、编译后或加载期织入;Spring AOP 使用运行时织入,在 Bean 创建过程中生成代理。
五、五类通知详解
Spring 的 @AspectJ 风格支持五类通知。
| @Before | 目标方法执行前 | 参数检查、记录开始事件 | 通常不能,除非抛出异常 |
| @AfterReturning | 目标方法正常返回后 | 记录返回值、成功后处理 | 目标已执行完 |
| @AfterThrowing | 目标方法因异常退出时 | 记录异常、失败审计 | 目标已异常退出 |
| @After | 正常或异常退出后 | 类似 finally 的清理 | 目标已执行或已尝试执行 |
| @Around | 包围目标方法 | 耗时、重试、流程控制 | 可以 |
官方建议始终使用满足需求的、能力最弱的通知类型。例如,只需在方法前记录参数时,使用 @Before 比 @Around 更简单,也不容易忘记调用 proceed() 或丢失返回值。
5.1 @Before:前置通知
@Before("execution(* com.example.demo.OrderService.*(..))")
public void before(JoinPoint joinPoint) {
log.info("准备调用 {}", joinPoint.getSignature());
}
如果前置通知正常返回,调用链会继续。如果前置通知抛出异常,目标方法通常不会执行。
不要在 @Before 中编写耗时统计的“后半段”并假设目标一定成功;成功与异常需要分别处理。
5.2 @AfterReturning:返回后通知
@AfterReturning(
pointcut = "execution(* com.example.demo.OrderService.createOrder(..))",
returning = "result"
)
public void afterReturning(Object result) {
log.info("正常返回:{}", result);
}
returning = "result" 必须与通知方法参数名 result 一致。这样可以把目标方法的返回值绑定到通知中。
如果只想接收特定返回类型,可以缩小参数类型:
@AfterReturning(
pointcut = "execution(* com.example.demo.OrderService.createOrder(..))",
returning = "result"
)
public void afterReturning(String result) {
log.info("订单结果:{}", result);
}
返回后通知可以观察或处理返回值对象,但不要把它当成通用的“替换任意返回值”工具。需要控制是否执行目标、修改调用流程或统一处理返回值时,才考虑环绕通知。
5.3 @AfterThrowing:异常后通知
@AfterThrowing(
pointcut = "execution(* com.example.demo.OrderService.*(..))",
throwing = "exception"
)
public void afterThrowing(IllegalStateException exception) {
log.warn("业务异常:{}", exception.getMessage());
}
throwing = "exception" 对应方法参数名。IllegalStateException 同时起到匹配限制作用:只有抛出的异常与参数类型兼容时,该通知才执行。
如果希望接收所有异常,可以使用:
@AfterThrowing(pointcut = "orderOperations()", throwing = "exception")
public void afterThrowing(Throwable exception) {
log.error("调用异常", exception);
}
记录异常时应把异常对象作为日志参数传入,保留堆栈。只写 exception.getMessage() 会丢失堆栈,适合作为简短业务提示,不应成为唯一的错误日志。
异常后通知如果只是记录而不主动抛出异常,原业务异常仍会继续传播。它不会自动把失败转换为成功。
5.4 @After:后置通知
@After("execution(* com.example.demo.OrderService.*(..))")
public void after(JoinPoint joinPoint) {
log.info("调用结束:{}", joinPoint.getSignature());
}
它的语义类似 finally:目标正常返回和异常退出时都会执行。适合记录“调用已结束”或执行必要的通用清理。
不要把 @AfterReturning 与 @After 混为一谈:
- @AfterReturning 只在正常返回时执行;
- @After 两种结果都会执行。
5.5 @Around:环绕通知
环绕通知能力最强,也最容易写错。基本模板如下:
@Around("execution(* com.example.demo.OrderService.*(..))")
public Object around(ProceedingJoinPoint pjp) throws Throwable {
// 目标执行前的逻辑
Object result = pjp.proceed();
// 目标正常返回后的逻辑
return result;
}
第一个参数应是 ProceedingJoinPoint,它继承自 JoinPoint,额外提供 proceed()。
常见、通用的返回类型写法是 Object。这并不表示注解在语法上强制所有环绕通知“只能写 Object”;真正需要保证的是:通知链最终向调用方返回兼容的结果,并正确传播异常。初学阶段使用 Object 并返回 pjp.proceed() 的结果最不容易出错。
下面几种写法具有完全不同的含义:
// 目标方法不会执行,调用方收到 null。
@Around("execution(* com.example.demo.OrderService.createOrder(..))")
public Object skipTarget(ProceedingJoinPoint pjp) {
return null;
}
// 目标方法执行了,但真实返回值被丢弃。
@Around("execution(* com.example.demo.OrderService.createOrder(..))")
public Object discardResult(ProceedingJoinPoint pjp) throws Throwable {
pjp.proceed();
return null;
}
// 保留真实返回值。
@Around("execution(* com.example.demo.OrderService.createOrder(..))")
public Object keepResult(ProceedingJoinPoint pjp) throws Throwable {
return pjp.proceed();
}
proceed() 可以调用零次、一次,某些场景下也可以多次。重复调用意味着目标可能执行多次,绝不是“重试机制”的免费替代品:涉及数据库写入、支付或消息发送时,必须先评估幂等性。
六、JoinPoint 能获取什么
任何通知都可以把 JoinPoint 声明为第一个参数;环绕通知使用其子接口 ProceedingJoinPoint。
@Before("execution(* com.example.demo.OrderService.*(..))")
public void inspect(JoinPoint joinPoint) {
Object[] args = joinPoint.getArgs();
Object proxy = joinPoint.getThis();
Object target = joinPoint.getTarget();
Signature signature = joinPoint.getSignature();
log.info("参数:{}", Arrays.toString(args));
log.info("代理类型:{}", proxy.getClass().getName());
log.info("目标类型:{}", target.getClass().getName());
log.info("方法签名:{}", signature);
}
| getArgs() | 当前方法参数 | 日志中避免输出密码、证件号等敏感数据 |
| getThis() | 当前代理对象 | 通常是调用方实际持有的对象 |
| getTarget() | 被代理的目标对象 | 真正包含业务方法实现 |
| getSignature() | 方法签名描述 | 适合记录类名、方法名等 |
还可将 Signature 转成 MethodSignature,进一步读取方法信息:
MethodSignature signature = (MethodSignature) joinPoint.getSignature();
Method method = signature.getMethod();
String methodName = method.getName();
如果只是为了读取自定义注解,优先使用后文的 @annotation 参数绑定,通常比手动反射更直接。
七、用 @Pointcut 复用切点
7.1 为什么不要到处复制表达式
多个通知都匹配同一组方法时,复制表达式会增加维护成本:
@Before("execution(* com.example.demo.OrderService.*(..))")
public void before() {
}
@After("execution(* com.example.demo.OrderService.*(..))")
public void after() {
}
可以提取命名切点:
@Pointcut("execution(* com.example.demo.OrderService.*(..))")
public void orderOperations() {
}
@Before("orderOperations()")
public void before(JoinPoint joinPoint) {
log.info("准备调用 {}", joinPoint.getSignature());
}
@After("orderOperations()")
public void after(JoinPoint joinPoint) {
log.info("调用结束 {}", joinPoint.getSignature());
}
@Pointcut 方法的返回类型必须是 void,方法体通常为空。它的作用是为表达式命名,不是定义一个需要手动调用的业务方法。
7.2 把公共切点集中管理
多个切面共享切点时,可以定义公共类:
package com.example.demo;
import org.aspectj.lang.annotation.Pointcut;
public class CommonPointcuts {
@Pointcut("execution(* com.example.demo..*Service.*(..))")
public void serviceLayer() {
}
@Pointcut("@annotation(com.example.demo.OperationLog)")
public void operationLogged() {
}
}
其他切面使用完整方法名引用:
@Before("com.example.demo.CommonPointcuts.serviceLayer()")
public void beforeService() {
log.info("进入 Service 层");
}
公共切点适合表达稳定的架构边界,例如 Service 层、Web 层或某个业务模块。不要为了减少表达式数量,把互不相关的方法强行塞进一个庞大切点。
八、execution 切点表达式
execution 是最常用的切点指示符,用于匹配方法执行连接点。
8.1 基本结构
execution(
modifiers-pattern?
ret-type-pattern
declaring-type-pattern?
name-pattern(param-pattern)
throws-pattern?
)
带问号的部分可以省略。常见形式可简化为:
execution(返回类型模式 包名.类名.方法名(参数模式))
例如:
execution(* com.example.demo.OrderService.createOrder(..))
对应关系如下:
| 返回类型 | * | 任意返回类型,包括 void |
| 声明类型 | com.example.demo.OrderService | 指定类 |
| 方法名 | createOrder | 指定方法 |
| 参数 | (..) | 任意数量、任意类型参数 |
8.2 常见示例
匹配某个类的所有方法
execution(* com.example.demo.OrderService.*(..))
只匹配 public 方法
execution(public * com.example.demo.OrderService.*(..))
只匹配返回 String 的方法
execution(String com.example.demo.OrderService.*(..))
匹配只有一个 String 参数的方法
execution(* com.example.demo.OrderService.*(String))
在 execution 的参数模式中,简单类型名 String 可用于匹配 java.lang.String。复杂项目中也常写全限定名以减少歧义。
第一个参数是 String,后面可以有其他参数
execution(* com.example.demo.OrderService.*(String, ..))
匹配当前包及子包中各类的方法
execution(* com.example.demo..*.*(..))
这里 .. 表示包路径中的任意层级,后面的 *.* 分别对应类名和方法名。不要误写成缺少类名、方法名段落的表达式。
匹配名称以 Service 结尾的类
execution(* com.example.demo..*Service.*(..))
8.3 通配符速查
| * | 匹配任意返回类型、名称或名称的一部分 | *Service、find* |
| .. | 匹配任意包层级;在参数中表示任意参数列表 | demo..*Service、(..) |
| + | 放在类型模式后,匹配该类型及其子类型 | OrderService+ |
通配符的含义取决于出现的位置。(..) 不是“一个任意参数”,而是“任意参数列表”;( *) 则通常用于表示一个任意类型参数,实际书写为:
execution(* com.example.demo.OrderService.*(*))
8.4 编写表达式的实用方法
范围越大,越需要关注误匹配。例如 execution(* com.example..*.*(..)) 可能把项目中的大量 Spring Bean 都纳入代理范围,导致日志膨胀、额外开销或通知之间互相影响。
九、其他常用切点指示符与组合
Spring AOP 支持一部分 AspectJ 切点指示符,并额外提供 bean。
| execution | 方法执行签名 | execution(* demo.OrderService.*(..)) |
| within | 指定类型或包中的方法执行 | within(com.example.demo..*) |
| target | 目标对象的运行时类型 | target(com.example.demo.OrderService) |
| this | 当前代理对象的类型 | this(com.example.demo.OrderApi) |
| args | 实参的运行时类型 | args(String,..) |
| @annotation | 被增强方法上的注解 | @annotation(OperationLog) |
| @within | 声明目标方法所在类型上的注解 | @within(Audited) |
| @target | 目标对象运行时类型上的注解 | @target(Audited) |
| @args | 实际参数运行时类型上的注解 | @args(Validated) |
| bean | Spring Bean 名称 | bean(orderService) |
9.1 within
within(com.example.demo.service..*)
匹配指定包及子包类型中的方法执行。与 execution 相比,within 更强调“类型内部”,通常更简洁。
9.2 bean
bean(orderService)
匹配名称为 orderService 的 Spring Bean。OrderService 默认 Bean 名通常是首字母小写的 orderService。
也可以使用名称模式:
bean(*Service)
bean 是 Spring AOP 特有的指示符,不应把它当成完整 AspectJ 语言的通用语法。
9.3 this 与 target
两者最容易混淆:
- this 检查代理对象类型;
- target 检查目标对象类型。
使用 JDK 动态代理时,代理实现业务接口,但并不是目标实现类的子类;使用 CGLIB 时,代理是目标类的子类。因此,更换代理策略可能改变某些 this 表达式的匹配结果。
9.4 组合切点
使用 &&、|| 和 ! 组合:
@Pointcut("execution(* com.example.demo..*Service.*(..))")
public void serviceMethods() {
}
@Pointcut("!bean(internalOrderService)")
public void notInternalService() {
}
@Before("serviceMethods() && notInternalService()")
public void beforeExternalService() {
}
也可以直接组合表达式:
execution(* com.example.demo..*Service.*(..)) && @annotation(com.example.demo.OperationLog)
这表示同时满足“Service 方法”和“带指定注解”两个条件。
完整 AspectJ 中的 call、get、set、handler、initialization、cflow 等并不都属于 Spring AOP 支持范围。把不支持的指示符用于 Spring AOP,可能得到 IllegalArgumentException 等解析错误。
十、自定义注解:只增强标记的方法
包级或类级切点适合统一规则,自定义注解则适合精细控制:只有明确标记的方法才记录操作日志。
10.1 定义注解
package com.example.demo;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface OperationLog {
String value();
}
两个元注解分别回答:
- @Target(ElementType.METHOD):这个注解可以写在哪里?这里只允许用于方法;
- @Retention(RetentionPolicy.RUNTIME):这个注解保留到什么时候?这里保留到运行时,允许反射读取。
三种保留策略的区别:
| SOURCE | 仅源码,编译时丢弃 | 否 |
| CLASS | 保留在 class 文件中,是默认策略 | 通常不能,VM 不必保留 |
| RUNTIME | 保留到运行时 | 是 |
AOP 需要在运行时识别方法注解,因此这里必须使用 RUNTIME。
10.2 标记业务方法
@Service
public class OrderService {
@OperationLog("创建订单")
public String createOrder(String item) {
return "ORDER-" + item;
}
public String fail() {
throw new IllegalStateException("库存不足");
}
public String createTwice(String item) {
return createOrder(item);
}
}
createTwice 暂时用于后面的自调用实验。
10.3 在切面中绑定注解
package com.example.demo;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;
@Aspect
@Component
public class OperationLogAspect {
private static final Logger log = LoggerFactory.getLogger(OperationLogAspect.class);
@Around("@annotation(operationLog)")
public Object logOperation(
ProceedingJoinPoint pjp,
OperationLog operationLog) throws Throwable {
log.info("开始操作:{}", operationLog.value());
Object result = pjp.proceed();
log.info("操作成功:{}", operationLog.value());
return result;
}
}
@annotation(operationLog) 不仅负责匹配,还把方法上的注解实例绑定到同名参数 operationLog。这样可以直接读取 value(),不需要手动遍历方法注解。
上面的“操作成功”放在 proceed() 之后,所以目标抛出异常时不会记录成功。若还需要失败审计,应增加明确的异常处理或单独通知,而不是把“成功”写进 finally。
十一、多个切面怎样排序
当一个方法同时被耗时切面和操作日志切面增强时,可以使用 @Order 指定优先级。数值越小,优先级越高。
@Aspect
@Component
@Order(1)
public class TimeAspect {
// …
}
@Aspect
@Component
@Order(2)
public class OperationLogAspect {
// …
}
对于环绕通知,高优先级切面位于更外层:
调用方
↓
TimeAspect @Order(1):进入
↓
OperationLogAspect @Order(2):进入
↓
目标方法
↓
OperationLogAspect @Order(2):离开
↓
TimeAspect @Order(1):离开
↓
调用方
即:进入时高优先级先执行,离开时高优先级后执行,形成嵌套结构。
需要注意:
- 不要把类名的字母顺序当作稳定业务契约;
- 需要顺序时显式写 @Order;
- 同一切面内多个通知的相对顺序不应凭感觉假设;
- 如果几段逻辑必须严格按一个顺序执行,可以合并为一个通知,或拆成边界清晰、明确排序的切面。
@Order 只解决通知链的编排问题,不会自动解决事务一致性、线程安全或重试幂等性。
十二、正常返回与异常退出分别发生什么
理解通知时机,比背注解名称更重要。
| @Before | 执行 | 若调用链已到达则执行 |
| 目标方法 | 执行完成 | 执行中抛出异常 |
| @AfterReturning | 执行 | 不执行 |
| @AfterThrowing | 不执行 | 异常类型匹配时执行 |
| @After | 执行 | 执行 |
| @Around 中 proceed() 后的普通代码 | 执行 | 默认不执行 |
| @Around 的 finally | 执行 | 执行 |
12.1 成功路径
正常返回时,内层调用链先完成,再逐层向外返回。@AfterReturning 只在正常返回后执行,@After 在正常和异常路径都会执行;环绕通知中 proceed() 后的普通代码,则只有在内层调用链正常返回后才执行。
通知类型本身不能决定跨切面的全局顺序。以环绕通知位于更外层为例:
外层 Around:proceed() 前的逻辑
↓
内层 Before
↓
目标方法正常返回
↓
内层 AfterReturning 与 After
↓
外层 Around:proceed() 返回后的逻辑与 finally
↓
调用方收到返回值
这里只明确内外层关系,不把同一内层中 AfterReturning 与 After 的相邻顺序作为业务依赖。若环绕通知位于其他切面内层,它的后置代码也会随内层调用链先完成。需要跨切面顺序时,应通过 @Order 明确编排。
12.2 异常路径
目标抛出异常后,@AfterReturning 不执行;异常类型匹配时执行 @AfterThrowing,@After 仍执行。若环绕通知没有捕获异常,proceed() 后的普通代码不会执行,但 finally 会随异常向外传播而执行。
仍以环绕通知位于更外层、且不捕获异常为例:
外层 Around:proceed() 前的逻辑
↓
内层 Before
↓
目标方法抛出异常
↓
内层 AfterThrowing(类型匹配时)与 After
↓
外层 Around:finally
↓
调用方收到异常
因此,在第 17 章的顺序配置中,OrderLifecycleAspect 位于 TimeAspect 内层,fail() 抛出异常后,内层异常与最终通知先执行,随后才执行外层 TimeAspect 的 finally。
12.3 环绕通知不要吞异常
下面的代码会把失败伪装成成功:
@Around("execution(* com.example.demo.OrderService.*(..))")
public Object wrong(ProceedingJoinPoint pjp) {
try {
return pjp.proceed();
} catch (Throwable ex) {
log.error("调用失败", ex);
return null;
}
}
调用方原本应该收到 IllegalStateException,现在却得到 null,上层事务和错误处理都可能因此做出错误判断。
只是记录日志时,优先选择:
@Around("execution(* com.example.demo.OrderService.*(..))")
public Object right(ProceedingJoinPoint pjp) throws Throwable {
try {
return pjp.proceed();
} catch (Throwable ex) {
log.error("调用失败", ex);
throw ex;
}
}
如果只需要成功、失败分别记录,使用 @AfterReturning 和 @AfterThrowing 往往更简洁。
十三、代理模式:理解 Spring AOP 的前置知识
13.1 静态代理
静态代理由开发者手写代理类。代理与目标实现相同接口,在调用目标前后添加通用逻辑:
public interface UserService {
void save();
}
public class UserServiceImpl implements UserService {
@Override
public void save() {
System.out.println("保存用户");
}
}
public class UserServiceProxy implements UserService {
private final UserService target;
public UserServiceProxy(UserService target) {
this.target = target;
}
@Override
public void save() {
System.out.println("保存前记录日志");
target.save();
System.out.println("保存后记录日志");
}
}
使用:
UserService target = new UserServiceImpl();
UserService service = new UserServiceProxy(target);
service.save();
问题是每增加一个接口或需要不同增强,就可能增加大量代理类。动态代理把这类重复结构交给运行时机制处理。
13.2 JDK 动态代理
JDK 标准库提供 java.lang.reflect.Proxy,可以在运行时为接口创建代理实例,并通过 InvocationHandler 统一处理方法调用。
import java.lang.reflect.Proxy;
public class JdkProxyDemo {
public static void main(String[] args) {
UserService target = new UserServiceImpl();
UserService proxy = (UserService) Proxy.newProxyInstance(
target.getClass().getClassLoader(),
target.getClass().getInterfaces(),
(proxyObject, method, methodArgs) -> {
System.out.println("调用前:" + method.getName());
Object result = method.invoke(target, methodArgs);
System.out.println("调用后:" + method.getName());
return result;
});
proxy.save();
}
}
这里至少有三个角色:
- target:真正执行业务逻辑的对象;
- proxy:JDK 在运行时创建的接口代理;
- Lambda 形式的 InvocationHandler:集中编写调用前后逻辑。
Spring AOP 的调用链、通知排序和上下文管理比这个示例复杂得多,但“外部调用先进入代理,再转到目标”的基本思想一致。
十四、Spring 的 JDK 代理与 CGLIB 代理
Spring AOP 默认使用 JDK 动态代理或 CGLIB 代理。
14.1 Spring Framework 的基本选择
在 Spring Framework 的核心机制中:
- 目标对象实现了接口时,可以使用 JDK 动态代理;
- 目标对象没有接口时,使用 CGLIB 创建目标类的子类代理;
- 也可以强制使用类代理。
CGLIB 已重新打包并包含在 spring-core 中。使用当前 Spring 依赖体系时,不需要为了 Spring AOP 再手动添加旧的独立 cglib:cglib 依赖。
14.2 Spring Boot 默认使用 CGLIB
Spring Boot 3.5 的 AOP 自动配置默认使用 CGLIB 代理,即 spring.aop.proxy-target-class=true。因此,即使类实现了接口,默认也倾向于使用类代理。
可以在测试中确认:
import static org.assertj.core.api.Assertions.assertThat;
import org.junit.jupiter.api.Test;
import org.springframework.aop.support.AopUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
@SpringBootTest
class ProxyTests {
@Autowired
private OrderService orderService;
@Test
void usesCglibByDefault() {
assertThat(AopUtils.isCglibProxy(orderService)).isTrue();
assertThat(AopUtils.isJdkDynamicProxy(orderService)).isFalse();
}
}
若希望改为在具备接口时使用 JDK 动态代理:
spring:
aop:
proxy-target-class: false
没有接口的类仍然需要 CGLIB。这个配置不是“关闭 AOP”,也不是“切换到完整 AspectJ”。
14.3 AspectJ 自动代理配置
AspectJ 位于类路径上时,Spring Boot 会自动启用 @AspectJ 自动代理支持,因此通常不需要再手写 @EnableAspectJAutoProxy。
在没使用对应自动配置的纯 Spring 环境中,才需要根据配置方式显式启用 @AspectJ 支持。
十五、为什么有些方法不会被增强
15.1 自调用失效
这是代理型 AOP 最常见的问题之一:
@Service
public class OrderService {
@OperationLog("创建订单")
public String createOrder(String item) {
return "ORDER-" + item;
}
public String createTwice(String item) {
return createOrder(item);
}
}
外部直接调用:
orderService.createOrder("BOOK");
调用经过代理,@OperationLog 对应的通知会执行。
外部调用:
orderService.createTwice("BOOK");
只有 createTwice 的这次外部调用经过代理。进入目标对象后,createOrder(item) 等价于 this.createOrder(item),这里的 this 是目标对象,不是代理,因此 createOrder 上的注解通知会被绕过。
外部调用 createOrder
代理 → 通知 → 目标 createOrder 通知生效
外部调用 createTwice
代理 → 目标 createTwice
└─ this.createOrder 不重新经过代理,通知失效
同样的问题也可能影响基于代理实现的 @Transactional 等能力。不能认为“方法上写了注解,无论怎样调用都一定生效”。
推荐处理顺序:
15.2 final 类与 final 方法
CGLIB 通过继承目标类生成代理,因此:
- final 类不能被继承,无法按这种机制生成子类代理;
- final 方法不能被覆盖,调用时不会被 CGLIB 代理拦截。
不要为了“让 AOP 生效”而机械删除所有 final。先判断这个类是否真的需要代理,再选择合理设计。
15.3 private 方法
private 方法不是通过子类覆盖来增强的,外部调用也无法直接到达它。因此下面这种期待通常不成立:
@OperationLog("内部计算")
private void calculate() {
}
常规业务增强点应优先设计为 public 方法。protected、包可见方法在不同代理和具体场景中有额外限制,不应仅凭一次实验就把它们当作稳定通用方案。
15.4 对象不是 Spring Bean
OrderService service = new OrderService();
service.createOrder("BOOK");
手动 new 出来的对象没有经过 Spring 容器创建和代理,Spring AOP 不会自动增强它。应从容器获取 Bean,例如构造器注入或测试中的 @Autowired。
15.5 切点没有匹配
重点检查:
- 包名、类名、方法名是否写错;
- 参数模式是否过窄;
- @annotation 的全限定类名是否正确;
- 自定义注解是否为 RUNTIME;
- 注解是否写在实现方法上,还是只写在另一个声明位置;
- 表达式是否被 ! 或 && 条件意外排除。
十六、Spring AOP 与 AspectJ 的关系
两者有关联,但不是同一个概念。
| 常用注解 | @Aspect、@Before、@Around 等 | 同样可使用 AspectJ 注解或 AspectJ 语言 |
| 运行基础 | Spring 代理与 IoC 容器 | AspectJ 编译器或织入器 |
| 主要连接点 | Spring Bean 的方法执行 | 更丰富的 AspectJ 连接点 |
| 织入时机 | 运行时创建代理 | 编译期、编译后或加载期 |
| 自调用 | 可能绕过代理 | 不依赖同类代理路径 |
| 常见使用难度 | 与 Spring Boot 集成简单 | 构建与运行配置更复杂 |
使用下面这种代码:
@Aspect
@Component
public class TimeAspect {
}
不等于已经使用 AspectJ 编译器修改了 class 文件。Spring 复用了 AspectJ 的编程风格和表达式解析能力,实际运行时仍然可以是纯 Spring AOP 代理。
如果需求只是增强 Spring Service 的 public 方法,Spring AOP 通常已经足够。若必须拦截字段访问、构造器调用、非 Spring 对象或自调用,才需要评估完整 AspectJ 或其他字节码方案。
十七、完整整合示例
下面把五类通知、命名切点、环绕通知、自定义注解和切面顺序放在一起。代码保持“通用逻辑在切面、业务逻辑在 Service”的边界。
17.1 OrderService
package com.example.demo;
import org.springframework.stereotype.Service;
@Service
public class OrderService {
@OperationLog("创建订单")
public String createOrder(String item) {
return "ORDER-" + item;
}
public String fail() {
throw new IllegalStateException("库存不足");
}
public String createTwice(String item) {
return createOrder(item);
}
}
17.2 TimeAspect
@Order(1) 让耗时统计位于更外层。finally 确保异常路径也记录耗时。
package com.example.demo;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;
@Aspect
@Component
@Order(1)
public class TimeAspect {
private static final Logger log = LoggerFactory.getLogger(TimeAspect.class);
@Around("execution(* com.example.demo.OrderService.*(..))")
public Object recordTime(ProceedingJoinPoint pjp) throws Throwable {
long start = System.nanoTime();
try {
return pjp.proceed();
} finally {
long elapsedMillis = (System.nanoTime() – start) / 1_000_000;
log.info("{} 执行耗时 {} ms", pjp.getSignature(), elapsedMillis);
}
}
}
17.3 OperationLogAspect
package com.example.demo;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;
@Aspect
@Component
@Order(2)
public class OperationLogAspect {
private static final Logger log = LoggerFactory.getLogger(OperationLogAspect.class);
@Around("@annotation(operationLog)")
public Object logOperation(
ProceedingJoinPoint pjp,
OperationLog operationLog) throws Throwable {
log.info("开始操作:{}", operationLog.value());
Object result = pjp.proceed();
log.info("操作成功:{}", operationLog.value());
return result;
}
}
17.4 OrderLifecycleAspect
package com.example.demo;
import org.aspectj.lang.JoinPoint;
import org.aspectj.lang.annotation.After;
import org.aspectj.lang.annotation.AfterReturning;
import org.aspectj.lang.annotation.AfterThrowing;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Before;
import org.aspectj.lang.annotation.Pointcut;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;
@Aspect
@Component
@Order(3)
public class OrderLifecycleAspect {
private static final Logger log = LoggerFactory.getLogger(OrderLifecycleAspect.class);
@Pointcut("execution(* com.example.demo.OrderService.*(..))")
public void orderOperations() {
}
@Before("orderOperations()")
public void before(JoinPoint joinPoint) {
log.info("准备调用 {}", joinPoint.getSignature());
}
@AfterReturning(pointcut = "orderOperations()", returning = "result")
public void afterReturning(Object result) {
log.info("正常返回:{}", result);
}
@AfterThrowing(pointcut = "orderOperations()", throwing = "exception")
public void afterThrowing(IllegalStateException exception) {
log.warn("业务异常:{}", exception.getMessage());
}
@After("orderOperations()")
public void after(JoinPoint joinPoint) {
log.info("调用结束:{}", joinPoint.getSignature());
}
}
17.5 预期行为
| createOrder("BOOK") | 返回 ORDER-BOOK,记录操作开始、操作成功、五类通知中的成功路径及耗时 |
| fail() | 抛出 IllegalStateException,执行异常通知和最终通知,记录耗时,不记录操作成功 |
| createTwice("BOOK") | 返回 ORDER-BOOK,但内部 createOrder 不再次经过代理,操作注解通知被绕过 |
createOrder 上同时有 TimeAspect、OperationLogAspect 和 OrderLifecycleAspect,顺序为 1、2、3。fail 没有 @OperationLog,所以不匹配注解切面。
十八、怎样测试 AOP,而不只是看日志
日志便于观察,但自动化测试应该验证可观察行为。
18.1 测试返回值与异常传播
@Test
void successKeepsReturnValue() {
assertThat(orderService.createOrder("BOOK"))
.isEqualTo("ORDER-BOOK");
}
@Test
void failureKeepsException() {
assertThatThrownBy(orderService::fail)
.isInstanceOf(IllegalStateException.class)
.hasMessage("库存不足");
}
这两个测试能发现环绕通知忘记 return、错误返回 null、吞异常等问题。
18.2 用测试切面记录通知是否执行
在测试源码中增加一个计数切面:
package com.example.demo;
import java.util.concurrent.atomic.AtomicInteger;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Before;
import org.springframework.stereotype.Component;
@Aspect
@Component
public class AnnotationCounterAspect {
private final AtomicInteger invocations = new AtomicInteger();
@Before("@annotation(com.example.demo.OperationLog)")
public void count() {
invocations.incrementAndGet();
}
public void reset() {
invocations.set(0);
}
public int invocations() {
return invocations.get();
}
}
通过 @Import 显式加入测试上下文:
@SpringBootTest
@Import(AnnotationCounterAspect.class)
class SelfInvocationTests {
@Autowired
private OrderService orderService;
@Autowired
private AnnotationCounterAspect counter;
@BeforeEach
void reset() {
counter.reset();
}
@Test
void selfInvocationBypassesAdvice() {
orderService.createTwice("BOOK");
assertThat(counter.invocations()).isZero();
orderService.createOrder("BOOK");
assertThat(counter.invocations()).isEqualTo(1);
}
}
这里不是只检查日志字符串,而是直接验证通知执行次数。
18.3 测试多个切面的嵌套顺序
可以让两个测试切面分别记录 before 和 after,目标方法记录 target。@Order(10) 与 @Order(20) 的预期事件为:
first-before
second-before
target
second-after
first-after
若顺序会影响审计、事务或资源释放,应把这类测试保留下来,避免后续重构无意间改变调用链。
十九、实战中的设计原则
19.1 一个切面聚焦一种职责
“操作日志”和“耗时统计”可以分开;“日志、权限、重试、缓存全部写进一个几千行切面”会让顺序和异常处理难以分析。
19.2 优先使用能力最弱的通知
| 调用前检查 | @Before |
| 成功后处理 | @AfterReturning |
| 失败后记录 | @AfterThrowing |
| 两种结果都清理 | @After |
| 必须包围并控制调用 | @Around |
这样既能减少代码,也能降低忘记 proceed()、丢失返回值或吞异常的风险。[cite:4]
19.3 不要把 AOP 日志变成敏感数据出口
避免直接输出整个参数对象:
log.info("请求参数:{}", Arrays.toString(joinPoint.getArgs()));
参数中可能包含密码、令牌、身份证号、银行卡号或用户隐私。生产环境应选择白名单字段,并进行脱敏。
19.4 不要在通用切面里随意重试
重复调用 proceed() 会重复执行业务。对非幂等写操作进行自动重试,可能产生重复订单、重复扣款或重复消息。重试需要明确超时、次数、退避、幂等键和异常分类,不能只靠一个循环。
19.5 注意通知自身的异常
通知也是调用链的一部分。日志、审计等辅助逻辑如果抛出异常,可能阻断业务或改变原始结果。应根据业务重要性明确策略:
- 核心安全校验失败时,应阻止调用;
- 非核心监控失败时,是否允许影响主流程,需要明确设计;
- 清理逻辑异常时,注意不能遮蔽原始业务异常。
19.6 AOP 不等于所有横切问题的唯一答案
| HTTP 请求进入 Controller 前的统一处理 | Servlet Filter、Spring MVC Interceptor |
| 数据库事务边界 | Spring @Transactional |
| Bean 字段校验 | Bean Validation |
| 某个业务领域规则 | 领域对象或领域服务 |
| Spring Bean 方法的通用增强 | Spring AOP |
Filter、Interceptor 和 AOP 的调用层级不同。不要因为都能“在前后执行代码”就随意替换。
二十、常见问题排查表
| 切面完全不生效 | 是否只有 @Aspect,没有注册为 Bean | 增加 @Component 或显式注册,并确认在扫描范围内 |
| 启动提示找不到 AspectJ 相关类 | 是否缺少 AOP Starter | 添加 spring-boot-starter-aop |
| 环绕通知后调用方得到 null | 是否忘记返回 proceed() 结果 | 使用 return pjp.proceed() 或保存后返回结果 |
| 目标方法没有执行 | 是否忘记调用 proceed() | 在需要执行目标的路径上调用一次 |
| 异常被吞掉 | 是否 catch 后返回 null | 重新抛出,或改用异常后通知 |
| 异常时没记录耗时 | 耗时日志是否只在 proceed() 之后 | 放入 finally |
| 正常时执行了异常通知 | 切点或绑定类型是否理解有误 | 检查目标是否真的异常退出、通知链是否抛出异常 |
| @AfterReturning 不执行 | 目标是否抛异常 | 异常路径使用 @AfterThrowing 和 @After |
| returning 启动报错 | 注解属性名与参数名是否一致 | 保持 returning = "result" 与参数 result 一致 |
| throwing 不执行 | 异常是否与参数类型兼容 | 改为实际异常父类型或 Throwable |
| 自定义注解读不到 | 保留策略是否正确 | 使用 @Retention(RetentionPolicy.RUNTIME) |
| 自调用没有通知 | 是否通过 this 调用目标方法 | 优先重构调用结构,避免依赖目标内部自调用 |
| 手动 new 的对象不生效 | 对象是否由 Spring 管理 | 从容器注入 Bean |
| final 方法不生效 | 是否使用 CGLIB 类代理 | 理解继承代理限制,调整增强点设计 |
| private 方法不生效 | 是否把代理机制当成字节码织入 | 改为合适的 public Bean 方法或评估完整 AspectJ |
| 顺序偶尔不符合预期 | 是否依赖类名或同切面通知顺序 | 拆分职责并使用明确 @Order,必要时合并通知 |
| execution 启动解析失败 | 包、类、方法、参数段落是否完整 | 从精确表达式开始,逐步扩大范围 |
| 使用 call 等表达式报错 | 是否误用了 Spring AOP 不支持的指示符 | 改用 execution 等受支持语法[cite:5] |
| 加了旧 CGLIB 依赖仍有冲突 | 是否重复引入第三方版本 | 使用 Spring 依赖管理,不手动添加旧 cglib:cglib |
| 不知道实际代理类型 | 是否只是凭接口有无猜测 | 使用 AopUtils 检查,并确认 Boot 配置[cite:7] |
二十一、上线前检查清单
切点与通知
- 切点从精确范围开始验证,没有无意中匹配大量 Bean。
- 正常返回与异常退出两条路径都已测试。
- 使用满足需求的最弱通知类型。
- 环绕通知在需要执行目标的路径上调用了 proceed()。
- 环绕通知保留目标返回值,没有无故返回 null。
- 异常没有被日志代码吞掉。
- 成功日志不会被写入无条件执行的 finally。
参数与注解
- returning、throwing 与通知方法参数名一致。
- 自定义注解使用 RUNTIME 保留策略。
- @annotation 绑定参数名与表达式一致。
- 日志没有输出密码、令牌和隐私参数。
- 异常日志保留堆栈,而不只保留一句消息。
代理与顺序
- 已确认目标是 Spring Bean,不是手动 new 的对象。
- 已检查自调用,没有假设内部调用会再次经过代理。
- 已理解 final、private 方法的代理限制。
- 多个切面有明确 @Order,没有依赖类名字母顺序。
- 顺序相关行为有自动化测试。
- 没有为了 Spring AOP 重复添加旧 CGLIB 依赖。
业务安全
- 通知中的辅助逻辑不会意外破坏主业务结果。
- 没有把重复 proceed() 当作无条件重试。
- 涉及写操作时评估了幂等性和事务边界。
- Spring AOP 与完整 AspectJ 的使用模式没有混淆。
二十二、总结
Spring AOP 的学习可以归纳为四条主线:
最重要的实践原则是:先用简单通知解决简单问题,再使用环绕通知处理真正需要包围调用的场景;先明确业务语义,再决定切点范围与通知顺序。这样写出来的切面才既可用,也便于长期维护。
参考资料
网硕互联帮助中心


![[特殊字符]华为云码道实战:基于 Spring Boot 从零构建校园 AI 工具箱-网硕互联帮助中心](https://www.wsisp.com/helps/wp-content/uploads/2026/11/20261118135630-6afdae8e378f5-220x150.png)


评论前必须登录!
注册