轮子再造就为数据脱敏：Spring Boot 全局注解 + 自定义策略实战

代码写得正嗨，突然想到一个需求：接口返回的用户手机号、身份证、银行卡号，是不是该做下脱敏处理？毕竟数据安全无小事。正好 Hutool 工具包里有现成的 DesensitizedUtil，那这次咱们就基于它“造”一个全局脱敏的轮子。思路清晰：自定义注解，配合 AOP 切面，哪里要脱敏就注解哪里。

先定义个总开关，一个标记在方法上的切入点注解 @DataDesensitized。

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

再搞一个字段级的注解 @Desensitized，用来标记需要脱敏的实体字段，脱敏策略直接用 Hutool 的枚举。

@Target({ElementType.FIELD, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Desensitized {
    //加上hutool类中的脱敏类型枚举选择脱敏策略
    DesensitizedUtil.DesensitizedType type();
}

万事俱备，切面登场。在 @AfterReturning 通知里，我们根据方法返回值类型（分页、集合还是单个对象）分类处理，然后反射遍历字段，完成脱敏替换。

@Aspect
@Component
@Slf4j
public class DataDesensitizedAspect{
    @AfterReturning(pointcut = "@annotation(dd)", returning = "result")
    public void doAfterReturning(JoinPoint joinPoint, DataDesensitized dd, Object result){
        //TODO 这里可以根据组织架构角色控制是否脱敏
        boolean need = true;
        if (!need) {
            return;
        }
        //方法响应一般有分页实体,list集合,单实体对象,那就分类处理
        if (result instanceof PageInfo) {
            PageInfo page = (PageInfo) result;
            List records = page.getList();
            for (Object record : records) {
                objReplace(record);
            }
        } else if (result instanceof List) {
            List list = (List) result;
            for (Object obj : list) {
                objReplace(obj);
            }
        } else {
            objReplace(result);
        }
    }

    public static <T> void objReplace(T t){
        try {
            Field[] declaredFields = ReflectUtil.getFields(t.getClass());
            for (Field field : declaredFields) {
                Desensitized des = field.getAnnotation(Desensitized.class);
                //被脱敏注解修饰且string类型
                if (des != null &&
                "class java.lang.String".equals(field.getGenericType().toString())) {
                    Object fieldValue = ReflectUtil.getFieldValue(t, field);
                    if (fieldValue == null || StringUtils.isEmpty(fieldValue.toString())) {
                        continue;
                    }
                    DesensitizedUtil.DesensitizedType type = des.type();
                    String hide = DesensitizedUtil.desensitized(fieldValue.toString(),type);
                    ReflectUtil.setFieldValue(t, field, hide);
                }
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

用法也很简单。在 Service 层的查询方法上打上 @DataProtection 注解（这里代码中注解名似乎写错了，实际上应该是我们定义的 @DataDesensitized，这点要注意），在返回的 VO 对象字段上标注 @Desensitized。

@Override
@DataProtection
public PageInfo<OrderDetailsVo> queryOrderDetails(QueryParam param){
    return mapper.queryOrderDetails(param);
}

@Data
public class OrderDetailsVo{
    private String orderNo;
    private String sn;

    @Desensitized(type = DesensitizedUtil.DesensitizedType.CHINESE_NAME)
    private String username;

    @Desensitized(type = DesensitizedUtil.DesensitizedType.MOBILE_PHONE)
    private String mobile;

    @Desensitized(type = DesensitizedUtil.DesensitizedType.ID_CARD)
    private String idCard;
}

本以为大功告成，结果第二天，产品经理就跑过来说：“那个 20 位的 SN 码，需要从第 5 位脱敏到第 18 位哦。” 一看 Hutool，没有这种局部自定义的脱敏类型。得，轮子还得继续改造。

看来完全依赖第三方工具类是不够的，我们得自己定义一套更灵活的脱敏策略。于是，自己动手写个 DesensitizedType 枚举，在 Hutool 的基础上，加一个 CUSTOM 类型。

public enum DesensitizedType {
    //自定义脱敏标识
    CUSTOM,
    //用户id
    USER_ID,
    //中文名
    CHINESE_NAME,
    //身份证号
    ID_CARD,
    //座机号
    FIXED_PHONE,
    //手机号
    MOBILE_PHONE,
    //地址
    ADDRESS,
    //电子邮件
    EMAIL,
    //密码
    PASSWORD,
    //中国大陆车牌，包含普通车辆、新能源车辆
    CAR_LICENSE,
    //银行卡
    BANK_CARD
}

同时，@Desensitized 注解也需要升级一下，增加自定义起止位置的能力。当 type 不指定（默认 CUSTOM）时，就可以通过 startInclude 和 endExclude 来自由控制脱敏区间。

@Target({ElementType.FIELD, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Desensitized {
    //替换成自己定义的枚举
    DesensitizedType type() default DesensitizedType.CUSTOM;

    /**
     * 当type不指定时,可自定义脱敏起始位置(包含)
     */
    int startInclude() default 0;

    /**
     * 当type不指定时,可自定义脱敏结束位置(不包含) ,-1代表字符串长度
     */
    int endExclude() default -1;
}

最后，把切面里的 objReplace 方法逻辑改一下，让它能识别 CUSTOM 模式，并根据配置的起止位置调用 StrUtil.hide。

public static <T> void objReplace(T t){
    try {
        Field[] declaredFields = ReflectUtil.getFields(t.getClass());
        for (Field field : declaredFields) {
            Desensitized des = field.getAnnotation(Desensitized.class);
            //被脱敏注解修饰且string类型
            if (des != null &&
            "class java.lang.String".equals(field.getGenericType().toString())) {
                Object fieldValue = ReflectUtil.getFieldValue(t, field);
                if (fieldValue == null || StringUtils.isEmpty(fieldValue.toString())) {
                    continue;
                }
                String value = fieldValue.toString();
                String hide = "";
                if (des.type() == DesensitizedType.CUSTOM) {
                    int startInclude = des.startInclude();
                    int endExclude = des.endExclude();
                    if (endExclude == -1) {
                        endExclude = value.length();
                    }
                    hide = StrUtil.hide(value, startInclude, endExclude);
                } else {
                    DesensitizedUtil.DesensitizedType type =
                            DesensitizedUtil.DesensitizedType.valueOf(des.type().toString());
                    hide = DesensitizedUtil.desensitized(value, type);
                }
                ReflectUtil.setFieldValue(t, field, hide);
            }
        }
    } catch (Exception e) {
        e.printStackTrace();
    }
}

这下，实体类中只需简单配置，就能轻松应对各种复杂的脱敏需求了。

@Data
public class OrderDetailsVo{
    private String orderNo;

    @Desensitized(startInclude = 5,endExclude = 18)
    private String sn;

    @Desensitized(type = DesensitizedType.CHINESE_NAME)
    private String username;

    @Desensitized(type = DesensitizedType.MOBILE_PHONE)
    private String mobile;

    @Desensitized(type = DesensitizedType.ID_CARD)
    private String idCard;
}

如果你也经常造轮子，会发现这种基于 Spring Boot AOP 的全局数据脱敏方案，非常适合在项目里快速落地，而且扩展性极强。怎么样，这个轮子是不是还挺趁手的？

注：此方案只针对 API 返回结果进行脱敏，存储到数据库中的仍是原始明文。如果要实现更彻底的脱敏，可以考虑结合 Mybatis 的 TypeHandler 或数据库层面的加密，不过那就是另一个故事了。