Spring on 牛哥聊技术

Spring 参数校验完整指南：JSR-380 与 Hibernate Validator

Sat, 17 Aug 2019 16:30:00 +0800

校验该写在哪一层？

很多项目里随处可见这样的代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


public Result createUser(UserDTO dto) {
 if (dto.getName() == null || dto.getName().isEmpty()) {
 return Result.fail("姓名不能为空");
 }
 if (dto.getAge() == null || dto.getAge() < 0 || dto.getAge() > 200) {
 return Result.fail("年龄不合法");
 }
 if (!Pattern.matches("^1[3-9]\\d{9}$", dto.getPhone())) {
 return Result.fail("手机号格式错误");
 }
 // ... 真正的业务逻辑
}

每个 Controller 都重复一遍，手工拼错误消息，堆得密不透风。这种代码不该出现在业务方法里——校验是输入边界的责任，应该在数据进入业务方法前就被自动拦截。

Bean Validation（JSR-380）和它的事实标准实现 Hibernate Validator 就是为这件事而生。今天我们把它的常见用法和"骚姿势"过一遍。

基础：常用注解一览

注解	作用	适用类型
`@NotNull`	不能为 null	任意
`@NotEmpty`	不能 null 且不能为空	String / Collection / Array
`@NotBlank`	不能 null 且 trim 后非空	String
`@Size(min,max)`	长度/大小范围	String / Collection
`@Min` / `@Max`	数值最小/最大	数字
`@DecimalMin/Max`	支持 BigDecimal 的最小最大	数字
`@Positive` / `@Negative`	正数 / 负数	数字
`@Pattern(regexp)`	正则匹配	String
`@Email`	邮箱格式	String
`@Past` / `@Future`	过去 / 未来时间	时间类型
`@AssertTrue`	必须为 true	boolean
`@Valid`	触发嵌套校验	对象 / 集合

一份典型的 DTO：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


public class UserCreateDTO {

 @NotBlank(message = "姓名不能为空")
 @Size(max = 20, message = "姓名最长 20 个字")
 private String name;

 @NotNull(message = "年龄必填")
 @Min(value = 0, message = "年龄不能为负")
 @Max(value = 200, message = "年龄太离谱了")
 private Integer age;

 @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不对")
 private String phone;

 @Email(message = "邮箱格式不对")
 private String email;

 @Valid // 嵌套校验
 private AddressDTO address;
}

接入 Spring：一个 `@Valid` 全自动

Spring MVC 集成是开箱即用的——参数前加 @Valid，校验失败会抛 MethodArgumentNotValidException：

1
2
3
4
5


@PostMapping("/users")
public Result createUser(@RequestBody @Valid UserCreateDTO dto) {
 // 进到这里，所有约束都已经通过
 return userService.create(dto);
}

Path Variable / Request Param 上需要 @Validated 在 Controller 类上配合：

1
2
3
4
5
6
7
8
9


@RestController
@Validated
public class UserController {

 @GetMapping("/users/{id}")
 public Result get(@PathVariable @Min(1) Long id) {
 return userService.get(id);
 }
}

Path/Param 校验失败会抛 ConstraintViolationException，异常类型和 @RequestBody 不一样，需要分别处理。

全局异常处理：让校验报错优雅返回

Controller 内部不该处理校验异常，应该用全局异常处理器统一处理：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


@RestControllerAdvice
public class GlobalExceptionHandler {

 // @RequestBody 校验失败
 @ExceptionHandler(MethodArgumentNotValidException.class)
 public Result handleBody(MethodArgumentNotValidException e) {
 String msg = e.getBindingResult().getFieldErrors().stream()
 .map(f -> f.getField() + ": " + f.getDefaultMessage())
 .collect(Collectors.joining("; "));
 return Result.fail(400, msg);
 }

 // @RequestParam / @PathVariable 校验失败
 @ExceptionHandler(ConstraintViolationException.class)
 public Result handleParam(ConstraintViolationException e) {
 String msg = e.getConstraintViolations().stream()
 .map(v -> v.getPropertyPath() + ": " + v.getMessage())
 .collect(Collectors.joining("; "));
 return Result.fail(400, msg);
 }
}

