Java高级特性-注解：注解实现Excel导出功能

Posted 2021-08-23 JerryWu

注解是 Java 的一个高级特性，Spring 更是以注解为基础，发展出一套“注解驱动编程”。

这听起来高大上，但毕竟是框架的事，我们也能用好注解吗？

的确，我们很少有机会自己写注解，导致我们搞不清楚注解是怎么回事，更别提用好注解了。

既然这样，我们就从具体的工作出发，开发一个 Excel 导出功能。我相信，你在搞懂这个例子后，就能明白注解是怎么个用法。

Excel 导出-需求拆解

在后台管理系统中，常常需要把数据导出 Excel 表。

比如，在双十一过后，销售部要把商品订单录入到 Excel 表，财务部要把支付订单录入到 Excel 表，然后各部门汇总分析，最后找个时间讨论怎么改善公司的服务。

你想呀，双十一的订单成千上万，靠人工录入，少说也要花三四天，而且还特别容易出错。所以，你必须开发 Excel 导出功能。

那么，具体怎么做呢？

上次我们提到，注解想发挥作用，有三个要素：定义、使用、读取。这次，我们就利用注解的三个特性，来实现 Excel 导出功能，设计过程是这样的。

第一步，我们要创建不同的 Excel 模型。双十一过后，销售部要订单数据，财务部要支付数据，两个部门要的 Excel 表肯定也不一样，这就得帮每个部门创建不同的 Excel 模型，他们拿到想要的数据。

第二步，我们要根据 Excel 模型，来导出 Excel 表。

看到这，你应该明白 Excel 导出的设计过程了。接下来，我们就来一步步实现这个功能。

创建 Excel 模型

创建 Excel 模型，涉及到注解三要素中的定义、使用。

首先，定义 Excel 注解，我们直接看关键代码。

@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface ExcelField {

    /**
     * 导出字段标题
     */
    String title();
    
    /**
     * 导出字段排序（升序）
     */
    int sort() default 0;
    
    /**
     * 对齐方式（0：自动；1：靠左；2：居中；3：靠右）
     */
    int align() default 0;    

}

这里用到了两个元注解@Retention和@Target。@Target代表这个注解只能放在成员变量上；@Retention代表这个注解要加载到 JVM 内存，我们可以用反射来读取注解。

此外，注解还有 3 个成员变量，分别对应：Excel 的字段标题、字段排序、对齐方式，方便大家微调表格。到了这，定义 Excel 注解就完成了。

接下来，使用注解，我们还是直接看代码。

public class OrderModel {
    @ExcelField(title = "订单号", align = 2, sort = 20)
    private String orderNo;

    @ExcelField(title = "金额", align = 2, sort = 20)
    private String amount;
    
    // 创建时间
    private Date createTime;
    
    // 省略 getter/setter 方法
}

订单模型有 3 个字段：订单号、金额、创建时间，但这里注解只加到订单号、金额上，表示这两个字段会导出 Excel 表，而创建时间会忽略，你可以看看这副图片。

至此，我们完成了定义注解、使用注解，得到了一个 Excel 模型。但要想实现导出功能，还必须根据这个模型，生成出 Excel 表。

读取 Excel 模型

读取 Excel 模型，涉及到注解三要素中的读取。 我们需要读取注解，生成 Excel 表，这主要分成 3 个步骤：初始化 Excel 表对象—>写入数据到 Excel 表对象—>输出文件。

第一步，初始化 Excel 表对象。在这一步中，我们要根据 Excel 模型，生成一个 Excel 表对象，要创建这几个东西：标题、表头、样式等等。我们来看代码。

public class ExcelExporter {

    // ...省略无数代码

