AOP on 牛哥聊技术

用 Jackson 和 AOP 优雅地处理接口数据脱敏

Thu, 18 Feb 2021 15:30:00 +0800

这件事每个面向用户的接口都遇到

合规要求越来越严，业务接口里要返回手机号、身份证、邮箱、银行卡——但生产环境必须脱敏：

1
2
3
4


138****8000 原: 13800138000
510123****0023 原: 510123199001020023
z****@163.com 原: zhangsan@163.com
6228**********0023 原: 6228480000010990023

一个朴素的实现是在 Service 里手动转换：

1
2
3
4
5
6
7
8
9


public UserVO getUser(Long id) {
 User user = userRepo.findById(id).orElseThrow();
 UserVO vo = new UserVO();
 vo.setName(user.getName());
 vo.setPhone(MaskUtil.maskPhone(user.getPhone())); // 手动脱敏
 vo.setIdCard(MaskUtil.maskIdCard(user.getIdCard())); // 手动脱敏
 vo.setEmail(MaskUtil.maskEmail(user.getEmail())); // 手动脱敏
 return vo;
}

写一两次不烦——写到一百次必出错：

新人写新接口忘了脱敏 → 信息泄漏
字段重命名时 Util 的调用没改全 → 漏脱敏
测试环境不希望脱敏 → 各处 if 判断又加 bug
一个字段多个接口都返回 → 改脱敏规则要改一堆地方

正确姿势是——让脱敏变成"声明式"：

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


public class UserVO {
 private String name;

 @Sensitive(type = PHONE)
 private String phone;

 @Sensitive(type = ID_CARD)
 private String idCard;

 @Sensitive(type = EMAIL)
 private String email;
}

写一次注解，所有接口自动生效。本文讲清楚怎么用 Jackson 自定义序列化 + AOP 实现这套机制，以及生产环境的细节。

一、最朴素：用 Jackson 自定义序列化器

Spring Boot 默认用 Jackson 序列化 JSON——拦截这个过程是最干净的姿势。

1. 定义脱敏类型

1
2
3
4
5
6
7
8
9


public enum SensitiveType {
 PHONE,
 ID_CARD,
 EMAIL,
 BANK_CARD,
 NAME,
 ADDRESS,
 CUSTOM;
}

2. 定义注解

1
2
3
4
5
6
7
8
9


@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@JacksonAnnotationsInside // 让自定义注解能携带其他 Jackson 注解
@JsonSerialize(using = SensitiveSerializer.class)
public @interface Sensitive {
 SensitiveType type();
 int prefix() default -1;
 int suffix() default -1;
}

@JacksonAnnotationsInside 是一个非常关键的"元注解"——它让 @Sensitive 自带 @JsonSerialize 的能力。

3. 写自定义序列化器

 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
31
32


public class SensitiveSerializer extends JsonSerializer<String>
 implements ContextualSerializer {

 private SensitiveType type = SensitiveType.PHONE;
 private int prefix = -1;
 private int suffix = -1;

 public SensitiveSerializer() {}
 public SensitiveSerializer(SensitiveType type, int prefix, int suffix) {
 this.type = type;
 this.prefix = prefix;
 this.suffix = suffix;
 }

 @Override
 public void serialize(String value, JsonGenerator gen, SerializerProvider sp)
 throws IOException {
 if (value == null) { gen.writeNull(); return; }
 gen.writeString(SensitiveUtil.mask(value, type, prefix, suffix));
 }

 @Override
 public JsonSerializer<?> createContextual(SerializerProvider prov,
 BeanProperty property) {
 if (property == null) return this;
 Sensitive ann = property.getAnnotation(Sensitive.class);
 if (ann != null) {
 return new SensitiveSerializer(ann.type(), ann.prefix(), ann.suffix());
 }
 return this;
 }
}

ContextualSerializer 让序列化器能在每次使用时拿到字段上的注解参数——这是注解能"传参"的关键。

4. 实现脱敏工具

 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
31
32
33
34