至此基础就齐了。下面才是真正出彩的"骚姿势"。

骚姿势一：分组校验（Validation Groups）

最常见的场景：新增和修改用的是同一个 DTO，但字段约束不同。新增时 id 不能传，修改时 id 必填——硬拆两个 DTO 又冗余。

分组校验解决这个问题：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


public interface CreateGroup {}
public interface UpdateGroup {}

public class UserDTO {

 @Null(message = "新增时不能传 ID", groups = CreateGroup.class)
 @NotNull(message = "修改时必须传 ID", groups = UpdateGroup.class)
 private Long id;

 @NotBlank(groups = {CreateGroup.class, UpdateGroup.class})
 private String name;
}

@PostMapping("/users")
public Result create(@RequestBody @Validated(CreateGroup.class) UserDTO dto) { ... }

@PutMapping("/users")
public Result update(@RequestBody @Validated(UpdateGroup.class) UserDTO dto) { ... }

注意——分组要用 @Validated 不能用 @Valid，因为 @Valid 不支持分组参数。

骚姿势二：嵌套校验

DTO 嵌 DTO 时，光在外层加 @Valid 是不够的，必须在内层字段上也加 @Valid，校验才会递归下去：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


public class OrderDTO {

 @NotEmpty
 @Valid // ← 关键
 private List<OrderItemDTO> items;
}

public class OrderItemDTO {
 @NotNull private Long skuId;
 @Min(1) private Integer count;
}

如果集合里有元素违规，错误路径会是 items[2].count，前端能精确定位。

骚姿势三：跨字段校验（自定义类级注解）

校验"密码和确认密码必须一致"这种字段间约束，单字段注解搞不定，需要写一个类级注解：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = PasswordMatchValidator.class)
public @interface PasswordMatch {
 String message() default "两次密码不一致";
 Class<?>[] groups() default {};
 Class<? extends Payload>[] payload() default {};
}

public class PasswordMatchValidator implements ConstraintValidator<PasswordMatch, RegisterDTO> {
 @Override
 public boolean isValid(RegisterDTO dto, ConstraintValidatorContext context) {
 if (dto.getPassword() == null) return true; // 让 @NotBlank 去管 null
 boolean match = dto.getPassword().equals(dto.getConfirmPassword());
 if (!match) {
 // 让错误"挂"在 confirmPassword 字段上而不是整个对象上
 context.disableDefaultConstraintViolation();
 context.buildConstraintViolationWithTemplate("两次密码不一致")
 .addPropertyNode("confirmPassword")
 .addConstraintViolation();
 }
 return match;
 }
}

@PasswordMatch
public class RegisterDTO {
 @NotBlank private String password;
 @NotBlank private String confirmPassword;
}

骚姿势四：自定义字段约束

校验"枚举值必须在指定集合内"是另一个常见需求。写一个 @Enum 自定义约束：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = EnumValidator.class)
public @interface EnumValue {
 String message() default "值不在允许范围内";
 Class<?>[] groups() default {};
 Class<? extends Payload>[] payload() default {};

 Class<? extends Enum<?>> enumClass();
 String method() default "name"; // 用 enum 的哪个方法取值
}

public class EnumValidator implements ConstraintValidator<EnumValue, Object> {
 private Set<Object> values;

 @Override
 public void initialize(EnumValue ann) {
 values = Arrays.stream(ann.enumClass().getEnumConstants())
 .map(e -> ReflectUtil.invoke(e, ann.method()))
 .collect(Collectors.toSet());
 }
 @Override
 public boolean isValid(Object value, ConstraintValidatorContext ctx) {
 return value == null || values.contains(value);
 }
}

用法：

1
2


@EnumValue(enumClass = OrderStatus.class, method = "getCode")
private String status;

写一次，全项目复用。

骚姿势五：Service 层方法参数校验