    /***************************** 初始化 Excel 表对象 ****************************/
    /**
     * 构造函数
     * @param title 表格标题，传“空值”，表示无标题
     * @param cls   excel模型对象
     */
    public ExcelExporter(String title, Class<?> cls) {
        // 获取注解list
        Field[] fs = cls.getDeclaredFields();
        for (Field f : fs) {
            ExcelField ef = f.getAnnotation(ExcelField.class);
            if (ef != null) {
                annotationList.add(new Object[]{ef, f});
            }
        }
        annotationList.sort(comparing(o -> ((ExcelField) o[0]).sort()));
        // 通过注解获取表头
        List<String> headerList = new ArrayList<>();
        for (Object[] os : annotationList) {
            String t = ((ExcelField) os[0]).title();
            headerList.add(t);
        }
        // 初始化excel表：创建excel表、添加表标题、创建表头等等
        initialize(title, headerList);
    }
}

在初始化的时候，我们先从 Excel 模型对象中读取注解，获得一个注解列表；然后，再从注解列表中，读取 title-字段标题；最后，再初始化 Excel 表对象，包括：创建 Excel 表对象、添加表标题、创建表头、添加样式。

第二步，写入数据到 Excel 表对象。在这一步中，我们要把 Java 的列表数据写到 Excel 表对象里，让这些数据能变成 Excel 表的一行行信息。还是来看代码。

public class ExcelExporter {

    /***************************** 初始化 Excel 表对象 ****************************/
    // ...省略无数代码

    /***************************** 写入数据到 Excel 表对象 ****************************/
    /**
     * 写入数据
     * @return list 数据列表
     */
    public <E> ExcelExporter setDataList(List<E> list) {
        for (E dataObj : list) {
            // 添加行
            Row row = this.addRow();

            // 获取数据，并写入单元格
            int cellNo = 0;
            for (Object[] os : annotationList) {
                // 获取成员变量的值
                Object value = null;
                try {
                    value = Reflections.invokeGetter(dataObj, ((Field) os[1]).getName());
                } catch (Exception ex) {
                    log.info(ex.toString());
                    value = "";
                }
                if (value == null) {
                    value = "";
                }

                // 写入单元格
                ExcelField ef = (ExcelField) os[0];
                this.addCell(row, cellNo++, value, ef.align());
            }
        }
        return this;
    }
}

我们先传入一个数据列表 dataList，然后用循环来遍历 dataList，在这个循环中，我们不断把数据写进 Excel 表对象里，具体操作是：创建了一个空白行，利用注解获取成员变量里的值，最后写进 Excel 表的单元格里。

第三步，输出文件。在这一步中，就是 Excel 表对象变成一个文件，来看下最后的代码吧。

public class ExcelExporter {

    /***************************** 初始化 Excel 表对象 ****************************/
    // ...省略无数代码

    /***************************** 写入数据到 Excel 表对象 ****************************/
    // ...省略无数代码

    /***************************** 输出相关 ****************************/
    /**
     * 输出到文件
     * @param fileName 输出文件名，加上绝对路径
     */
    public ExcelExporter writeFile(String fileName) throws IOException {
        FileOutputStream os = new FileOutputStream(fileName);
        this.write(os);
        return this;
    }
}

输出文件就没什么好说的了，就是指定文件名，然后把文件输出到指定的地方。

到了这，读取 Excel 模型就完成了。

当然，读取 Excel 模型涉及到注解的读取，这是最难理解的地方，因为读取注解要用到 Java 另一个高级特性—反射。而且，注解一般是用来简化业务，如果你对业务没有深刻的了解，是很难用好的。

限于篇幅，我只讲了最核心的代码，项目的完整代码放在文末的链接上，大家可以好好看看。

写在最后

注解想发挥作用，有三个要素：定义、使用、读取。这篇文章利用了注解的三要素，实现了 Excel 导出功能。

这分成两步。第一步，创建 Excel 模型，这涉及到注解三要素中的定义、使用；第二步，读取 Excel 模型，这涉及到注解三要素中的读取。

总之，注解一般用来简化业务，你要想用好注解，不但得熟练掌握 Java 的高级用法，还得对业务有深刻的理解。

文章演示代码：点击跳转