cn-rdms/rdms-framework/rdms-spring-boot-starter-excel/README.md

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

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. 导出模板

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. 导入解析

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. 复杂流式处理或多工作簿复杂编排（建议单独实现）