@Validated 不只能用在 Controller，也能用在 Service：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


@Service
@Validated
public class UserService {

 public User getById(@Min(1) Long id) {
 // ...
 }

 public void batchCreate(@NotEmpty @Valid List<UserDTO> users) {
 // ...
 }
}

被 @Validated 标注的类，方法参数上的约束会通过 AOP 自动校验，失败抛 ConstraintViolationException。这意味着——业务方法可以放心地把"非法输入"假设成不可能发生。

骚姿势六：错误消息国际化

把 message 写成 {key} 形式，Hibernate Validator 会自动从 messages.properties 读取：

1
2


@NotBlank(message = "{user.name.notBlank}")
private String name;

src/main/resources/messages.properties：

1

user.name.notBlank=姓名不能为空

src/main/resources/messages_en.properties：

1

user.name.notBlank=Name is required

Spring Boot 默认就开启了国际化支持，根据请求 Accept-Language 自动切换。

骚姿势七：编程式 API 与 failFast

少数场景注解搞不定——例如根据运行时参数切换分组、或希望"遇到第一个错误就停"。可以用编程式 Validator：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


// 1. 自定义 ValidatorFactory，开启 failFast
@Bean
public Validator validator() {
 return Validation.byProvider(HibernateValidator.class)
 .configure()
 .failFast(true) // 任一字段失败立即返回，不再校验后续
 .buildValidatorFactory()
 .getValidator();
}

// 2. 编程式调用，按运行时条件选 group
@Autowired private Validator validator;

public void create(UserDTO dto, boolean strict) {
 Set<ConstraintViolation<UserDTO>> errors = strict
 ? validator.validate(dto, StrictGroup.class)
 : validator.validate(dto);
 if (!errors.isEmpty()) throw new IllegalArgumentException(...);
}

failFast 适合批量导入这种"快报快停"的场景；编程式 API 适合规则需要根据上下文动态切换。注解和编程式 API 完全可以混用——80% 用注解、20% 用 API 兜底。

一些工程上的踩坑提醒

@NotEmpty ≠ @NotBlank——前者认空白字符串为有效，后者会 trim
@Valid 和 @Validated 不要混用——分组场景必须 @Validated，嵌套校验只能 @Valid
基本类型的 @NotNull 是没用的——int、long 这些永远有默认值；要校验"必填"就得用包装类型
groups 默认值是 Default.class——不指定 groups 的注解只在不传分组时生效；你给某个注解加了 groups = Update.class，新增校验时它就不参与了
错误消息别堆业务逻辑——消息只描述"为什么不合法"，不要写"请联系管理员"这种和校验无关的话
DTO 复用别贪心——三种以上场景共用一个 DTO 时，强烈建议拆开，分组校验维护成本会爆炸

小结

Hibernate Validator 的价值不只是"少写 if"，它把输入校验从业务逻辑中剥离，让业务方法可以放心地假设"参数都是合法的"。

把今天的内容压一句：

校验是边界的责任，不是业务方法的责任。让框架帮你拦在门口，业务里只关心业务。

至于使用层级：

能用注解就用注解——分组、嵌套、自定义约束都属于注解能力
跨字段或动态规则——写自定义类级注解或编程式 API
Service 层也别放过——加 @Validated 让内部接口也享受框架保护

把这些招数都用上，Controller 里再也不会有那一行行傻乎乎的 if (xxx == null)。

Spring 依赖注入：@Resource 与 @Autowired 的使用边界

Tue, 04 Dec 2018 15:30:00 +0800

老生常谈但很少人答得明白的一题

Spring 项目里随手就能写出这两种依赖注入：

1
2
3
4
5


@Autowired
private UserService userService;

@Resource
private OrderService orderService;

两个注解效果几乎一样。但面试官一问"两者区别"，多数人只能磕磕巴巴答出"前者按类型，后者按名字"——这只是冰山一角。

本文把这两个注解的差异、源头、行为细节、踩坑点系统讲清楚。

一、出处不同

	@Autowired	@Resource
