90 lines
2.9 KiB
Markdown
90 lines
2.9 KiB
Markdown
# rdms-spring-boot-starter-excel
|
||
|
||
## 模块定位
|
||
这是一个面向业务的 Excel 能力模块，核心目标是：
|
||
|
||
1. 降低导入导出开发成本（统一工具类）
|
||
2. 让业务字段和 Excel 展示语义解耦（注解 + Converter）
|
||
3. 把字典能力接入 Excel 场景（值与标签互转、校验、下拉选项）
|
||
|
||
## 设计思路
|
||
|
||
1. 统一入口：通过 `ExcelUtils` 封装读写，Controller 只关心 VO 和数据。
|
||
2. 注解驱动：通过 `@DictFormat`、`@ExcelColumnSelect` 把“字段语义”放在 VO 上，而不是散落在业务代码里。
|
||
3. 转换器分层：`DictConvert`、`AreaConvert`、`JsonConvert`、`MoneyConvert` 分别处理不同类型转换。
|
||
4. 字典缓存：`DictFrameworkUtils` 基于缓存读取字典，减少重复远程调用。
|
||
5. 导出体验：自动列宽、下拉选项、Long 防精度丢失等细节统一在模块内处理。
|
||
|
||
## 核心类
|
||
|
||
1. `com.njcn.rdms.framework.excel.core.util.ExcelUtils`
|
||
2. `com.njcn.rdms.framework.excel.core.convert.DictConvert`
|
||
3. `com.njcn.rdms.framework.excel.core.handler.SelectSheetWriteHandler`
|
||
4. `com.njcn.rdms.framework.dict.core.DictFrameworkUtils`
|
||
5. `com.njcn.rdms.framework.dict.validation.InDict`
|
||
|
||
## 示例：用户导入导出（含字典转换）
|
||
|
||
### 1. 定义 Excel VO
|
||
|
||
```java
|
||
import cn.idev.excel.annotation.ExcelProperty;
|
||
import com.njcn.rdms.framework.excel.core.annotations.DictFormat;
|
||
import com.njcn.rdms.framework.excel.core.convert.DictConvert;
|
||
import lombok.Data;
|
||
|
||
@Data
|
||
public class UserImportExcelVO {
|
||
|
||
@ExcelProperty("登录名称")
|
||
private String username;
|
||
|
||
@ExcelProperty(value = "用户性别", converter = DictConvert.class)
|
||
@DictFormat("USER_SEX")
|
||
private Integer sex;
|
||
|
||
@ExcelProperty(value = "账号状态", converter = DictConvert.class)
|
||
@DictFormat("COMMON_STATUS")
|
||
private Integer status;
|
||
}
|
||
```
|
||
|
||
### 2. 导出模板
|
||
|
||
```java
|
||
import com.njcn.rdms.framework.excel.core.util.ExcelUtils;
|
||
import jakarta.servlet.http.HttpServletResponse;
|
||
|
||
public void exportTemplate(HttpServletResponse response) throws Exception {
|
||
ExcelUtils.write(response, "用户导入模板.xls", "用户列表", UserImportExcelVO.class, List.of());
|
||
}
|
||
```
|
||
|
||
### 3. 导入解析
|
||
|
||
```java
|
||
import com.njcn.rdms.framework.excel.core.util.ExcelUtils;
|
||
import org.springframework.web.multipart.MultipartFile;
|
||
|
||
public List<UserImportExcelVO> importExcel(MultipartFile file) throws Exception {
|
||
return ExcelUtils.read(file, UserImportExcelVO.class);
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
1. 导入时 `DictConvert` 会把 Excel 标签值转回字典 value（如“男”->`1`）。
|
||
2. 导出时 `DictConvert` 会把字典 value 转成可读标签（如 `1`->“男”）。
|
||
|
||
## 适用场景
|
||
|
||
1. 后台管理常规 Excel 导入导出
|
||
2. 字典字段较多、希望自动做值/标签转换
|
||
3. 需要生成带下拉选项的导入模板
|
||
|
||
## 不适用场景
|
||
|
||
1. 超大规模离线数据处理（建议走专用批处理链路）
|
||
2. 复杂流式处理或多工作簿复杂编排（建议单独实现）
|
||
|