Skip to content

starter-excel ​

1. 职责 ​

把「字典 + Excel」两件在后台系统里高频出现的事封成一套:DictFrameworkUtils 提供字典 label ↔ value 的缓存查询与校验注解,ExcelUtils 提供一行导出的写方法,并配套 5 个转换器(字典、多值字典、JSON、金额、地区)与两个写处理器(自适应列宽、下拉框)。

它的定位是「少写样板」:Controller 里 ExcelUtils.write(response, "用户.xlsx", "用户", UserExcelVO.class, list) 即可,不需要自己拼 ExcelWriter。

它不解决:超大文件流式导入导出(仍是一次性读进内存的 doReadAllSync)、复杂模板报表(用积木报表等工具)、Excel 的公式计算。

本节路径均省略公共前缀 framework/pmforge-spring-boot-starter-excel/src/main/java/com/pmforge/framework/。

2. 关键类 ​

类作用路径
PmforgeDictAutoConfiguration唯一自动配置:把 DictDataCommonApi 注入静态工具dict/config/PmforgeDictAutoConfiguration.java
DictFrameworkUtils字典缓存(Guava,1 分钟异步刷新)+ parseDictDataLabel/Value、getDictDataLabelListdict/core/DictFrameworkUtils.java
InDict / InDictValidator / InDictCollectionValidator请求参数校验:值必须存在于字典中(集合逐项校验)dict/validation/
ExcelUtilswrite(response, filename, sheetName, head, data) 与 read(file, head)excel/core/util/ExcelUtils.java
DictFormat / ExcelColumnSelect字段注解:字典格式化;导出下拉框(按字典或按函数)excel/core/annotations/
DictConvert / MultiDictConvert字典值 ↔ label;多值字典用逗号存储、导出用顿号「、」excel/core/convert/
JsonConvert / MoneyConvert / AreaConvertJSON 字符串、分 → 元、地区 label → idexcel/core/convert/
ColumnWidthMatchStyleStrategy自适应列宽(最大 255),比 Excel 默认多处理 DATE 类型excel/core/handler/ColumnWidthMatchStyleStrategy.java
SelectSheetWriteHandler生成「字典sheet」并给列加下拉约束(FIRST_ROW=1、LAST_ROW=2000)excel/core/handler/SelectSheetWriteHandler.java
ExcelColumnSelectFunction下拉数据来源接口:getName() + getOptions(),不一定是字典excel/core/function/ExcelColumnSelectFunction.java

3. 自动配置 ​

配置类生效条件注册了什么
PmforgeDictAutoConfiguration始终装配DictFrameworkUtils dictUtils(DictDataCommonApi):调 DictFrameworkUtils.init(...) 后返回实例

DictDataCommonApi 的实现(pmforge-module-system)必须存在,否则这个 Bean 创建失败——starter-excel 因此隐式依赖 system 模块的字典能力。

4. 配置项 ​

前缀键默认值说明
—无—本模块没有 @ConfigurationProperties,也没有可调的导出参数

写死的常量(改不了,只能改代码):

常量值出处
字典缓存时长1 分钟(异步刷新)DictFrameworkUtils
下拉生效行第 1 ~ 2000 行SelectSheetWriteHandler
字典 sheet 名字典sheetSelectSheetWriteHandler
最大列宽255 字符ColumnWidthMatchStyleStrategy

5. 扩展点 ​

  • 导出:VO 字段标 @ExcelProperty(value = "状态", converter = DictConvert.class),字典类型通过 @DictFormat("system_user_status") 传给转换器。
  • 导入:ExcelUtils.read(file, UserExcelVO.class) 返回 List,内部 doReadAllSync;要边读边处理请直接用 FastExcel 的 ReadListener。
  • 下拉数据不是字典:实现 ExcelColumnSelectFunction 注册成 Bean,注解上写 @ExcelColumnSelect(functionName = "userNames")。
  • 货币/地区:MoneyConvert(分 → 元,HALF_UP 保留 2 位)、AreaConvert(label → Area.id,依赖 biz-ip)。
  • 多值字典:MultiDictConvert 支持 String、数组、Collection,用「、」显示、逗号入库。

6. 常见坑 ​

  1. 底层是 FastExcel(cn.idev.excel),不是 EasyExcel:注解名相同(@ExcelProperty),但工具类、监听器、转换器接口都不同,直接抄 EasyExcel 的代码编译不过。
  2. 转换器只能挂在字段上:5 个转换器的 supportJavaTypeKey()/supportExcelTypeKey() 都抛 UnsupportedOperationException("暂不支持,也不需要"),所以不能用 registerConverter 全局注册,必须写进 @ExcelProperty(converter = ...)。
  3. 下拉框只对前 2000 行生效:LAST_ROW = 2000 是常量;导出超过 2000 行时后续单元格没有下拉,用户可自由输入。
  4. 字典值改不了缓存即时性:DictFrameworkUtils 用 1 分钟异步刷新,后台改字典后最坏要等 1 分钟;单测/脚本里手动改数据需要 clearCache()。
  5. MultiDictConvert 的「、」是硬编码的:库里存逗号、导出显示顿号,读回来时按 [、,,] 三种分隔符 split——如果业务自己用顿号入库,再导出会变成双顿号。
  6. 响应头在写完流之后才设置:ExcelUtils.write 先 doWrite 再设 Content-Disposition/Content-Type,所以写文件过程中抛异常时前端拿到的不是 Excel;自己封装时务必先设头。
  7. 中文文件名要编码:框架用 HttpUtils.encodeUtf8 处理,自写下载接口时直接 setHeader("Content-Disposition", "attachment;filename=用户.xlsx") 会乱码。

7. 关联页面 ​