Skip to content

JSON数据脱敏

最后更新: 9 分钟前
实践版本: v2.13.0

简介

continew-starter-security-mask 是 ContiNew Starter 提供的基于注解的数据脱敏模块,支持 JSON 响应数据的自动脱敏处理,保护敏感信息在传输和展示过程中的安全性。

xml
<dependency>
    <groupId>top.continew.starter</groupId>
    <artifactId>continew-starter-security-mask</artifactId>
</dependency>

主要特性

  • 开箱即用: 基于注解的自动脱敏处理
  • 多种脱敏策略: 支持手机号、邮箱、身份证、银行卡、车牌号、密码等常见脱敏场景
  • 自定义脱敏: 支持自定义脱敏规则和处理器
  • 透明处理: 对业务代码无侵入,仅在数据输出时进行脱敏
  • JSON 集成: 完美集成 Jackson,支持复杂对象结构

@JsonMask 注解

介绍

数据脱敏注解,用于标记需要进行脱敏处理的字段。

java
/**
 * JSON 脱敏注解
 *
 * @author Charles7c
 * @since 1.4.0
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@JacksonAnnotationsInside
@JsonSerialize(using = JsonMaskSerializer.class)
public @interface JsonMask {

    /**
     * 脱敏类型
     */
    MaskType value() default MaskType.CUSTOM;

    /**
     * 脱敏策略
     * <p>
     * 优先级高于脱敏类型
     * </p>
     */
    Class<? extends IMaskStrategy> strategy() default IMaskStrategy.class;

    /**
     * 左侧保留位数
     * <p>
     * 仅在脱敏类型为 {@code DesensitizedType.CUSTOM } 时使用
     * </p>
     */
    int left() default 0;

    /**
     * 右侧保留位数
     * <p>
     * 仅在脱敏类型为 {@code DesensitizedType.CUSTOM } 时使用
     * </p>
     */
    int right() default 0;

    /**
     * 脱敏符号(默认:*)
     */
    char character() default CharConstants.ASTERISK;
}

示例

在需要脱敏的实体类字段上添加 @JsonMask 注解。

java
@Data
@Schema(description = "用户信息响应")
public class UserResp {
    
    @Schema(description = "用户ID")
    private Long id;
    
    @Schema(description = "用户名")
    private String username;
    
    /**
     * 手机号(脱敏)
     */
    @Schema(description = "手机号")
    @JsonMask(type = MaskType.MOBILE_PHONE)
    private String phone;
    
    /**
     * 邮箱(脱敏)
     */
    @Schema(description = "邮箱")
    @JsonMask(type = MaskType.EMAIL)
    private String email;
    
    /**
     * 身份证号(脱敏)
     */
    @Schema(description = "身份证号")
    @JsonMask(type = MaskType.ID_CARD)
    private String idCard;
    
    /**
     * 银行卡号(脱敏)
     */
    @Schema(description = "银行卡号")
    @JsonMask(type = MaskType.BANK_CARD)
    private String bankCard;
    
    /**
     * 自定义脱敏
     */
    @Schema(description = "敏感信息")
    @JsonMask(type = MaskType.CUSTOM, left = 2, right = 2)
    private String sensitiveInfo;
}

内置脱敏类型

目前内置的脱敏类型 MaskType 如下:

枚举值脱敏类型脱敏规则
MOBILE_PHONE手机号码保留前 3 位和后 4 位,例如:135****2210
FIXED_PHONE固定电话保留前 4 位和后 2 位
EMAIL电子邮箱邮箱前缀仅保留第 1 个字母,@ 符号及后面的地址不脱敏,例如:d**@126.com
ID_CARD身份证号保留前 1 位和后 2 位
BANK_CARD银行卡由于银行卡号长度不定,所以只保留前 4 位,后面保留的位数根据卡号决定展示 1-4 位
CAR_LICENSE中国大陆车牌(包含普通车辆、新能源车辆)例如:苏D40000 => 苏D4***0
CHINESE_NAME中文名只保留第 1 个汉字,例如:李**
PASSWORD密码密码的全部字符都使用脱敏符号代替,例如:******
ADDRESS地址只显示到地区,不显示详细地址,例如:北京市海淀区****
IPV4IPv4 地址例如:192.0.2.1 => 192.*.*.*
IPV6IPv6 地址例如:2001:0db8:86a3:08d3:1319:8a2e:0370:7344 => 2001:*:*:*:*:*:*:*
CUSTOM自定义脱敏结合 left、right 配置进行脱敏处理

自定义脱敏策略

如果你的脱敏要求更为复杂,我们还提供了 top.continew.starter.security.mask.strategy.IMaskStrategy 接口,只需要重写该接口的 mask 方法,然后在需要使用的地方引用即可。

java
/**
 * 自定义脱敏策略
 */
public class CustomMaskStrategy implements IMaskStrategy {

    /**
     * 数据脱敏
     *
     * @param str       原始字符串
     * @param character 脱敏符号
     * @param left      左侧保留位数
     * @param right     右侧保留位数
     * @return 脱敏后的数据
     */
    public String mask(String str, char character, int left, int right) {
        // 略
    }
}
java
@JsonMask(strategy = CustomMaskStrategy.class)
private String sensitiveInfo;

核心依赖

依赖描述
top.continew.starter:continew-starter-core核心模块
top.continew.starter:continew-starter-json-jacksonJSON 模块(Jackson 序列化支持)

参考资料

  1. Jackson 自定义序列化文档:https://github.com/FasterXML/jackson-docs/wiki/JacksonHowToCustomSerializers