public class SensitiveUtil {
 public static String mask(String src, SensitiveType type, int prefix, int suffix) {
 if (src == null || src.isEmpty()) return src;
 switch (type) {
 case PHONE:
 return src.length() == 11 ? src.substring(0, 3) + "****" + src.substring(7) : src;
 case ID_CARD:
 return src.length() == 18 ? src.substring(0, 6) + "********" + src.substring(14) : src;
 case EMAIL:
 int at = src.indexOf('@');
 if (at <= 1) return src;
 String name = src.substring(0, at);
 String mask = name.charAt(0) + "****";
 return mask + src.substring(at);
 case BANK_CARD:
 return src.length() < 4 ? src : "****" + src.substring(src.length() - 4);
 case NAME:
 return src.charAt(0) + "*";
 case ADDRESS:
 return src.length() <= 10 ? src : src.substring(0, 6) + "****";
 case CUSTOM:
 return maskCustom(src, prefix, suffix);
 default:
 return src;
 }
 }

 private static String maskCustom(String src, int prefix, int suffix) {
 if (src.length() <= prefix + suffix) return src;
 return src.substring(0, prefix)
 + "*".repeat(src.length() - prefix - suffix)
 + src.substring(src.length() - suffix);
 }
}

5. 实战使用

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


public class UserVO {
 private String name;

 @Sensitive(type = PHONE)
 private String phone;

 @Sensitive(type = ID_CARD)
 private String idCard;

 @Sensitive(type = EMAIL)
 private String email;

 @Sensitive(type = CUSTOM, prefix = 4, suffix = 4)
 private String bankCard;

 // getters / setters
}

业务代码原汁原味：

1
2
3
4
5
6
7


@GetMapping("/users/{id}")
public UserVO getUser(@PathVariable Long id) {
 User user = userRepo.findById(id).orElseThrow();
 UserVO vo = new UserVO();
 BeanUtils.copyProperties(user, vo); // 直接拷贝
 return vo; // 返回时 Jackson 自动脱敏
}

二、按角色控制是否脱敏

需求经常是这样：

普通用户调接口看到 138****8000；管理员调接口看到完整 13800138000。

注解里加一个"绕过角色"：

1
2
3
4


public @interface Sensitive {
 SensitiveType type();
 String[] bypassRoles() default {}; // 这些角色不脱敏
}

修改序列化器（在原有字段基础上加 bypassRoles，并在 createContextual 里读注解传进新实例）：

 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
31
32
33
34
35
36
37


public class SensitiveSerializer extends JsonSerializer<String> implements ContextualSerializer {

 private SensitiveType type = SensitiveType.PHONE;
 private int prefix = -1;
 private int suffix = -1;
 private String[] bypassRoles = new String[0]; // ★ 新增

 public SensitiveSerializer() {}
 public SensitiveSerializer(SensitiveType type, int prefix, int suffix, String[] bypassRoles) {
 this.type = type;
 this.prefix = prefix;
 this.suffix = suffix;
 this.bypassRoles = bypassRoles;
 }

 @Override
 public void serialize(String value, JsonGenerator gen, SerializerProvider sp)
 throws IOException {
 if (value == null) { gen.writeNull(); return; }
 Set<String> myRoles = UserContextHolder.current().getRoles();
 if (Arrays.stream(bypassRoles).anyMatch(myRoles::contains)) {
 gen.writeString(value); // 不脱敏
 return;
 }
 gen.writeString(SensitiveUtil.mask(value, type, prefix, suffix));
 }

 @Override
 public JsonSerializer<?> createContextual(SerializerProvider prov, BeanProperty property) {
 if (property == null) return this;
 Sensitive ann = property.getAnnotation(Sensitive.class);
 if (ann != null) {
 return new SensitiveSerializer(ann.type(), ann.prefix(), ann.suffix(), ann.bypassRoles());
 }
 return this;
 }
}

业务里：

1
2


@Sensitive(type = PHONE, bypassRoles = {"ADMIN", "RISK_OPS"})
private String phone;

三、Jackson 方案的限制

Jackson 序列化是 JSON 输出阶段 才介入——它解决了"返回给前端时脱敏"。但有些场景它不能覆盖：

入参脱敏（用户上传含敏感数据，落库前要脱敏）
写日志脱敏（日志里也不能完整打印身份证）
第三方接口调用脱敏（你不直接控制 JSON 序列化）

这些场景需要 AOP 配合。

四、AOP 方案：方法级数据转换

AOP 拦截 Controller / Service 方法，在方法返回后遍历返回对象，手动改写带 @Sensitive 的字段：

 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
31
32


@Aspect
@Component
public class SensitiveAspect {

 @AfterReturning(value = "@annotation(SensitiveResult)", returning = "result")
 public void after(JoinPoint pjp, Object result) {
 maskRecursively(result);
 }

