py-ecology/py-base/easy.md

Poyee Easy 包功能说明

概述

com.poyee.easy 包是 Poyee 基础框架中的一个重要组件，主要提供了基于 EasyExcel 的 Excel 导入导出功能，并且特别支持国际化（i18n）处理。该包通过封装 Alibaba EasyExcel 库，提供了更高级的功能和更简洁的 API，使得 Excel 的导入导出操作更加便捷，特别是在需要多语言支持的国际化应用场景中。

核心组件

1. EasyExcelUtil

这是一个用于 Excel 导出的工具类，主要功能包括：

• 支持普通 Excel 导出和国际化 Excel 导出
• 提供链式调用 API，如 init(), i18nConfig(), build() 等
• 支持文件导出和流导出两种方式
• 支持多 Sheet 导出，特别是国际化场景下的多语言 Sheet

主要方法：

• init(Class<T> clazz, List<T> data): 初始化导出工具
• init(Class<T> clazz, List<T> data, String sheet): 初始化导出工具并指定 sheet 名称
• i18nConfig(EasyI18nConfig i18nConfig): 设置国际化配置
• build(): 构建导出工具
• doWrite(String path): 导出到文件
• doWriteStream(OutputStream out): 导出到输出流

使用示例：

EasyExcelUtil<ChecklistExcelDto, Object> easyExcelUtil = EasyExcelUtil.init(ChecklistExcelDto.class, checklistExcelDtos, baseInfo.getDisplayName())
    .i18nConfig(i18nConfig)
    .build();
easyExcelUtil.doWriteStream(outputStream);

2. EasyExcelImportUtil

这是一个用于 Excel 导入的工具类，主要功能包括：

• 支持普通 Excel 导入和国际化 Excel 导入
• 提供链式调用 API，如 create(), i18nConfig(), batch(), async() 等
• 支持批量处理和异步处理导入数据
• 支持从 URL 下载 Excel 文件并解析

主要方法：

• create(Class<T> clazz, Consumer<List<R>> consumer, Function<T, R> rowConverter): 创建导入工具
• i18nConfig(boolean isI18n, EasyI18nConfig i18nConfig): 设置国际化配置
• batch(): 启用批量处理
• batch(int batchCount): 启用批量处理并设置批处理数量
• async(ThreadPoolExecutor executor): 启用异步处理
• doRead(InputStream inputStream): 从输入流读取
• doRead(String fileUrl): 从 URL 读取

使用示例：

List<PaniniChecklistImport> list = new ArrayList<>();
EasyExcelImportUtil<PaniniChecklistImport, PaniniChecklistImport> importer = 
    EasyExcelImportUtil.create(PaniniChecklistImport.class, list::addAll, Function.identity())
    .i18nConfig(true, i18nConfig)
    .batch();
importer.doRead(url);

3. EasyExcelReadSheetListener

这是一个 EasyExcel 的事件监听器，用于处理 Excel 读取过程中的事件，特别是国际化数据的处理：

• 继承自 AnalysisEventListener，用于监听 Excel 读取过程
• 支持多 Sheet 读取，特别是国际化场景下的多语言 Sheet
• 提供数据转换和处理功能

主要方法：

• EasyExcelReadSheetListener(EasyI18nConfig config, Function<T, R> rowConverter, Consumer<List<R>> consumer): 构造函数
• init(): 初始化监听器
• invoke(T data, AnalysisContext context): 处理每行数据
• doAfterAllAnalysed(AnalysisContext context): 所有数据解析完成后的处理

4. EasyI18nConfig

这是一个国际化配置类，用于配置国际化 Excel 的导入导出：

• 定义了 Sheet 的结构，包括 key、name、header 和 data 等属性
• 支持多语言配置

主要属性：

• sheet: Sheet 配置列表

Sheet 类属性：

• index: Sheet 索引
• key: Sheet 映射的字段
• name: Sheet 名称
• header: Sheet 头部映射
• data: Sheet 数据