出处	Spring 自家	JSR-250（Java EE 标准）
包路径	`org.springframework.beans.factory.annotation`	`javax.annotation` / `jakarta.annotation`
历史	Spring 2.5+	Java EE 5（2006）
跨框架	只有 Spring 认	Spring / CDI / 多框架认

@Resource 是 Java 标准注解，@Autowired 是 Spring 私货。这是两者最本质的差异——理论上，使用 @Resource 的代码可以无缝切到任何 JSR-250 兼容的容器；用 @Autowired 就只能跑在 Spring 上。

实际工程里这点意义不大——99% 的 Java Web 项目都跑在 Spring 上。

二、查找规则不同

这是最常被问的差异——但远不止"按类型 vs 按名字"。

@Autowired 的查找顺序

flowchart TD
 A[按类型查找] --> B{找到 1 个?}
 B -->|是| C[注入]
 B -->|否，找到 0 个| D{required=true?}
 B -->|否，找到多个| E[尝试按名称匹配]
 D -->|是| F[抛 NoSuchBeanDefinitionException]
 D -->|否| G[注入 null]
 E --> H{匹配成功?}
 H -->|是| C
 H -->|否| I[抛 NoUniqueBeanDefinitionException]

简化：先按类型，类型多个时退化到按名字。

@Resource 的查找顺序

flowchart TD
 Start[开始] --> Q1{显式指定 name?}
 Q1 -->|是| ByName[只按 name 查]
 Q1 -->|否| Q2{显式指定 type?}
 Q2 -->|是| ByType[只按 type 查]
 Q2 -->|否| ByField[默认: 字段名作为 name 查]
 ByField --> Q3{找到?}
 Q3 -->|否| Fallback[退化到按类型查]
 Q3 -->|是| Done[注入]
 ByName --> Done
 ByType --> Done
 Fallback --> Done

简化：先按名字（字段名），找不到再按类型。

行为差异举例

1
2
3
4
5
6
7


public interface MessageSender {}

@Component
public class SmsSender implements MessageSender {}

@Component
public class EmailSender implements MessageSender {}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


// @Autowired：类型 MessageSender 有两个 Bean，先按类型找不唯一
@Autowired
private MessageSender smsSender; // ✓ 退化到字段名匹配 SmsSender

@Autowired
private MessageSender provider; // ❌ 字段名没匹配，抛异常

// @Resource：默认按字段名找
@Resource
private MessageSender smsSender; // ✓ 直接按 smsSender 找到

@Resource
private MessageSender provider; // ❌ 字段名没匹配的 Bean

// @Resource 显式指定
@Resource(name = "smsSender")
private MessageSender provider; // ✓

三、required 选项

@Autowired 有 required 属性：

1
2


@Autowired(required = false)
private OptionalService optionalService; // 没有 Bean 时注入 null

@Resource 没有这个开关——Bean 找不到一定抛异常。

不过现代 Spring 推荐用 Optional 替代：

1
2


@Autowired
private Optional<OptionalService> service;

四、能否注入到构造器 / 方法

1
2
3
4
5
6
7
8


@Autowired
public OrderService(UserService userService) { ... } // ✓ 构造器

@Autowired
public void setUserService(UserService userService) { ... } // ✓ Setter

@Autowired
public void initSomething(UserService u, OrderService o) { ... } // ✓ 任意方法

@Resource 主要用于字段和 Setter，不能注入到构造器：

1
2


@Resource
public OrderService(UserService userService) { ... } // ❌ 不支持

这是个关键差别——构造器注入是 Spring 推荐的方式（不可变、便于测试），但 @Resource 不支持。所以"全用 @Resource 替代 @Autowired“在构造器场景下行不通。

五、集合注入

@Autowired 能优雅注入集合：

1
2
3
4
5


@Autowired
private List<MessageSender> senders; // 所有实现都被注入

@Autowired
private Map<String, MessageSender> senderMap; // key 是 Bean name

@Resource 在集合注入上行为不那么友好——没有"按类型找全部"的语义。

