EasyExcel 数据字典转换器实战：注解驱动设计

一、场景痛点与解决方案

1. 问题背景

在 Excel 导入导出场景中，开发者常面临以下问题：

数据可读性差：数据库存储的字典值（如 1、true）直接导出时难以理解
双向转换复杂：导入时需将用户输入的标签反向解析为存储值
代码侵入性强：硬编码字典类型导致业务逻辑与字典管理耦合

2. 设计方案

在这里插入图片描述

二、核心实现解析

1. 注解驱动设计

在这里插入图片描述
代码示例

@Data
public class ConfigRespVO {// 导出列声明 + 字典类型绑定@ExcelProperty(value = "参数类型", converter = DictConvert.class)@DictFormat(DictTypeConstants.CONFIG_TYPE) private Integer type;
}

2. 双向转换流程

导出流程（值 → 标签）

导入流程（标签 → 值）

三、关键技术实现

1. 转换器核心类

@Slf4j
public class DictConvert implements Converter<Object> {@Overridepublic Class<?> supportJavaTypeKey() {throw new UnsupportedOperationException("暂不支持，也不需要");}@Overridepublic CellDataTypeEnum supportExcelTypeKey() {throw new UnsupportedOperationException("暂不支持，也不需要");}@Overridepublic Object convertToJavaData(ReadCellData readCellData, ExcelContentProperty contentProperty,GlobalConfiguration globalConfiguration) {// 使用字典解析String type = getType(contentProperty);String label = readCellData.getStringValue();//通过type(sex)和label(女)获取value(0)String value = DictFrameworkUtils.parseDictDataValue(type, label);if (value == null) {log.error("[convertToJavaData][type({}) 解析不掉 label({})]", type, label);return null;}// 将 String 的 value 转换成对应的属性Class<?> fieldClazz = contentProperty.getField().getType();return Convert.convert(fieldClazz, value);}@Overridepublic WriteCellData<String> convertToExcelData(Object object, ExcelContentProperty contentProperty,GlobalConfiguration globalConfiguration) {// 空时，返回空if (object == null) {return new WriteCellData<>("");}// 使用字典格式化String type = getType(contentProperty);String value = String.valueOf(object);//通过type(sex)和value(0)获取label(女)String label = DictFrameworkUtils.getDictDataLabel(type, value);if (label == null) {log.error("[convertToExcelData][type({}) 转换不了 label({})]", type, value);return new WriteCellData<>("");}// 生成 Excel 小表格return new WriteCellData<>(label);}/*** 通过注解获取**/private static String getType(ExcelContentProperty contentProperty) {return contentProperty.getField().getAnnotation(DictFormat.class).value();}}

2. 注解定义

/*** 字典格式化* <p>* 实现将字典数据的值，格式化成字典数据的标签*/
@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface DictFormat {/*** 例如说，SysDictTypeConstants、InfDictTypeConstants** @return 字典类型*/String value();
}

四、设计亮点总结

设计维度	实现方案	解决的问题
声明式配置	通过组合注解实现配置	解耦业务代码与字典逻辑
类型安全转换	使用Hutool的Convert工具	自动处理String→Integer等类型转换
统一异常处理	捕获异常并记录错误日志	避免Excel解析中断
可扩展性	支持任意字典类型配置	方便新增字典类型

五、最佳实践建议

1. 常量统一管理

建议创建字典类型常量类：

public class DictTypeConstants {public static final String CONFIG_TYPE = "infra_config_type";public static final String BOOLEAN_STRING = "sys_boolean_string";
}

2. 单元测试方案

public class DictConvertTest {@Testvoid testExport() {ConfigRespVO vo = new ConfigRespVO();vo.setType(1);// 导出验证Excel内容包含"文本类型"EasyExcel.write("test.xlsx", ConfigRespVO.class).sheet().doWrite(Collections.singletonList(vo));}@Testvoid testImport() {// 准备包含"文本类型"的Excel文件List<ConfigRespVO> list = EasyExcel.read("test.xlsx").head(ConfigRespVO.class).sheet().doReadSync();assertEquals(1, list.get(0).getType()); // 验证转换结果}
}