# sensitive-export-spring-boot-starter

**Repository Path**: welsonmayun/sensitive-export-spring-boot-starter

## Basic Information

- **Project Name**: sensitive-export-spring-boot-starter
- **Description**: 一个用于Excel导出时进行数据脱敏的Spring Boot Starter
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-07-08
- **Last Updated**: 2025-07-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Sensitive Export Spring Boot Starter

[![License](https://img.shields.io/badge/license-Apache%202-4EB1BA.svg)](https://www.apache.org/licenses/LICENSE-2.0.html)

一个用于处理Excel导出中敏感数据的Spring Boot Starter，提供了灵活的数据脱敏和高性能的导出功能。

## 特性

- 🚀 **开箱即用** - 与Spring Boot无缝集成，最小化配置
- 🛡️ **数据安全** - 内置多种脱敏策略，支持自定义策略
- 📝 **注解驱动** - 使用注解优雅地标记需要脱敏的字段
- 🔧 **高度可配置** - 支持全局和局部配置，灵活控制脱敏行为
- 💪 **简单易用** - 提供简单易用的API接口，支持自动分页
- 🎯 **易扩展** - 支持自定义实现脱敏策略，批处理迭代

## 环境依赖

- JDK 1.8+
- Spring Boot 2.7.x
- EasyExcel 3.3.x

支持的依赖版本：

| 依赖项 | 版本      | 说明 |
|--------|---------|------|
| Spring Boot | 2.7.18  | 核心框架 |
| EasyExcel | 3.3.3   | Excel处理 |
| Servlet API | 4.0.1   | 提供Servlet支持 |

## 快速开始

### 1. 添加依赖

```xml
<dependency>
    <groupId>io.gitee.welson</groupId>
    <artifactId>sensitive-export-spring-boot-starter</artifactId>
    <version>2.0.0-SNAPSHOT</version>
</dependency>
```

### 2. 配置属性（可选）

```yaml
sensitive:
  export:
    enabled: true                       # 启用导出功能
    sensitive-enabled: true             # 启用脱敏功能
    sheet-max-rows: 1000000             # 单个Sheet最大行数
    over-flow-strategy: THROW_EXCEPTION # 溢出策略
    default-suffix: xlsx                # 默认文件后缀
    default-encoding: UTF-8             # 默认编码
```

### 3. 使用示例

#### 3.1 开启脱敏策略注解

```java
@EnableSensitiveExportStrategy
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}
```

#### 3.2 导出到响应流（用于Web下载）

```java
@EnableSensitiveExportStrategy
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}
```

```java
@Data
public class UserDTO {
    @SensitiveField(strategy = SensitiveStrategyType.NAME)
    private String name;

    @SensitiveField(strategy = SensitiveStrategyType.PHONE)
    private String phone;

    @SensitiveField(strategy = SensitiveStrategyType.ID_CARD)
    private String idCard;
}

@RestController
@RequestMapping("/api/users")
public class UserController {
    @Autowired
    private SensitiveExportService exportService;

    @GetMapping("/export")
    public void export(HttpServletResponse response) {
        // 准备数据
        List<UserDTO> users = getUserList();

        // 手动控制脱敏或明文导出
        SensitiveContext.markDesensitization(true);

        // 导出数据
        exportService.export(response, "用户信息", users, UserDTO.class);
    }
}
```

#### 3.3 导出到文件

```java
@Service
public class UserService {
    @Autowired
    private SensitiveExportService exportService;
    
    public void exportToFile() {
        // 准备数据
        List<UserDTO> users = getUserList();
        
        // 基础导出
        exportService.exportToFile("D:/exports/users.xlsx", users, UserDTO.class);
        
        // 使用自定义参数导出
        ExportParams params = ExportParams.builder()
                .fileName("用户信息")
                .sheetMaxRows(100000)
                .overflowStrategy(OverflowStrategy.PAGINATION)
                .build();
        exportService.exportToFile("D:/exports/users_custom.xlsx", params, users, UserDTO.class);
        
        // 多Sheet页导出
        List<SheetData<UserDTO>> sheetDataList = Arrays.asList(
            new SheetData<>("活跃用户", getActiveUsers()),
            new SheetData<>("新注册用户", getNewUsers())
        );
        exportService.exportMultiSheetToFile("D:/exports/users_multi_sheet.xlsx", sheetDataList, UserDTO.class);
        
        // 分批导出（适用于大数据量）
        exportService.exportBatchToFile("D:/exports/users_batch.xlsx", 
            (offset, batchSize) -> getUsersByPage(offset, batchSize), 
            1000, 
            UserDTO.class);
    }
}
```

## 内置脱敏策略

- 姓名脱敏：`张三` → `张*`
- 手机号脱敏：`13812345678` → `138****5678`
- 身份证号脱敏：`440123199001011234` → `440123********1234`
- 驾驶证号脱敏：`440123199001011234` → `440123********1234`
- 邮箱脱敏：`example@gmail.com` → `e****@gmail.com`
- 自定义正则脱敏：支持自定义正则表达式和替换规则

## 扩展点

1. 自定义脱敏策略
```java
@Component
public class CustomSensitiveStrategy implements SensitiveStrategy {
    @Override
    public String doMask(String value, String... params) {
        // 实现自定义脱敏逻辑
        return maskedValue;
    }
}
```

2. 自定义导出写入器
```java
@Component
public class CustomExportWriter implements ExportWriter {
    // 实现自定义导出逻辑
}
```

## 贡献指南

1. Fork 本仓库
2. 创建特性分支：`git checkout -b feature/AmazingFeature`
3. 提交改动：`git commit -m 'Add some AmazingFeature'`
4. 推送分支：`git push origin feature/AmazingFeature`
5. 提交 Pull Request

## 开源协议

本项目采用 [Apache 2.0 协议](LICENSE)。