userList;
@SensitiveEntry
private User[] userArray;
//...
}
```
- 对象构建
```java
/**
* 构建用户-属性为列表，数组。列表中为对象。
* @return 构建嵌套信息
* @since 0.0.2
*/
public static UserEntryObject buildUserEntryObject() {
UserEntryObject userEntryObject = new UserEntryObject();
User user = buildUser();
User user2 = buildUser();
User user3 = buildUser();
userEntryObject.setUser(user);
userEntryObject.setUserList(Arrays.asList(user2));
userEntryObject.setUserArray(new User[]{user3});
return userEntryObject;
}
```
- 测试演示
```java
/**
* 用户属性中有集合或者对象，集合中属性是对象-脱敏测试
* @since 0.0.2
*/
@Test
public void sensitiveEntryObjectTest() {
UserEntryObject userEntryObject = DataPrepareTest.buildUserEntryObject();
System.out.println("脱敏前原始： " + userEntryObject);
UserEntryObject sensitiveUserEntryObject = SensitiveUtil.desCopy(userEntryObject);
System.out.println("脱敏对象： " + sensitiveUserEntryObject);
System.out.println("脱敏后原始： " + userEntryObject);
}
```
- 测试结果
```java
脱敏前原始： UserEntryObject{user=User{username='脱敏君', idCard='123456190001011234', password='1234567', email='12345@qq.com', phone='18888888888'}, userList=[User{username='脱敏君', idCard='123456190001011234', password='1234567', email='12345@qq.com', phone='18888888888'}], userArray=[User{username='脱敏君', idCard='123456190001011234', password='1234567', email='12345@qq.com', phone='18888888888'}]}
脱敏对象： UserEntryObject{user=User{username='脱*君', idCard='123456**********34', password='null', email='123**@qq.com', phone='188****8888'}, userList=[User{username='脱*君', idCard='123456**********34', password='null', email='123**@qq.com', phone='188****8888'}], userArray=[User{username='脱*君', idCard='123456**********34', password='null', email='123**@qq.com', phone='188****8888'}]}
脱敏后原始： UserEntryObject{user=User{username='脱敏君', idCard='123456190001011234', password='1234567', email='12345@qq.com', phone='18888888888'}, userList=[User{username='脱敏君', idCard='123456190001011234', password='1234567', email='12345@qq.com', phone='18888888888'}], userArray=[User{username='脱敏君', idCard='123456190001011234', password='1234567', email='12345@qq.com', phone='18888888888'}]}
```
# 系统内置脱敏策略
## 引入原因
如果你看了前面的内容，会看到这样的代码：
```java
@Sensitive(strategy = StrategyChineseName.class)
private String username;
```
但是这种需求很常见，就引入更简单的写法，如下：
```java
@SensitiveStrategyChineseName
private String name;
```
和上面效果是一致的。
不足：无法灵活指定生效条件，下个版本准备解决这个问题。
## 系统内置注解
| 注解 | 等价 @Sensitive | 备注 |
|:-------|:------|:------|
| `@SensitiveStrategyChineseName` | `@Sensitive(strategy = StrategyChineseName.class)` | 中文名称脱敏 |
| `@SensitiveStrategyPassword` | `@Sensitive(strategy = StrategyPassword.class)` | 密码脱敏 |
| `@SensitiveStrategyEmail` | `@Sensitive(strategy = StrategyEmail.class)` | email 脱敏 |
| `@SensitiveStrategyCardId` | `@Sensitive(strategy = StrategyCardId.class)` | 卡号脱敏 |
| `@SensitiveStrategyPhone` | `@Sensitive(strategy = StrategyPhone.class)` | 手机号脱敏 |
## 使用案例
使用的方式和 `@Sensitive` 是一样的，只是一种简化，方便日常使用。
与 `@SensitiveEntry` 的结合和 `@Sensitive` 完全一致，此处不再演示。
- SystemBuiltInAt.java
定义测试对象
```java
@SensitiveStrategyPhone
private String phone;
@SensitiveStrategyPassword
private String password;
@SensitiveStrategyChineseName
private String name;
@SensitiveStrategyEmail
private String email;
@SensitiveStrategyCardId
private String cardId;
//Getter Setter
//toString()
}
```
- 对象构建
```java
/**
* 构建系统内置对象
* @return 构建后的对象
* @since 0.0.3
*/
public static SystemBuiltInAt buildSystemBuiltInAt() {
SystemBuiltInAt systemBuiltInAt = new SystemBuiltInAt();
systemBuiltInAt.setName("脱敏君");
systemBuiltInAt.setPassword("1234567");
systemBuiltInAt.setEmail("12345@qq.com");
systemBuiltInAt.setCardId("123456190001011234");
systemBuiltInAt.setPhone("18888888888");
return systemBuiltInAt;
}
```
- 测试方法
测试方法断言如下。
```java
/**
* 普通属性脱敏测试
*/
@Test
public void sensitiveTest() {
final String originalStr = "SystemBuiltInAt{phone='18888888888', password='1234567', name='脱敏君', email='12345@qq.com', cardId='123456190001011234'}";
final String sensitiveStr = "SystemBuiltInAt{phone='188****8888', password='null', name='脱*君', email='123**@qq.com', cardId='123456**********34'}";
SystemBuiltInAt systemBuiltInAt = buildSystemBuiltInAt();
Assert.assertEquals(originalStr, systemBuiltInAt.toString());
SystemBuiltInAt sensitive = SensitiveUtil.desCopy(systemBuiltInAt);
Assert.assertEquals(sensitiveStr, sensitive.toString());
Assert.assertEquals(originalStr, systemBuiltInAt.toString());
}
```
## 与 @Sensitive 混合使用
如果你将新增的注解 `@SensitiveStrategyChineseName` 与 `@Sensitive` 同时在一个字段上使用。
为了简化逻辑，优先选择执行 `@Sensitive`，如果 `@Sensitive` 执行脱敏，
那么 `@SensitiveStrategyChineseName` 将不会生效。
如：
```java
/**
* 测试字段
* 1.当多种注解混合的时候，为了简化逻辑，优先选择 @Sensitive 注解。
*/
@SensitiveStrategyChineseName
@Sensitive(strategy = StrategyPassword.class)
private String testField;
```
# 自定义注解
- v0.0.4 新增功能。允许功能自定义条件注解和策略注解。
- v0.0.11 新增功能。允许功能自定义级联脱敏注解。
## 案例1
### 自定义密码脱敏策略&自定义密码脱敏策略生效条件
- 策略脱敏
```java
/**
* 自定义密码脱敏策略
* @author binbin.hou
* date 2019/1/17
* @since 0.0.4
*/
@Inherited
@Documented
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@SensitiveStrategy(CustomPasswordStrategy.class)
public @interface SensitiveCustomPasswordStrategy {
}
```
- 脱敏生效条件
```java
/**
* 自定义密码脱敏策略生效条件
* @author binbin.hou
* date 2019/1/17
* @since 0.0.4
*/
@Inherited
@Documented
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@SensitiveCondition(ConditionFooPassword.class)
public @interface SensitiveCustomPasswordCondition{
}
```
- TIPS
`@SensitiveStrategy` 策略单独使用的时候，默认是生效的。
如果有 `@SensitiveCondition` 注解，则只有当条件满足时，才会执行脱敏策略。
`@SensitiveCondition` 只会对系统内置注解和自定义注解生效，因为 `@Sensitive` 有属于自己的策略生效条件。
- 策略优先级
`@Sensitive` 优先生效，然后是系统内置注解，最后是用户自定义注解。
### 对应的实现
两个元注解 `@SensitiveStrategy`、`@SensitiveCondition` 分别指定了对应的实现。
- CustomPasswordStrategy.java
```java
public class CustomPasswordStrategy implements IStrategy {
@Override
public Object des(Object original, IContext context) {
return "**********************";
}
}
```
- ConditionFooPassword.java
```java
/**
* 让这些 123456 的密码不进行脱敏
* @author binbin.hou
* date 2019/1/2
* @since 0.0.1
*/
public class ConditionFooPassword implements ICondition {
@Override
public boolean valid(IContext context) {
try {
Field field = context.getCurrentField();
final Object currentObj = context.getCurrentObject();
final String name = (String) field.get(currentObj);
return !name.equals("123456");
} catch (IllegalAccessException e) {
throw new RuntimeException(e);
}
}
}
```
### 定义测试对象
定义一个使用自定义注解的对象。
```java
public class CustomPasswordModel {
@SensitiveCustomPasswordCondition
@SensitiveCustomPasswordStrategy
private String password;
@SensitiveCustomPasswordCondition
@SensitiveStrategyPassword
private String fooPassword;
//其他方法
}
```
### 测试
```java
/**
* 自定义注解测试
*/
@Test
public void customAnnotationTest() {
final String originalStr = "CustomPasswordModel{password='hello', fooPassword='123456'}";
final String sensitiveStr = "CustomPasswordModel{password='**********************', fooPassword='123456'}";
CustomPasswordModel model = buildCustomPasswordModel();
Assert.assertEquals(originalStr, model.toString());
CustomPasswordModel sensitive = SensitiveUtil.desCopy(model);
Assert.assertEquals(sensitiveStr, sensitive.toString());
Assert.assertEquals(originalStr, model.toString());
}
```
构建对象的方法如下：
```java
/**
* 构建自定义密码对象
* @return 对象
*/
private CustomPasswordModel buildCustomPasswordModel(){
CustomPasswordModel model = new CustomPasswordModel();
model.setPassword("hello");
model.setFooPassword("123456");
return model;
}
```
## 案例2
- v0.0.11 新增功能。允许功能自定义级联脱敏注解。
### 自定义级联脱敏注解
- 自定义级联脱敏注解
可以根据自己的业务需要，在自定义的注解上使用 `@SensitiveEntry`。
使用方式保持和 `@SensitiveEntry` 一样即可。
```java
/**
* 级联脱敏注解,如果对象中属性为另外一个对象(集合)，则可以使用这个注解指定。
*
* 1. 如果属性为 Iterable 的子类集合，则当做列表处理，遍历其中的对象
* 2. 如果是普通对象，则处理对象中的脱敏信息
* 3. 如果是普通字段/MAP，则不做处理
*
* @author dev-sxl
* date 2020-09-14
* @since 0.0.11
*/
@Inherited
@Documented
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@SensitiveEntry
public @interface SensitiveEntryCustom {
}
```
### 定义测试对象
定义一个使用自定义注解的对象。
```java
public class CustomUserEntryObject {
@SensitiveEntryCustom
private User user;
@SensitiveEntryCustom
private List userList;
@SensitiveEntryCustom
private User[] userArray;
// 其他方法...
}
```
### 测试
```java
/**
* 用户属性中有集合或者对象，集合中属性是对象-脱敏测试
* @since 0.0.11
*/
@Test
public void customSensitiveEntryObjectTest() {
final String originalStr = "CustomUserEntryObject{user=User{username='脱敏君', idCard='123456190001011234', password='1234567', email='12345@qq.com', phone='18888888888'}, userList=[User{username='脱敏君', idCard='123456190001011234', password='1234567', email='12345@qq.com', phone='18888888888'}], userArray=[User{username='脱敏君', idCard='123456190001011234', password='1234567', email='12345@qq.com', phone='18888888888'}]}";
final String sensitiveStr = "CustomUserEntryObject{user=User{username='脱*君', idCard='123456**********34', password='null', email='123**@qq.com', phone='188****8888'}, userList=[User{username='脱*君', idCard='123456**********34', password='null', email='123**@qq.com', phone='188****8888'}], userArray=[User{username='脱*君', idCard='123456**********34', password='null', email='123**@qq.com', phone='188****8888'}]}";
CustomUserEntryObject userEntryObject = DataPrepareTest.buildCustomUserEntryObject();
Assert.assertEquals(originalStr, userEntryObject.toString());
CustomUserEntryObject sensitiveUserEntryObject = SensitiveUtil.desCopy(userEntryObject);
Assert.assertEquals(sensitiveStr, sensitiveUserEntryObject.toString());
Assert.assertEquals(originalStr, userEntryObject.toString());
}
```
构建对象的方法如下：
```java
/**
* 构建用户-属性为列表，数组。列表中为对象。
*
* @return 构建嵌套信息
* @since 0.0.11
*/
public static CustomUserEntryObject buildCustomUserEntryObject() {
CustomUserEntryObject userEntryObject = new CustomUserEntryObject();
User user = buildUser();
User user2 = buildUser();
User user3 = buildUser();
userEntryObject.setUser(user);
userEntryObject.setUserList(Arrays.asList(user2));
userEntryObject.setUserArray(new User[]{user3});
return userEntryObject;
}
/**
* 构建测试用户对象
*
* @return 创建后的对象
* @since 0.0.1
*/
public static User buildUser() {
User user = new User();
user.setUsername("脱敏君");
user.setPassword("1234567");
user.setEmail("12345@qq.com");
user.setIdCard("123456190001011234");
user.setPhone("18888888888");
return user;
}
```
# 生成脱敏后的 JSON
## 说明
为了避免生成中间脱敏对象，v0.0.6 之后直接支持生成脱敏后的 JSON。
## 使用方法
新增工具类方法，可以直接返回脱敏后的 JSON。
生成的 JSON 是脱敏的，原对象属性值不受影响。
```java
public static String desJson(Object object)
```
## 注解的使用方式
和 `SensitiveUtil.desCopy()` 完全一致。
## 使用示例代码
所有的测试案例中，都添加了对应的 `desJson(Object)` 测试代码，可以参考。
此处只展示最基本的使用。
```java
@Test
public void sensitiveJsonTest() {
final String originalStr = "SystemBuiltInAt{phone='18888888888', password='1234567', name='脱敏君', email='12345@qq.com', cardId='123456190001011234'}";
final String sensitiveJson = "{\"cardId\":\"123456**********34\",\"email\":\"123**@qq.com\",\"name\":\"脱*君\",\"phone\":\"188****8888\"}";
SystemBuiltInAt systemBuiltInAt = DataPrepareTest.buildSystemBuiltInAt();
Assert.assertEquals(sensitiveJson, SensitiveUtil.desJson(systemBuiltInAt));
Assert.assertEquals(originalStr, systemBuiltInAt.toString());
}
```
## 注意
本次 JSON 脱敏基于 [FastJSON](https://github.com/alibaba/fastjson)。
FastJSON 在序列化本身存在一定限制。当对象中有集合，集合中还是对象时，结果不尽如人意。
### 示例代码
本测试案例可见测试代码。
```java
@Test
public void sensitiveUserCollectionJsonTest() {
final String originalStr = "UserCollection{userList=[User{username='脱敏君', idCard='123456190001011234', password='1234567', email='12345@qq.com', phone='18888888888'}], userSet=[User{username='脱敏君', idCard='123456190001011234', password='1234567', email='12345@qq.com', phone='18888888888'}], userCollection=[User{username='脱敏君', idCard='123456190001011234', password='1234567', email='12345@qq.com', phone='18888888888'}], userMap={map=User{username='脱敏君', idCard='123456190001011234', password='1234567', email='12345@qq.com', phone='18888888888'}}}";
final String commonJson = "{\"userArray\":[{\"email\":\"12345@qq.com\",\"idCard\":\"123456190001011234\",\"password\":\"1234567\",\"phone\":\"18888888888\",\"username\":\"脱敏君\"}],\"userCollection\":[{\"$ref\":\"$.userArray[0]\"}],\"userList\":[{\"$ref\":\"$.userArray[0]\"}],\"userMap\":{\"map\":{\"$ref\":\"$.userArray[0]\"}},\"userSet\":[{\"$ref\":\"$.userArray[0]\"}]}";
final String sensitiveJson = "{\"userArray\":[{\"email\":\"123**@qq.com\",\"idCard\":\"123456**********34\",\"phone\":\"188****8888\",\"username\":\"脱*君\"}],\"userCollection\":[{\"$ref\":\"$.userArray[0]\"}],\"userList\":[{\"$ref\":\"$.userArray[0]\"}],\"userMap\":{\"map\":{\"$ref\":\"$.userArray[0]\"}},\"userSet\":[{\"$ref\":\"$.userArray[0]\"}]}";
UserCollection userCollection = DataPrepareTest.buildUserCollection();
Assert.assertEquals(commonJson, JSON.toJSONString(userCollection));
Assert.assertEquals(sensitiveJson, SensitiveUtil.desJson(userCollection));
Assert.assertEquals(originalStr, userCollection.toString());
}
```
### 解决方案
如果有这种需求，建议使用原来的 `desCopy(Object)`。
# 针对集合的处理
`v0.0.7` 支持的新特性，便于用户处理集合相关的脱敏。
如果列表为空，则直接返回空列表。
更多测试代码参见 [SensitiveUtilCollectionTest.java](https://github.com/houbb/sensitive/blob/release_0.0.7/sensitive-test/src/test/java/com/github/houbb/sensitive/test/core/sensitive/collection/SensitiveUtilCollectionTest.java)
## 集合脱敏-对象拷贝
- List desCopyCollection(Collection collection)
返回脱敏后的对象集合
```java
List userList = DataPrepareTest.buildUserList();
List sensitiveList = SensitiveUtil.desCopyCollection(userList);
Assert.assertEquals("[User{username='脱*君', idCard='123456**********34', password='null', email='123**@qq.com', phone='188****8888'}, User{username='集**试', idCard='123456**********34', password='null', email='123**@qq.com', phone='188****8888'}]", sensitiveList.toString());
```
## 集合脱敏-json
- List desJsonCollection(Collection collection)
返回脱敏后的 json 列表
```java
List userList = DataPrepareTest.buildUserList();
List sensitiveJsonList = SensitiveUtil.desJsonCollection(userList);
Assert.assertEquals("[{\"email\":\"123**@qq.com\",\"idCard\":\"123456**********34\",\"phone\":\"188****8888\",\"username\":\"脱*君\"}, {\"email\":\"123**@qq.com\",\"idCard\":\"123456**********34\",\"phone\":\"188****8888\",\"username\":\"集**试\"}]", sensitiveJsonList.toString());
```
# 脱敏引导类
为了配置的灵活性，引入了引导类。
## 核心 api 简介
`SensitiveBs` 引导类的核心方法列表如下：
| 序号 | 方法 | 参数 | 结果 | 说明 |
|:---|:---|:---|:---|:---|
| 1 | desCopy() | 目标对象 | 深度拷贝脱敏对象 | 适应性更强 |
| 2 | desJson() | 目标对象 | 脱敏对象 json | 性能较好 |
## 使用示例
使用方式和工具类一致，示意如下：
```java
SensitiveBs.newInstance().desCopy(user);
```
## 配置深度拷贝实现
默认的使用 FastJson 进行对象的深度拷贝，等价于：
```java
SensitiveBs.newInstance()
.deepCopy(FastJsonDeepCopy.getInstance())
.desJson(user);
```
参见 [SensitiveBsTest.java](https://github.com/houbb/sensitive/blob/master/sensitive-test/src/test/java/com/github/houbb/sensitive/test/bs/SensitiveBsTest.java)
deepCopy 用于指定深度复制的具体实现，支持用户自定义。
# 深度复制（DeepCopy）
## 说明
深度复制可以保证我们日志输出对象脱敏，同时不影响正常业务代码的使用。
可以实现深度复制的方式有很多种，默认基于 [fastjson](https://github.com/alibaba/fastjson) 实现的。
为保证后续良性发展，v0.0.13 版本之后将深度复制接口抽离为单独的项目：
> [deep-copy](https://github.com/houbb/deep-copy)
## 内置策略
目前支持 6 种基于序列化实现的深度复制，便于用户替换使用。
每一种都可以单独使用，保证依赖更加轻量。
## 自定义
为满足不同场景的需求，深度复制策略支持用户自定义。
> [自定义深度复制](https://github.com/houbb/deep-copy#%E8%87%AA%E5%AE%9A%E4%B9%89)
# 需求 & BUGS
> [issues](https://github.com/houbb/sensitive/issues)
# 欢迎加入开发
如果你对本项目有兴趣，并且对代码有一定追求，可以申请加入本项目开发。
如果你善于写文档，或者愿意补全测试案例，也非常欢迎加入。
# ROAD-MAP
- [ ] 考虑添加针对 MAP 的脱敏支持
- [ ] 考虑对 JSON 的可拓展性，不拘泥于 FastJSON