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()); // 验证转换结果
    }
}
相关推荐
苍煜2 分钟前
MinIO 教程:从入门到Spring Boot集成
java·spring boot·后端·minio
掘金詹姆斯3 分钟前
LangChain4j—持久化聊天记忆 Persistence(五)
java·人工智能
程序猿大波17 分钟前
基于Java,SpringBoot,Vue,HTML宠物相亲配对婚恋系统设计
java·vue.js·spring boot
Leaf吧32 分钟前
分布式定时任务(xxl-job)
java·分布式
纪元A梦44 分钟前
华为OD机试真题——绘图机器(2025A卷:100分)Java/python/JavaScript/C++/C/GO最佳实现
java·javascript·c++·python·华为od·go·华为od机试题
louisgeek1 小时前
Android NSD 网络服务发现
android
24k小善1 小时前
FlinkSql入门与实践
java·大数据·flink·云计算
CodeCraft Studio1 小时前
Excel处理控件Spire.XLS系列教程:Java设置Excel活动工作表或活动单元格
java·python·excel
张可2 小时前
历时两年半开发,Fread 项目现在决定开源,基于 Kotlin Multiplatform 和 Compose Multiplatform 实现
android·前端·kotlin
瓯雅爱分享2 小时前
任务管理系统,Java+Vue,含源码与文档,科学规划任务节点,全程督办保障项目落地提效
java·mysql·vue·软件工程·源代码管理