这是 @Autowired 在写"策略模式"时的杀手锏——业务代码：

1
2
3
4
5
6


@Autowired
private Map<String, PaymentChannel> channels;

public void pay(String type, ...) {
 channels.get(type).charge(...);
}

加一个新支付渠道只需要 @Component，业务代码无感。

六、构造器注入 vs 字段注入

无论用哪个注解，字段注入是反模式。Spring 官方文档现在也推荐构造器注入：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// ❌ 字段注入（反模式）
@Autowired
private UserService userService;

// ✓ 构造器注入
private final UserService userService;

public OrderService(UserService userService) {
 this.userService = userService;
}

如果用 Lombok 更简洁：

1
2
3
4
5
6


@RequiredArgsConstructor
@Service
public class OrderService {
 private final UserService userService;
 private final OrderRepository repo;
}

构造器注入的好处：

字段可以 final——不可变
无 Spring 也能 new 出来——纯 Java，方便单测
依赖关系暴露在签名上——一眼能看出这个类依赖什么
循环依赖会立刻报错——而不是"运行时 NPE”

这就是为什么"@Autowired vs @Resource“这场争论某种意义上已经过时了——两者都不该用在字段上。

七、@Qualifier 与 @Resource(name)

类型多个 Bean 时，两种注解各有指定方式：

1
2
3
4
5
6


@Autowired
@Qualifier("smsSender")
private MessageSender sender;

@Resource(name = "smsSender")
private MessageSender sender;

效果相同。@Qualifier 还可以自定义：

1
2
3
4
5
6
7


@Component
@Qualifier("primary-sms")
public class AlibabaSmsSender implements MessageSender {}

@Autowired
@Qualifier("primary-sms")
private MessageSender sender;

@Resource(name) 没有这种"分组标签"的扩展能力。

八、循环依赖处理

两者对循环依赖的处理一致——字段注入和setter 注入支持循环依赖（Spring 三级缓存）；构造器注入循环依赖直接报错。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// A 依赖 B
@Service
public class A {
 @Autowired private B b;
}

// B 依赖 A → Spring 三级缓存可以解
@Service
public class B {
 @Autowired private A a;
}

但生产代码里出现循环依赖通常意味着设计问题，不要因为 Spring 能 handle 就放任。

九、@Autowired vs @Inject

讲到 JSR 标准，绕不过 @Inject（JSR-330）：

注解	出处	required 默认
`@Autowired`	Spring	true
`@Resource`	JSR-250	true
`@Inject`	JSR-330	true

@Inject 是 Google Guice / CDI 的标准，Spring 也支持——实际工程里基本没人用，因为 Spring 自家 @Autowired 功能更全。

十、踩坑提醒

1. 接口多实现时

1
2


@Autowired
private Service service; // 多个实现时报错

要么字段名匹配某个 Bean，要么显式 @Qualifier，要么用 @Primary：

1
2
3


@Component
@Primary
public class DefaultService implements Service {}

2. final 字段不能用 @Autowired

1
2


@Autowired
private final UserService userService; // ❌

final 字段必须在构造器里初始化——直接用构造器注入。

3. static 字段不能注入

1
2


@Autowired
private static UserService userService; // ❌ 不会注入

要给 static 字段注入只能在 setter 里手动 set，但这通常是设计有问题。

4. 单例引用原型 Bean

1
2
3
4
5


@Component // 默认单例
public class A {
 @Autowired
 private B b; // B 是 prototype，但 A 单例 → 始终是同一个 B 实例
}

不是 Spring 的 bug——是单例的依赖只注入一次。要每次取新实例：

1
2
3
4
5
6


@Autowired
private ObjectProvider<B> bProvider;

public void use() {
 B b = bProvider.getObject(); // 每次都拿新实例
}

5. JDK 版本与 javax/jakarta

Spring 6 / Spring Boot 3 把 javax.annotation 改成了 jakarta.annotation——老项目升级时 @Resource 的 import 要批量替换。

十一、选型建议

