# mybatis-desensitization-plugin
**Repository Path**: caigou6666/mybatis-desensitization-plugin
## Basic Information
- **Project Name**: mybatis-desensitization-plugin
- **Description**: 一个基于 Spring Boot + MyBatis 的轻量级字段脱敏框架，支持注解配置、插件拦截、SPI 策略扩展，内置多种脱敏类型（手机号、身份证、邮箱等）。可通过注解启用、YAML配置、线程级控制等方式灵活管理脱敏行为，支持自动或手动清理 ThreadLocal，适用于接口返回值、日志输出等多场景数据保护需求。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-24
- **Last Updated**: 2025-05-24
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 🌟 字段脱敏框架使用文档
## ✨ 框架功能简介
本框架通过注解和插件拦截机制，在 MyBatis 查询结果返回前对敏感字段进行脱敏处理，支持：
+ 多种内置脱敏策略（手机号、身份证、邮箱等）
+ 自定义脱敏策略（SPI 动态扩展）
+ 支持线程隔离控制脱敏行为
+ 支持跳过字段 / 跳过整线程脱敏
---
## 🚀 快速启用
### 1. 引入依赖模块
确保已引入 starter 模块。
```xml
com.caigou
mybatis-sensitive-plugin-starter
1.0.0
```
**项目中使用之前，需要注入 mybatisplus 插件！**
```java
@Resource
private ApplicationContext applicationContext;
@Bean
public SqlSessionFactory sqlSessionFactory() throws Exception {
PathMatchingResourcePatternResolver resolver =
new PathMatchingResourcePatternResolver();
SqlSessionFactoryBean sessionFactory = new SqlSessionFactoryBean();
sessionFactory.setDataSource(dataSource());
sessionFactory.setFailFast(true);
sessionFactory.setMapperLocations(resolver.getResources("classpath:/mapper/*Mapper.xml"));
/*
* 添加插件信息(因为插件采用责任链模式所有可以有多个，所以采用数组
*/
if (applicationContext.containsBean("desensitizationInterceptor")) {
DesensitizationInterceptor desensitizationInterceptor = applicationContext.getBean(
DesensitizationInterceptor.class);
Interceptor[] interceptors = new Interceptor[1];
interceptors[0] = desensitizationInterceptor;
sessionFactory.setPlugins(interceptors);
}
return sessionFactory.getObject();
}
```
### 2. 添加启用注解（优先级最高）
在 `Spring Boot` 启动类上添加注解：
```java
@EnableDesensitization
@SpringBootApplication
public class MainApplication {
public static void main(String[] args) {
SpringApplication.run(MainApplication.class, args);
}
}
```
### 3. YAML 配置文件启用(优先级第二)
```yaml
desensitization:
enabled: true
```
平级优先级，控制当前线程或接口，临时禁用。
DesensitizationContext.tempDisEnabled();
## 🏷️ 脱敏注解说明
### `@SensitiveField`
在实体字段上添加该注解以启用脱敏。
```java
@SensitiveField("EMAIL")
private String email;
@SensitiveField(value = "AAA", fillValue = "X")
private String name;
```
参数说明：
+ `value`: 策略类型，对应 `SensitiveTypeEnums` 或自定义策略 `getType()`
+ `fillValue`: 脱敏字符，默认 `*`
---
## 🔌 插件策略管理
### 查看当前已注册的所有脱敏策略：
```java
SensitiveContext.printAllStrategies();
```
输出为 JSON 格式，示例如下：
```plain
{
"name": "EMAIL",
"class": "com.caigou.desensitization.strategy.impl.EmailStrategyHandle",
"isUserCreate": false
}
```
isUserCreate 是否是用户创建的脱敏策略
## ⚙️ 脱敏控制用法
### 跳过指定字段的脱敏（当前线程）
```java
DesensitizationContext.addFields(User.class, "email", "mobile");
```
### 临时禁用当前线程所有字段脱敏
```java
DesensitizationContext.tempDisEnabled();
```
### 恢复启用脱敏（可选）
```java
DesensitizationContext.tempEnable();
```
---
## 🔄 ThreadLocal 自动/手动清理
### 自动清理（推荐）
使用注解 `@AutoClearDesensitization` 标注方法，执行完成后会自动清理 ThreadLocal 状态：
```java
@AutoClearDesensitization
@GetMapping("/findAllUser")
public List findAllUser() {
DesensitizationContext.tempDisEnabled();
DesensitizationContext.addFields(User.class, "mobile", "email");
return userMapper.findAllUser();
}
```
### 手动清理（灵活控制）
```java
try {
DesensitizationContext.addFields(User.class, "mobile", "email");
return userMapper.findAllUser();
} finally {
DesensitizationContext.clear(); // 强制清理 ThreadLocal
}
```
---
## 🧩 自定义策略扩展（SPI）
1. 实现接口 `SensitiveStrategy`
2. 实现方法 `getType()` 返回唯一标识
3. 将实现类添加到 `META-INF/services/...` 中
```java
public class AAAStrategyHandle implements SensitiveStrategy {
@Override
public String getType() {
return "AAA";
}
@Override
public String handle(Object object, String fillValue) {
// 自定义处理逻辑
}
}
```
创建文件。com.caigou.desensitization.strategy.SensitiveStrategy 固定的写法
文件内容是你实现的脱敏策略类
## 📌 示例 Controller
```java
@AutoClearDesensitization
@GetMapping("/findAllUser")
public List findAllUser() {
DesensitizationContext.addFields(User.class, "mobile", "email");
return userMapper.findAllUser();
}
```
---
## 🧪 示例实体
```java
public class User {
@SensitiveField("EMAIL")
private String email;
@SensitiveField("MOBILE")
private String mobile;
@SensitiveField("ADDRESS")
private String address;
}
```