 private void maskRecursively(Object obj) {
 if (obj == null) return;
 if (obj instanceof Collection) {
 ((Collection<?>) obj).forEach(this::maskRecursively);
 return;
 }
 for (Field f : obj.getClass().getDeclaredFields()) {
 Sensitive ann = f.getAnnotation(Sensitive.class);
 if (ann != null && f.getType() == String.class) {
 f.setAccessible(true);
 try {
 String v = (String) f.get(obj);
 f.set(obj, SensitiveUtil.mask(v, ann.type(), ann.prefix(), ann.suffix()));
 } catch (IllegalAccessException ignored) {}
 } else if (!f.getType().isPrimitive() && !f.getType().getName().startsWith("java.")) {
 f.setAccessible(true);
 try {
 maskRecursively(f.get(obj));
 } catch (IllegalAccessException ignored) {}
 }
 }
 }
}

调用方加注解：

1
2


@SensitiveResult
public List<UserVO> listUsers() { ... }

Jackson vs AOP

	Jackson	AOP
触发时机	JSON 序列化时	方法返回时
改的对象	输出流	Java 对象本身
后续可读	输出流写完即结束	对象被改了，后续逻辑读到脱敏值
性能	高	中（反射遍历）
控制粒度	字段级	方法级 + 字段级
适用	接口返回	入参、日志、复杂场景

生产推荐组合：Jackson 处理 99% 的接口返回，AOP 处理少数特殊场景。

五、踩坑提醒

1. 不要原地修改 Entity

AOP 方案里有个隐含风险——直接修改了 User 实体的字段：

1
2


List<User> users = userRepo.findAll();
maskRecursively(users); // 改了实体！

如果接下来还要把这些 users 写回 DB，会写入脱敏后的值——数据被破坏。

正确做法：只对 VO 脱敏，永不对 Entity。VO 是临时对象，Entity 是数据。

2. 注解要打在 String 上

Long、Integer 这些类型上加 @Sensitive 不会生效（序列化器只处理 String）——身份证存 String 不要存 Long。

3. 集合 + 嵌套对象

JSON 序列化器自动递归处理嵌套；AOP 方案要手动写递归，容易栈溢出——加个深度限制：

1
2
3
4


private void maskRecursively(Object obj, int depth) {
 if (depth > 10) return;
 // ...
}

4. 缓存的对象

如果对象被脱敏后又被放进缓存，缓存里的值就是脱敏的——下次拿出来给管理员也是脱敏的。永远只在最后一刻（接口返回）脱敏。

5. 日志里也要脱敏

1

log.info("user info: {}", user); // ❌ user.toString() 含完整手机号

可以为 Lombok 的 @ToString 用 @ToString.Exclude，或在 Logback 配 PatternMaskingFilter。

6. 测试环境不脱敏

通过 Profile 切换：

1
2
3
4
5


@Profile({"!test"})
@Configuration
public class SensitiveConfig {
 // 注册序列化器
}

测试环境关闭脱敏，方便调试。

7. 某些字段不脱敏 = 数据合规风险

不要让"业务方便"凌驾于合规之上——有人为了排查问题要"管理员能看完整信息"，要做：

操作日志（谁在什么时候查了谁的完整数据）
二次确认（点"查看完整"才显示）
限频（每天最多查 N 个）

六、生产推荐架构

flowchart TD
 Req[接口请求] --> Controller
 Controller --> Service[业务逻辑]
 Service --> DB[(DB 存原文)]
 Service --> VO[转 VO]
 VO --> Sensitive["@Sensitive 注解
(声明式)"]
 Sensitive --> Jackson[Jackson 序列化
自动脱敏]
 Jackson --> Resp[返回前端]
 
 Logging[日志记录] --> LogMask[Logback PatternFilter
脱敏]

每一层都有自己的脱敏机制，VO 上的注解是核心声明，序列化器/AOP/日志过滤器各自落实。

小结

把全文压一句：

**数据脱敏不该写在业务代码里——它属于『数据展示层』的事。用注解声明字段类型，用 Jackson 序列化器或 AOP 做执行——业务代码只关心业务。 **

工程上几条铁律：

永远脱敏 VO，不脱敏 Entity
接口返回用 Jackson 序列化器，特殊场景用 AOP 兜底
日志脱敏单独走 Logback Filter
角色绕过要严格审计
测试环境通过 Profile 关闭

把这套做对，业务代码再也不用满地 MaskUtil.maskPhone(...)，新接口加字段也不会漏脱敏。

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/事件没生效，单测不一定能发现。要专门写集成测试覆盖。

小结