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

一、场景痛点与解决方案

1. 问题背景

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

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

2. 设计方案

二、核心实现解析

1. 注解驱动设计

代码示例

java 复制代码

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

2. 双向转换流程

导出流程（值 → 标签）
Excel DictConvert DictService 请求转换值(1) getLabel("config_type", 1) "文本类型" 写入单元格 Excel DictConvert DictService

导入流程（标签 → 值）
Excel DictConvert DictService Java 读取单元格("文本类型") parseValue("config_type", "文本类型") "1" 设置Integer类型字段值 Excel DictConvert DictService Java

三、关键技术实现

1. 转换器核心类

java 复制代码

@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. 注解定义

java 复制代码

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

四、设计亮点总结

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

五、最佳实践建议

1. 常量统一管理

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

java 复制代码

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

2. 单元测试方案

java 复制代码

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()); // 验证转换结果
    }
}