flowchart TD
 Start([需要注入依赖?])
 Start --> Type{字段还是构造器?}
 Type -->|构造器| C[必须 @Autowired
或 @RequiredArgsConstructor]
 Type -->|字段，不可改| F{需要按名字精确匹配?}
 F -->|是| R[@Resource - 简洁]
 F -->|否| A[@Autowired - 类型 + Qualifier]

给一个直接的工程建议：

首选构造器注入（用 Lombok 的 @RequiredArgsConstructor），二选 @Autowired + @Qualifier，最后选 @Resource。@Resource 在新代码里其实没什么不可替代的优势。

小结

把全文压一句：

@Autowired 优先按类型，@Resource 优先按名字；前者 Spring 私货功能更全，后者 JSR 标准。但两者最佳实践都是『不要用在字段上』——构造器注入才是 Spring 官方推荐的姿势。

记住几点：

字段注入是反模式，无论用哪个注解
构造器注入只能用 @Autowired（Spring 4.3 后构造器只有一个时连注解都不需要）
集合注入用 @Autowired 才够灵活
@Resource 在按 Bean name 精确匹配时稍简洁，但不是不可替代

下次写 Service 字段时——先想想"是否能改成构造器”，再选注解。

Spring 业务解耦：AOP 与事件监听的实战与边界

Wed, 09 May 2018 16:00:00 +0800

写在前面

业务代码里最容易长出"屎山"的两类逻辑——横切关注点（cross-cutting concerns）和副作用副流程：

日志、权限、审计、缓存、限流、监控埋点 → 横切关注点
用户注册后送积分、下单后通知库存、修改后清缓存 → 副流程

一旦把这些事写进业务方法，主线逻辑就被淹没：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


public Order createOrder(OrderDTO dto) {
 log.info("user {} start create order", userId);
 if (!hasPermission(userId, "ORDER_CREATE")) throw new ...;

 long start = System.currentTimeMillis();
 try {
 // 真正的业务
 Order order = orderRepo.save(new Order(dto));

 // 副流程一坨
 sendNotification(...);
 addUserPoints(userId, order.getAmount());
 cleanCache(userId);
 sendMQ(...);
 // ...

 return order;
 } finally {
 metrics.record("createOrder", System.currentTimeMillis() - start);
 log.info("create order done, id={}", order.getId());
 }
}

业务和"基础设施 + 副流程"完全混在一起。

Spring 提供了两种让业务代码保持纯粹的武器——AOP 和 事件监听。本文把它们的适用场景、边界、最佳实践讲清楚。

一、AOP：解决"横切关注点"

AOP 在解决什么

AOP 把"和业务逻辑交叉但本身不属于业务"的代码抽出来，让业务方法只剩"业务"：

1
2
3
4
5


@LogTime
@RequirePermission("ORDER_CREATE")
public Order createOrder(OrderDTO dto) {
 return orderRepo.save(new Order(dto));
}

业务代码变得极简，所有横切逻辑由 AOP 统一处理。

一个完整例子：方法耗时日志

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


@Aspect
@Component
public class TimingAspect {

 @Around("@annotation(LogTime)")
 public Object around(ProceedingJoinPoint pjp) throws Throwable {
 long start = System.currentTimeMillis();
 try {
 return pjp.proceed();
 } finally {
 long cost = System.currentTimeMillis() - start;
 log.info("{} cost {}ms", pjp.getSignature().toShortString(), cost);
 }
 }
}

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface LogTime {}

业务方法加 @LogTime 即可。

AOP 的典型适用场景

场景	注解风格
方法耗时日志	`@LogTime`
接口幂等	`@Idempotent`
限流	`@RateLimit(qps = 100)`
缓存	`@Cached(ttl = 5m)`
数据权限	`@DataScope`
重试	`@Retry(times = 3)`
分布式锁	`@DistributedLock(key)`
操作日志	`@OperationLog("创建订单")`

共同特征：和业务无关、跨多个方法、可以"声明式开关"。

AOP 的限制和坑

