# data-masking-kit

**Repository Path**: lichunlin-forest/data-masking-kit

## Basic Information

- **Project Name**: data-masking-kit
- **Description**: 一款强大的数据脱敏工具包，用于保护敏感信息
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-10
- **Last Updated**: 2026-02-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 数据脱敏工具包 (Data Masking Kit)

项目简介
一个基于 Spring Boot 的通用数据脱敏框架，支持注解驱动、日志脱敏、MyBatis 拦截器加密等多种脱敏方式。提供灵活的可配置化脱敏策略，内置多种常见敏感数据类型脱敏规则。

## 核心特性

### 🛡️ 多种脱敏方式
- 注解驱动：通过 @DataMasking 注解标记需要脱敏的字段
- 日志脱敏：集成 Logback，自动对日志中的敏感信息进行脱敏
- MyBatis 拦截器：支持数据入库前加密、查询后解密
- 配置文件驱动：通过 properties 文件配置脱敏字段

### 📋 内置脱敏类型
- 身份证号 (15位/18位)
- 手机号码
- 固定电话
- 银行卡号
- 邮箱地址
- 车牌号
- 统一社会信用代码
- 护照号
- 军官证
- 税号等

### ⚙️ 灵活配置
- 支持前后缀保留位数配置
- 支持自定义脱敏字符
- 支持固定显示长度
- 支持正则表达式匹配替换
- 支持自定义脱敏策略

## 快速开始
### 1. 添加依赖
```xml
   <dependency>
   <groupId>com.forest</groupId>
   <artifactId>data-masking-kit</artifactId>
   <version>1.0.0</version>
   </dependency>
```   

### 2. 基础配置
```yaml
   config:
    data-masking:
      enabled: true                    # 总开关
      slf4j-enabled: true             # 日志脱敏开关
      encryption: false               # 数据加密开关（入库脱敏）
```   

### 3. json序列化配置
```java
ObjectMapper mapper = new ObjectMapper();
mapper.registerModule(DataMaskingModule);
```

### 4. 使用注解脱敏
```java
public class User {

   @DataMasking(maskType = MaskType.MOBILE_PHONE)
   private String mobile;

   @DataMasking(maskType = MaskType.ID_CARD)
   private String idCard;

   @DataMasking(prefixLen = 1, suffixLen = 1, maskChar = '*')
   private String name;

   @DataMasking(fixedDisplayLen = 3)
   private String email;

   @DataMasking(strategyName = "customMaskStrategy", isEncrypt = true)
   private String bankCard;
}
```   

### 5. 配置文件脱敏字段
在 `mask-field.properties` 中配置：
```properties
# 格式：字段名称=描述/屏蔽类型名称 || 字段名称=描述/固定显示长度 || 字段名称=正则/掩码 || 字段名称=前显示长度/后显示长度
#      字段名称=描述/正则/掩码 || 字段名称=描述/前显示长度/后显示长度
#      字段名称=屏蔽类型名称 || 字段名称=固定显示长度
mobile=手机号/(\\d{3})(\\d{4})(\\d{4})/$1****$3
idCard=身份证/(\\d{6})(\\d{8})([\\dXx]{4})/$1********$3
bankCard=银行卡/(\\d{4})(\\d{4})(\\d{4})(\\d{4})/$1****$3****
name=姓名/1/1
email=邮箱/3
address=地址/address
```

### 6. 编程式使用
```java
// 直接脱敏字符串
String maskedMobile = DataMaskingUtil.maskData("13812345678", MaskType.MOBILE_PHONE);

// 根据字段名脱敏
String maskedIdCard = DataMaskingUtil.maskData("idCard", "110101199001011234");

// 脱敏整个对象
User maskedUser = DataMaskingUtil.mask(user);
```
## 核心组件说明
### 注解体系
#### @DataMasking
```java
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface DataMasking {
MaskType maskType() default MaskType.CUSTOM;      // 脱敏类型
int prefixLen() default 0;                        // 前显示位数
int suffixLen() default 0;                        // 后显示位数
char maskChar() default '*';                      // 脱敏字符
int fixedDisplayLen() default 0;                  // 固定显示位数
Class<? extends MaskStrategy> strategy() default MaskStrategy.class; // 自定义策略
String strategyName() default "";                 // 策略名称
boolean isEncrypt() default false;                // 是否加密存储
}
```
#### 脱敏类型 (MaskType)
- 内置支持的脱敏数据类型：
- CHINESE_NAME - 中文姓名
- ID_CARD - 身份证号
- MOBILE_PHONE - 手机号码
- FIXED_PHONE - 固定电话
- EMAIL - 邮箱地址
- BANK_CARD - 银行卡号
- CAR_LICENSE - 车牌号
- PASSPORT - 护照号
等20+种常见类型

#### 脱敏策略 (MaskStrategy)
```java
public interface MaskStrategy {
String mask(String source);                       // 脱敏方法
MaskType getSupportMaskType();                    // 支持的脱敏类型

    default String defaultMask(String source, int prefixLen, int suffixLen) {
        // 默认实现
    }
}
```
## 高级功能
### 1. 自定义脱敏策略
```java
@Component
   public class CustomMaskStrategy implements MaskStrategy {

   @Override
   public String mask(String source) {
        // 自定义脱敏逻辑
        return source.substring(0, 2) + "****" + source.substring(source.length() - 2);
   }

   @Override
   public MaskType getSupportMaskType() {
        return MaskType.CUSTOM;
   }
}

// 使用自定义策略
@DataMasking(strategy = CustomMaskStrategy.class)
private String customField;
```

### 2. 数据加密存储
```java
   @DataMasking(maskType = MaskType.MOBILE_PHONE, isEncrypt = true)
   private String mobile;  // 入库时自动加密，查询时自动解密
```   
### 3. 日志脱敏
自动对 Logback 日志输出进行脱敏处理，在配置文件中使用LogbackConvert转换规则

### 4. MyBatis 拦截器
支持在数据持久化层自动处理加密字段：
- 插入/更新时：自动加密敏感字段
- 查询时：自动解密敏感字段

## 配置说明
### 自动配置类
- DataMaskingAutoConfiguration - 自动配置入口
- DataMaskProperties - 配置属性类

### 核心管理器
- MaskFieldManager - 脱敏字段管理器
- MaskStrategyManager - 脱敏策略管理器
- DefaultMaskFieldLoader - 默认字段加载器
- FieldInfoManager       - 脱敏字段信息管理器

### 序列化组件
- DataMaskingSerializer - Jackson 序列化器
- DataMaskingModule - Jackson 模块

## 扩展开发
### 添加新的脱敏类型
1.在 MaskType 枚举中添加新类型
2.在 MaskPatten 中定义正则规则
3.实现对应的 MaskStrategy


### 自定义字段加载
实现 IMaskTypeConstantField 接口：

```java
public class CustomMaskField implements IMaskTypeConstantField {
@Override
public String getFieldName() { return "customField"; }

    @Override
    public String getDesc() { return "自定义字段"; }
    
    @Override
    public MaskStrategy getStrategy() {
        return new CustomMaskStrategy();
    }
}
```
### 注意事项
- 性能考虑：大量数据脱敏时注意性能影响
- 加密密钥：使用加密功能时需要配置安全的密钥
- 正则优化：复杂正则表达式可能影响性能
- 线程安全：所有管理器组件都是线程安全的

## 版本信息
- 当前版本: 1.0.0
- JDK版本: 1.8+
- Spring Boot: 2.x+
- MyBatis-Plus: 3.x+ (可选)

## 许可证
Apache License 2.0