主题
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、getDictDataLabelList | dict/core/DictFrameworkUtils.java |
InDict / InDictValidator / InDictCollectionValidator | 请求参数校验:值必须存在于字典中(集合逐项校验) | dict/validation/ |
ExcelUtils | write(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 / AreaConvert | JSON 字符串、分 → 元、地区 label → id | excel/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 名 | 字典sheet | SelectSheetWriteHandler |
| 最大列宽 | 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. 常见坑
- 底层是 FastExcel(
cn.idev.excel),不是 EasyExcel:注解名相同(@ExcelProperty),但工具类、监听器、转换器接口都不同,直接抄 EasyExcel 的代码编译不过。 - 转换器只能挂在字段上:5 个转换器的
supportJavaTypeKey()/supportExcelTypeKey()都抛UnsupportedOperationException("暂不支持,也不需要"),所以不能用registerConverter全局注册,必须写进@ExcelProperty(converter = ...)。 - 下拉框只对前 2000 行生效:
LAST_ROW = 2000是常量;导出超过 2000 行时后续单元格没有下拉,用户可自由输入。 - 字典值改不了缓存即时性:
DictFrameworkUtils用 1 分钟异步刷新,后台改字典后最坏要等 1 分钟;单测/脚本里手动改数据需要clearCache()。 MultiDictConvert的「、」是硬编码的:库里存逗号、导出显示顿号,读回来时按[、,,]三种分隔符 split——如果业务自己用顿号入库,再导出会变成双顿号。- 响应头在写完流之后才设置:
ExcelUtils.write先doWrite再设Content-Disposition/Content-Type,所以写文件过程中抛异常时前端拿到的不是 Excel;自己封装时务必先设头。 - 中文文件名要编码:框架用
HttpUtils.encodeUtf8处理,自写下载接口时直接setHeader("Content-Disposition", "attachment;filename=用户.xlsx")会乱码。
7. 关联页面
- starter-biz-ip:
AreaConvert依赖AreaUtils - pmforge-common:
DictDataCommonApi、JsonUtils - 字典管理、文件与导入导出、横切机制