ContiNew

切换日光/暗黑模式

JSON数据脱敏 ​

最后更新: 20 天前
实践版本: 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