1. Spring AOP 是基于代理的——同类调用不生效

1
2
3
4
5
6


@Service
public class OrderService {
 public void a() { b(); } // ❌ 调 b 不会触发 b 的切面
 @LogTime
 public void b() { ... }
}

代理只在外部调用入口生效，类内部 this.method() 调用绕过了代理。解决：

1
2


@Autowired private ApplicationContext ctx;
public void a() { ctx.getBean(OrderService.class).b(); }

或者把 b 拆到另一个 Service。

2. private 方法不能被切

代理基于继承/接口，private 方法直接绕过。

3. AOP 调试链路长

stack trace 里多了 CglibProxy、JdkDynamicAopProxy 这些层，新人看不懂。

4. 滥用会让代码难追

业务方法签名上看到一堆 @LogTime @Cached @Idempotent @RateLimit @OperationLog @DistributedLock——不熟悉项目的人根本不知道每个注解干啥，行为变成"看不见的魔法"。

经验上：业务方法上的 AOP 注解多于 3 个就值得复盘，多于 5 个往往是过度设计的信号。

二、事件监听：解决"副流程解耦"

Spring 事件机制

业务做完主线后，需要触发一系列副流程——传统写法是直接调用：

1
2
3
4
5
6
7


public Order createOrder(...) {
 Order o = orderRepo.save(...);
 notificationService.send(...); // 副流程 1
 pointService.addPoints(...); // 副流程 2
 cacheService.evict(...); // 副流程 3
 return o;
}

每加一个副流程都要改这个方法，代码越来越臃肿。事件机制的解法——业务方法只发一个事件，副流程自己订阅：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


public Order createOrder(...) {
 Order o = orderRepo.save(...);
 publisher.publishEvent(new OrderCreatedEvent(o)); // 只发事件
 return o;
}

@Component
public class NotificationListener {
 @EventListener
 public void onCreate(OrderCreatedEvent e) { ... }
}

@Component
public class PointListener {
 @EventListener
 public void onCreate(OrderCreatedEvent e) { ... }
}

每个副流程独立、可单独测试、加新流程不动主业务。

同步 vs 异步

@EventListener 默认是同步的——和业务在同一个线程、同一个事务。这意味着：

任何 listener 抛异常，主业务回滚
listener 慢，主业务也慢

要改成异步，加 @Async：

1
2
3


@Async
@EventListener
public void onCreate(OrderCreatedEvent e) { ... }

这时 listener 在另一个线程跑，和主业务事务无关——常用于"发短信、发 MQ"这类不重要、可重试的副流程。

`@TransactionalEventListener`：等事务提交后再触发

最容易踩的坑——publishEvent 是在主业务事务提交之前调用的（在业务方法内）。所以无论同步还是异步监听器，listener 看到的都是"事务还没提交"的状态——副流程里去查 DB 可能查不到刚写入的数据：

1
2
3
4


@EventListener // 同步、异步（@Async）都一样
public void onCreate(OrderCreatedEvent e) {
 orderRepo.findById(e.getId()); // ❌ 可能查不到（事务还没提）
}

注意：这与"是否异步"无关——事件触发点本身就在事务提交之前。

正确写法：

1
2
3
4


@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
public void onCreate(OrderCreatedEvent e) {
 // 主事务已提交，可以放心读取
}

AFTER_COMMIT 是最常用——只有主事务提交后才触发。生产场景里只要副流程要读 DB 数据，几乎都要用它。

事件机制的典型适用场景

领域事件：用户注册、订单创建、支付完成
副流程触发：积分、消息推送、缓存清理
解耦不同模块：订单模块发事件，营销模块、库存模块、积分模块各自订阅
审计 / 操作记录

事件机制的限制和坑

1. 事件不要变成"远程过程调用"

1
2
3
4


@TransactionalEventListener
public Result onCreate(OrderCreatedEvent e) {
 return riskService.check(...); // ❌ 想要返回值？事件不该这么用
}

