JSON数据脱敏

最后更新: 17 天前

实践版本: v2.13.4

简介

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

主要特性

• 开箱即用：基于注解的自动脱敏处理，无需复杂配置
• 多种脱敏策略：内置手机号、邮箱、身份证、银行卡、车牌号等常见脱敏场景
• 自定义能力：支持自定义脱敏规则和处理器，满足特殊业务需求
• 无侵入性：对业务代码零侵入，仅在数据输出时进行脱敏处理
• JSON集成：完美集成 Jackson，支持复杂对象结构的脱敏

快速开始

引入依赖

pom.xml

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

使用注解

在需要脱敏的实体类字段上添加 @JsonMask 注解，并根据需求配置相应属性：

@Data
@Schema(description = "用户信息响应")
public class UserResp {
    
    @Schema(description = "用户ID")
    private Long id;
    
    @Schema(description = "用户名")
    private String username;
    
    /**
     * 手机号（脱敏）：保留前3位和后4位
     */
    @Schema(description = "手机号")
    @JsonMask(type = MaskType.MOBILE_PHONE)
    private String phone;
    
    /**
     * 邮箱（脱敏）：仅保留第一个字母
     */
    @Schema(description = "邮箱")
    @JsonMask(type = MaskType.EMAIL)
    private String email;
    
    /**
     * 身份证号（脱敏）：保留前1位和后2位
     */
    @Schema(description = "身份证号")
    @JsonMask(type = MaskType.ID_CARD)
    private String idCard;
    
    /**
     * 银行卡号（脱敏）：保留前4位和后4位
     */
    @Schema(description = "银行卡号")
    @JsonMask(type = MaskType.BANK_CARD)
    private String bankCard;
    
    /**
     * 自定义脱敏：保留前2位和后2位
     */
    @Schema(description = "敏感信息")
    @JsonMask(type = MaskType.CUSTOM, left = 2, right = 2)
    private String sensitiveInfo;
}

@JsonMask 注解

数据脱敏核心注解，用于标记需要进行脱敏处理的字段。通过注解属性配置脱敏策略，实现灵活的数据脱敏。

/**
 * JSON 脱敏注解
 * <p>用于标记需要进行脱敏处理的字段，支持多种脱敏策略和自定义规则</p>
 *
 * @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>优先级高于脱敏类型，当指定策略时将忽略 value 属性</p>
     */
    Class<? extends IMaskStrategy> strategy() default IMaskStrategy.class;

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

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

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

内置脱敏类型

目前内置的脱敏类型 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	地址	只显示到地区，不显示详细地址，例如：北京市海淀区****
IPV4	IPv4 地址	例如：192.0.2.1 => 192.*.*.*
IPV6	IPv6 地址	例如：2001:0db8:86a3:08d3:1319:8a2e:0370:7344 => 2001:*:*:*:*:*:*:*
CUSTOM	自定义脱敏	结合 left、right 配置进行脱敏处理

自定义脱敏策略

对于复杂的脱敏需求，可通过实现 IMaskStrategy 接口自定义脱敏策略。只需重写 mask 方法，实现自定义的脱敏逻辑。

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

    /**
     * 数据脱敏
     *
     * @param str       原始字符串
     * @param character 脱敏符号
     * @param left      左侧保留位数
     * @param right     右侧保留位数
     * @return 脱敏后的数据
     */
    @Override
    public String mask(String str, char character, int left, int right) {
        // 略
    }
}

使用自定义脱敏策略：

@JsonMask(strategy = CustomMaskStrategy.class)
private String sensitiveInfo;

核心依赖

依赖	描述
top.continew.starter:continew-starter-core	核心模块
top.continew.starter:continew-starter-json-jackson	JSON 模块（Jackson 序列化支持）

参考资料

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