使用示例：

EasyI18nConfig i18nConfig = new EasyI18nConfig();
List<EasyI18nConfig.Sheet> sheetList = new ArrayList<>();
sheetList.add(new EasyI18nConfig.Sheet("playerTranslations", "player", Language.getLangEnMap()));
sheetList.add(new EasyI18nConfig.Sheet("teamTranslations", "team", Language.getLangEnMap()));
i18nConfig.setSheet(sheetList);

国际化支持

该包特别强调了对国际化的支持，主要体现在：

1. 多语言 Sheet：支持在一个 Excel 文件中包含多个语言的 Sheet，如主数据 Sheet 和语言翻译 Sheet

2. 国际化注解：使用 @ExcelI18nFromat 和 @i18n 注解来标记需要国际化处理的字段

3. 动态语言处理：根据 ServletUtils.isI18nSupport() 判断是否需要进行国际化处理

4. JSON 处理：使用 fastjson 库处理国际化数据的 JSON 格式化和解析

业务应用

在项目中，这些工具类主要用于：

1. Checklist 导入导出：如 CardChecklistBaseInfoServiceImpl 中的 downloadAndImport 和 downloadCheckList 方法

2. 国际化数据处理：如 doI18nImportChecklist 和 downloadI18nExcelAndParseExcel 方法

最佳实践

导出 Excel

// 1. 准备数据
List<YourDto> dataList = ...

// 2. 创建国际化配置（如果需要）
EasyI18nConfig i18nConfig = new EasyI18nConfig();
List<EasyI18nConfig.Sheet> sheetList = new ArrayList<>();
sheetList.add(new EasyI18nConfig.Sheet("fieldName", "sheetName", languageMap));
i18nConfig.setSheet(sheetList);

// 3. 初始化导出工具
EasyExcelUtil<YourDto, Object> easyExcelUtil = EasyExcelUtil.init(YourDto.class, dataList, "Sheet名称")
    .i18nConfig(i18nConfig)  // 如果需要国际化
    .build();

// 4. 导出到文件或流
easyExcelUtil.doWrite("path/to/file.xlsx");  // 导出到文件
// 或
easyExcelUtil.doWriteStream(outputStream);  // 导出到流

导入 Excel

// 1. 准备接收数据的集合
List<YourDto> list = new ArrayList<>();

// 2. 创建国际化配置（如果需要）
EasyI18nConfig i18nConfig = new EasyI18nConfig();
List<EasyI18nConfig.Sheet> sheetList = new ArrayList<>();
sheetList.add(new EasyI18nConfig.Sheet("fieldName", "sheetName", languageMap));
i18nConfig.setSheet(sheetList);

// 3. 创建导入工具
EasyExcelImportUtil<YourDto, YourDto> importer = 
    EasyExcelImportUtil.create(YourDto.class, list::addAll, Function.identity())
    .i18nConfig(true, i18nConfig)  // 如果需要国际化
    .batch(500)  // 批量处理，每500条处理一次
    .async(executor);  // 如果需要异步处理

// 4. 从文件或URL读取
importer.doRead(inputStream);  // 从输入流读取
// 或
importer.doRead("http://example.com/file.xlsx");  // 从URL读取

注意事项

1. 在使用国际化功能时，需要确保 DTO 类中有正确的注解标记

2. 导入大量数据时，建议使用批量处理和异步处理功能

3. 导出国际化 Excel 时，需要正确配置 EasyI18nConfig

4. 使用 URL 导入时，需要确保 URL 可访问且格式正确

总结

com.poyee.easy 包是一个专注于 Excel 处理的工具包，它基于 EasyExcel 库，提供了更高级的功能，特别是国际化支持。它通过链式 API 和注解的方式，简化了 Excel 导入导出的开发工作，并且特别适合需要多语言支持的国际化应用场景。