一、场景痛点与解决方案
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> {
@Override
public Class<?> supportJavaTypeKey() {
throw new UnsupportedOperationException("暂不支持，也不需要");
}
@Override
public CellDataTypeEnum supportExcelTypeKey() {
throw new UnsupportedOperationException("暂不支持，也不需要");
}
@Override
public 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);
}
@Override
public 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 {
@Test
void testExport() {
ConfigRespVO vo = new ConfigRespVO();
vo.setType(1);
// 导出验证Excel内容包含"文本类型"
EasyExcel.write("test.xlsx", ConfigRespVO.class).sheet().doWrite(Collections.singletonList(vo));
}
@Test
void testImport() {
// 准备包含"文本类型"的Excel文件
List<ConfigRespVO> list = EasyExcel.read("test.xlsx")
.head(ConfigRespVO.class).sheet().doReadSync();
assertEquals(1, list.get(0).getType()); // 验证转换结果
}
}
