# wsitm-clutter

**Repository Path**: wsitm/wsitm-clutter

## Basic Information

- **Project Name**: wsitm-clutter
- **Description**: 杂烩工具，基于 Hutool， 针对业务进一步封装的工具
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-04-27
- **Last Updated**: 2026-05-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# wsitm-clutter

## 介绍
`wsitm-clutter` 是一个基于 [Hutool](https://github.com/looly/hutool) 的工具类库，针对业务场景进行了进一步封装，主要提供以下功能：

- **数据导出**：支持大数据量的 Excel（xlsx）和 CSV 文件导出
- **数据导入**：支持从 Excel 和 CSV 文件导入数据，内置校验机制
- **树形结构导出**：将树形结构数据可视化导出为 Excel 文件

该项目适用于需要高效处理数据导入导出、树形结构转换的业务场景。

## 功能概览

| 模块 | 功能 |
|------|------|
| `ExportKit` | 提供多种方式导出数据为 Excel 或 CSV 文件，支持注解配置、条件导出、自定义处理器 |
| `ImportKit` | 从 Excel/CSV 文件导入数据，支持字段映射、数据校验、错误收集 |
| `Tree2ExcelKit` | 将树形结构数据转换为可视化的 Excel 表格，支持多种对齐方式 |
| `@Header` | 注解方式定义导出字段的表头信息、格式化规则、条件标记等 |
| `HandlerAdapter` | 自定义数据处理器接口，支持泛型和非泛型两种实现方式 |

## 快速开始

### Maven 依赖

```xml
<dependency>
    <groupId>io.gitee.wsitm</groupId>
    <artifactId>wsitm-clutter</artifactId>
    <version>0.1.3</version>
</dependency>
```

### 基础依赖

本项目基于 [Hutool](https://github.com/looly/hutool)，请确保项目中已引入以下依赖：

```xml
<dependency>
    <groupId>cn.hutool</groupId>
    <artifactId>hutool-all</artifactId>
    <version>5.8.44</version>
</dependency>
```

## 使用示例

### 1. 数据导出

```java
// 定义数据模型
public class User {
    @Header(value = "用户ID", sort = 1)
    private String id;
    
    @Header(value = "用户名", sort = 2)
    private String name;
    
    @Header(value = "注册时间", dateFormat = "yyyy-MM-dd")
    private Date createTime;
    
    @Header(value = "状态", converterExp = "0=禁用,1=启用")
    private Integer status;
    
    // getter/setter
}

// 导出 Excel
List<User> users = getUsers();
ExportKit.exportXlsx(response, "users.xlsx", users);

// 导出 CSV
ExportKit.exportCsv("./output", "users.csv", users);

// 条件导出（只导出 conditionMarkers 匹配的字段）
ExportKit.exportXlsx(response, new int[]{1}, users);
```

### 2. 自定义数据处理器

```java
// 实现 BasicHandlerAdapter
public class MyHandler implements BasicHandlerAdapter {
    @Override
    public Object format(Object value, Object original) {
        // value: 当前字段值
        // original: 整行数据对象
        return "[处理]" + value;
    }
}

// 在字段上使用
@Header(value = "金额", handler = MyHandler.class)
private Double amount;
```

### 3. 树形结构导出

```java
// 定义树节点
public class TreeNode {
    private String name;
    private List<TreeNode> children;
    // getter/setter
}

// 导出树形结构
List<TreeNode> treeData = getTreeData();
Workbook workbook = new XSSFWorkbook();
Tree2ExcelKit.handle(workbook, treeData);  // 中对齐（默认）
Tree2ExcelKit.handle(workbook, treeData, Tree2ExcelKit.Type.TOP);  // 上对齐
```

### 4. 数据导入

```java
// 定义导入模型
public class ImportUser {
    @NotNull(message = "ID不能为空")
    @Header("用户ID")
    private String id;
    
    @NotEmpty(message = "姓名不能为空")
    @Header("姓名")
    private String name;
    
    // getter/setter
}

// 从文件导入
File file = new File("users.xlsx");
ImportResult<ImportUser> result = ImportKit.importData(file, ImportUser.class);

if (result.isSuccess()) {
    List<ImportUser> validData = result.getValidData();
    // 处理有效数据
} else {
    List<ImportError<ImportUser>> errors = result.getErrors();
    // 处理错误信息
}

// 带回调的导入
ImportOption<ImportUser> option = new ImportOption<ImportUser>()
    .setOnEach((rowNum, data) -> System.out.println("处理第 " + rowNum + " 行"))
    .setOnFinish((result) -> System.out.println("导入完成"));

ImportKit.importData(file, ImportUser.class, option);
```

## 核心特性

### ExportKit 特性

- ✅ 支持 Excel (.xlsx) 和 CSV 格式导出
- ✅ 支持注解配置表头、排序、列宽、日期格式等
- ✅ 支持枚举翻译（converterExp）
- ✅ 支持条件标记导出（conditionMarkers）
- ✅ 支持自定义数据处理器（HandlerAdapter）
- ✅ 支持前缀、后缀、百分比格式化
- ✅ 支持流式导出，适合大数据量场景
- ✅ 支持 Map 数据类型导出

### ImportKit 特性

- ✅ 支持 Excel (.xls/.xlsx) 和 CSV 格式导入
- ✅ 支持 javax.validation 和 jakarta.validation 约束注解校验
- ✅ 支持自定义逐行校验器
- ✅ 支持全量校验和首错即停两种模式
- ✅ 支持生命周期回调（onEach、onFinish）
- ✅ 自动字段映射和类型转换
- ✅ 详细的错误信息收集

### Tree2ExcelKit 特性

- ✅ 支持树形结构可视化导出
- ✅ 支持上对齐、中对齐、下对齐三种布局
- ✅ 自动绘制连接线
- ✅ 支持自定义标签字段和子节点字段
- ✅ 支持指定起始行列和间隔
- ✅ 支持 Map 和 JavaBean 两种数据结构

## 模块说明

### 包结构

```
io.gitee.wsitm
├── ExportKit.java              # 数据导出工具类
├── ImportKit.java              # 数据导入工具类
├── Tree2ExcelKit.java          # 树形结构导出工具类
├── anno/
│   └── Header.java             # 导出字段注解
├── export/
│   ├── HandlerAdapter.java     # 泛型数据处理器接口
│   ├── BasicHandlerAdapter.java # 非泛型数据处理器接口
│   ├── Column.java             # 列信息
│   ├── ExportInfo.java         # 导出信息
│   ├── ExportOption.java       # 导出配置项
│   ├── Merge.java              # 合并单元格信息
│   └── adapter/
│       ├── ResponseHandler.java      # 响应处理器接口
│       └── ServletResponseAdapter.java # Servlet响应适配器
└── imports/
    ├── ImportError.java        # 导入错误信息
    ├── ImportFieldMeta.java    # 导入字段元数据
    ├── ImportMeta.java         # 导入元数据
    ├── ImportOption.java       # 导入配置项
    ├── ImportResult.java       # 导入结果
    └── validation/
        ├── ConstraintAnnotationAdapter.java # 约束注解适配器
        └── ConstraintValidationSupport.java # 约束校验支持类
```

### @Header 注解属性

| 属性 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| value | String[] | 表头名称（支持多级表头） | - |
| sort | int | 排序号 | Integer.MAX_VALUE / 2 |
| width | int | 列宽（Excel有效，0表示自动） | 0 |
| prefix | String | 文字前缀 | "" |
| suffix | String | 文字后缀 | "" |
| percent | int | 百分比化（保留位数，-1表示不处理） | -1 |
| converterExp | String | 枚举翻译表达式（key1=value1,key2=value2） | "" |
| dateFormat | String | 日期格式 | "" |
| handler | Class<?> | 自定义数据处理器 | HandlerAdapter.class |
| conditionMarkers | int[] | 条件标记 | {} |

### ImportOption 配置项

| 方法 | 说明 | 默认值 |
|------|------|--------|
| setAllValidate(boolean) | 全量校验开关 | true |
| setCharset(Charset) | CSV字符集 | UTF-8 |
| setDelimiter(char) | CSV分隔符 | ',' |
| setOnEach(BiConsumer) | 每行回调 | null |
| setOnFinish(Consumer) | 完成回调 | null |
| setValidator(RowValidator) | 自定义校验器 | null |

## 支持的约束注解

ImportKit 支持以下常见的验证注解（兼容 javax 和 jakarta 包名）：

- `@NotNull` - 不能为null
- `@Null` - 必须为null
- `@NotEmpty` - 不能为空字符串或空集合
- `@NotBlank` - 不能为空白字符串
- `@Positive` - 必须为正数
- `@Negative` - 必须为负数
- `@Min` - 最小值
- `@Max` - 最大值
- `@DecimalMin` - 最小小数值
- `@DecimalMax` - 最大小数值
- `@Size` - 长度或大小限制
- `@Pattern` - 正则表达式匹配
- `@Email` - 邮箱格式

## 注意事项

1. **大数据量导出**：建议使用流式导出方式，避免内存溢出
2. **泛型处理器**：由于Java泛型擦除，HandlerAdapter<T> 在运行时第二个参数仍为Object类型
3. **约束注解**：只需注解名称和结构与规范一致即可，不强制要求包名
4. **树形导出**：节点类需包含标签字段和子节点列表字段
5. **编码问题**：CSV导出时注意设置正确的字符集，避免中文乱码

## 许可证

本项目遵循 [MIT License](https://opensource.org/licenses/MIT)，详情请查看 [LICENSE](LICENSE) 文件。

## 贡献指南

欢迎提交 Issue 和 Pull Request，帮助我们完善项目。请遵循以下贡献流程：

1. Fork 项目
2. 创建新分支 (`git checkout -b feature/your-feature`)
3. 提交代码 (`git commit -am 'Add some feature'`)
4. 推送到分支 (`git push origin feature/your-feature`)
5. 提交 Pull Request

## 联系方式

如有问题或建议，请提交 Issue 或联系项目维护者。

- Gitee: [https://gitee.com/wsitm/wsitm-clutter](https://gitee.com/wsitm/wsitm-clutter)
- Email: 392079454@qq.com

## 版本历史

- **v0.1.3** - 当前版本
  - 支持 HandlerAdapter 双模式（泛型/非泛型）
  - 完善数据导入功能，支持约束注解校验
  - 升级依赖至 hutool-all 5.8.44
  
- **v0.1.2**
  - 优化导出功能
  - 增强树形结构导出
  
- **v0.1.x** - 早期版本
  - 基础导出功能
  - 树形结构导出

## 致谢

感谢 [Hutool](https://github.com/looly/hutool) 提供的基础工具支持。