事件是单向通知，不是"调用"。需要返回值的逻辑应该走普通 Service 调用。

2. 异步事件 + 事务

@Async + @EventListener 跨线程后默认丢失主线程的事务上下文——副流程内部的 DB 操作处于"自己开新事务"模式。要小心数据一致性。

3. 事件溯源能力弱

Spring 事件是进程内的——重启就没了，没有"事件回放"能力。要做事件溯源（Event Sourcing）需要更专业的方案（Axon、自己写 outbox）。

4. 链式事件失控

A 事件触发 B listener，B listener 又发 C 事件，C 又发 D……复杂业务里事件链能绕成一团乱麻。控制好事件层级，建议不超过 2 跳。

三、AOP vs 事件：怎么选

	AOP	事件监听
目标	横切关注点	副流程解耦
与主业务关系	“包"主业务（before/after/around）	主业务发出，副流程自己订阅
多对一?	单切面 → 多方法	单事件 → 多 listener
跨事务?	同事务	可配置（同步/异步/事务后）
业务感知度	业务方法加注解或不加	业务方法显式 publishEvent
可见性	“魔法”	比 AOP 显式

简单判断：

跟业务逻辑无关、想做声明式开关 → AOP
业务做完后需要触发若干副流程 → 事件监听
既不是横切又不是副流程 → 直接调 Service

四、典型场景示例对比

场景：下单后清缓存

❌ 反例：写在业务里

1
2
3
4
5


public Order createOrder(...) {
 Order o = orderRepo.save(...);
 redis.delete("user:" + userId + ":orders");
 return o;
}

✅ 用 AOP（声明式缓存）

1
2


@CacheEvict(value = "user:orders", key = "#dto.userId")
public Order createOrder(OrderDTO dto) { ... }

适合"创建/修改/删除都要清同样的 cache”——纯横切。

✅ 用事件（多个副流程都要做）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


public Order createOrder(...) {
 Order o = orderRepo.save(...);
 publisher.publishEvent(new OrderCreatedEvent(o));
 return o;
}

@TransactionalEventListener(phase = AFTER_COMMIT)
public void cleanCache(OrderCreatedEvent e) { ... }

@TransactionalEventListener(phase = AFTER_COMMIT)
public void sendMQ(OrderCreatedEvent e) { ... }

副流程多、需要解耦时用事件。

五、组合用法

实际项目里两者经常配合：

1
2
3
4
5
6


@OperationLog("创建订单") // AOP 记审计
public Order createOrder(...) {
 Order o = orderRepo.save(...);
 publisher.publishEvent(new OrderCreatedEvent(o)); // 事件解耦副流程
 return o;
}

AOP 处理"操作日志"这种横切——业务无感
事件处理"积分/通知/MQ"这种副流程——主业务只发事件

六、几条工程惯例

1. 注解上限

业务方法上的 AOP 注解不要超过 3 个。多了说明：

你需要把多个注解合并成业务相关的 meta 注解（@OperationLog 包含审计 + 时间 + 权限）
或者你滥用了 AOP，把本该是业务的逻辑抽离了

2. 事件命名

事件名永远是**「实体 + 动作过去时」**：OrderCreatedEvent、UserRegisteredEvent、PaymentCompletedEvent。不要叫 CreateOrderEvent——前者表示"已发生"，后者像"指令"。

3. 事件的字段最小化

事件载荷只放"必要的标识 + 关键字段"，不要塞整个对象。listener 自己再去查 DB——避免事件载荷过大、同时减少耦合。

4. AOP 注解必须有"业务含义"

@LogTime、@RateLimit 一看就懂；不要写 @MyAspect1 这种含糊命名——业务方法签名应该自解释。

5. 事件不要用于强一致性场景

事件 = 异步 / 解耦 / 最终一致。强一致用普通调用 + 事务，事件不能替代。

6. 测试覆盖到 AOP 和事件

切面和监听器很容易在测试中被忽略——主业务跑得过、但 AOP/事件没生效，单测不一定能发现。要专门写集成测试覆盖。

小结