注解绑定列位置和格式更稳定易维护,支持列名+列序双定位、日期数字字典一体化格式配置、下拉合并语义声明及元信息审计字段扩展。

直接用注解绑定列位置和格式,比硬编码索引、手动写日期转换逻辑更稳也更易维护。关键不是“能不能加”,而是字段级控制要细到哪一层——列在哪一列、怎么显示、怎么校验、谁填的,都得在注解里说清楚。
列索引定义:支持列名+列序双模式
只靠列名匹配容易受Excel表头微调影响(比如多空格、中英文冒号混用),所以注解必须同时支持列名(columnName)和列序(columnIndex)两种定位方式:
- 默认优先按 columnName 匹配表头,大小写不敏感,自动 trim 空格
- 当传入 columnIndex ≥ 0 时,强制按物理列序读取(从 0 开始),跳过表头匹配,适合固定模板场景
- 两者同时存在时,以 columnIndex 为准,避免表头错位导致数据错行
格式化规则:日期、数字、字典值一体化配置
格式不是只给导出看的,导入时也要能反向解析。注解里把常见格式收敛成可复用字段:
-
dateFormat:仅对
Date或字符串型时间字段生效,导入时按该格式 parse,导出时按该格式 format -
numberFormat:如
"#,##0.00",用于金额、数量等数值字段,统一控制小数位与千分位 -
dictType 或 readConverterExp:例如
"0=未开始,1=进行中,2=已完成",导入时把文本转为对应枚举/数字,导出时把字段值转为中文描述
下拉与合并:业务语义直接下沉到注解
很多 Excel 场景不只是展示数据,还要约束输入、提升可读性。这些规则应该声明在字段上,而不是藏在工具类或 Service 里:
-
selectOptions:逗号分隔的字符串,如
"待审核,已通过,已驳回",导出模板时自动生成下拉列表 - selectRowRange:指定下拉生效的行范围,避免首行标题也被下拉覆盖
-
merge + mergeBy:设为
true且填"orderNo",表示按 orderNo 字段值合并当前列单元格,适合订单明细汇总类报表
元信息与审计字段:让每个列自带“身份证”
集团级系统常需追溯字段来源、更新人、是否脱敏等信息,这些不属于业务逻辑,但属于治理要求。注解里预留扩展槽位:
-
dataSource:标注该字段来自哪个子系统,如
"人力HRIS"、"电商OMS" - auditField:布尔值,标记该字段需记录操作人、操作时间(由通用拦截器自动注入)
-
maskRule:如
"mobile:4-8"表示手机号第4~8位脱敏,导出时自动处理











