Spring Boot + EasyExcel 实现 Excel 导入导出（实战篇）

Spring Boot + EasyExcel 实现 Excel 导入导出（实战篇）

上一篇我们已经掌握了Spring Boot文件上传的核心技巧，而Excel导入导出正是文件操作的延伸与核心落地场景——无论是日常办公的数据批量录入、系统数据备份，还是你要开发的小工具（如数据管理工具、报表工具），Excel导入导出都是不可或缺的核心功能。本文精准聚焦“落地小工具”需求，手把手实战EasyExcel整合Spring Boot，从依赖引入、实体类注解设计，到批量导入数据库、数据导出为Excel文件，全程贴合实际开发场景，代码可直接复制复用，帮你快速落地小工具核心功能，精准对接需求、高效引流。

一、前置准备：明确实战场景与环境搭建

本次实战以「用户数据管理」为核心场景（适配大多数小工具需求），实现两个核心功能：① 上传Excel文件，批量导入用户数据到数据库；② 查询数据库用户数据，导出为Excel文件。环境基于Spring Boot + EasyExcel + MyBatis-Plus + MySQL，简化复杂配置，聚焦核心功能落地。

1.1 核心依赖引入

重点引入EasyExcel核心依赖（轻量高效，避免POI的内存溢出问题），搭配MyBatis-Plus操作数据库，无需额外引入过多组件，适配小工具轻量需求：

<!-- Spring Boot Web 核心依赖（支持文件上传） -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<!-- EasyExcel 核心依赖（导入导出核心，推荐3.3.2版本，稳定无bug） -->
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>easyexcel</artifactId>
    <version>3.3.2</version>
</dependency>

<!-- MyBatis-Plus 核心依赖（操作数据库，简化CRUD） -->
<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-boot-starter</artifactId>
    <version>3.5.3.1</version>
</dependency>

<!-- MySQL 驱动 -->
<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <scope>runtime</scope>
</dependency>

<!-- lombok 简化代码（实体类、工具类无需写getter/setter） -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>
</dependency>

<!-- commons-io 工具类（简化文件操作，可选） -->
<dependency>
    <groupId>commons-io</groupId>
    <artifactId>commons-io</artifactId>
    <version>2.11.0</version>
</dependency>

1.2 核心配置（application.yml）

配置数据库连接、EasyExcel相关优化（可选）、文件上传限制，集中管理，便于后续部署修改，贴合小工具开发的简洁需求：

spring:
  # 数据库配置（替换为自己的数据库地址、用户名、密码）
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/springboot_easyexcel?useUnicode=true&characterEncoding=utf-8&serverTimezone=GMT%2B8
    username: root
    password: 123456

  # 文件上传配置（适配Excel导入，限制单个文件大小）
  servlet:
    multipart:
      enabled: true
      max-file-size: 50MB # 单个Excel文件最大50MB，满足大数据量导入
      max-request-size: 100MB

# MyBatis-Plus 配置
mybatis-plus:
  mapper-locations: classpath:mybatis/mapper/**/*.xml
  type-aliases-package: com.example.demo.entity
  configuration:
    map-underscore-to-camel-case: true # 驼峰命名映射
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl # 打印SQL日志，便于调试

# EasyExcel 自定义配置（可选，优化解析性能）
easyexcel:
  reader:
    batch-size: 100 # 批量读取行数，避免内存占用过高
    head-row-number: 1 # 默认表头行数（第0行是表头）
  writer:
    auto-close-stream: true # 自动关闭流，避免资源泄露

1.3 数据库表设计（用户表）

设计简单的用户表，用于存储Excel导入的数据、提供导出数据源，字段与Excel表头一一对应，适配小工具数据管理需求：

CREATE TABLE `sys_user` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '用户主键',
  `username` varchar(50) NOT NULL COMMENT '用户名（唯一）',
  `phone` varchar(11) DEFAULT NULL COMMENT '手机号',
  `role` varchar(20) NOT NULL COMMENT '用户角色（admin/普通用户）',
  `status` tinyint(1) DEFAULT 1 COMMENT '状态（1：正常，0：禁用）',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_username` (`username`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='系统用户表';

二、核心实战一：实体类注解设计（EasyExcel核心）

EasyExcel的核心优势的是“注解驱动”，无需手动解析Excel单元格，通过注解将实体类与Excel表头绑定，同时关联数据库实体，实现“Excel数据→实体类→数据库”的无缝映射，是导入导出的基础。

我们需要创建两个关联实体（可复用一个，按需区分）：① 数据库实体（SysUser）：映射数据库表；② Excel解析实体（ExcelUserDTO）：映射Excel表头，通过EasyExcel注解配置。

2.1 数据库实体（SysUser）

import com.baomidou.mybatisplus.annotation.*;
import lombok.Data;
import java.time.LocalDateTime;

/**
 * 数据库实体类（映射sys_user表）
 */
@Data
@TableName("sys_user")
public class SysUser {
    @TableId(type = IdType.AUTO)
    private Long id;

    // 用户名（与Excel表头“用户名”对应）
    private String username;

    // 手机号（与Excel表头“手机号”对应）
    private String phone;

    // 角色（与Excel表头“角色”对应）
    private String role;

    // 状态（默认1正常，Excel导入时可省略，自动填充）
    private Integer status = 1;

    // 创建时间（自动填充，无需Excel导入）
    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createTime;
}

2.2 Excel解析实体（ExcelUserDTO）

核心是EasyExcel注解，通过@ExcelProperty绑定Excel表头，明确列索引和表头名称，同时可添加数据校验、格式转换注解，适配Excel导入导出需求：

import com.alibaba.excel.annotation.ExcelIgnore;
import com.alibaba.excel.annotation.ExcelProperty;
import com.alibaba.excel.annotation.format.NumberFormat;
import lombok.Data;
import javax.validation.constraints.NotBlank;

/**
 * Excel解析实体类（与Excel表头绑定，用于导入导出）
 * 注解说明：
 * 1. @ExcelProperty：核心注解，value=Excel表头名称，index=列索引（0开始）
 * 2. @ExcelIgnore：忽略该字段，不导入也不导出
 * 3. @NotBlank：数据校验，导入时用户名不能为空
 * 4. @NumberFormat：格式转换（如手机号转为字符串，避免科学计数法）
 */
@Data
public class ExcelUserDTO {

    @ExcelIgnore // 主键自增，Excel中无该字段，忽略
    private Long id;

    @ExcelProperty(value = "用户名", index = 0) // 对应Excel第0列，表头“用户名”
    @NotBlank(message = "用户名不能为空") // 导入时校验，为空则报错
    private String username;

    @ExcelProperty(value = "手机号", index = 1) // 对应Excel第1列，表头“手机号”
    @NumberFormat("#") // 避免手机号（纯数字）转为科学计数法
    private String phone;

    @ExcelProperty(value = "角色", index = 2) // 对应Excel第2列，表头“角色”
    @NotBlank(message = "角色不能为空")
    private String role;

    @ExcelIgnore // 状态自动填充，不导入不导出
    private Integer status;

    @ExcelIgnore // 创建时间自动填充，不导入不导出
    private LocalDateTime createTime;
}

关键注意点：

1. Excel表头名称必须与@ExcelProperty的value完全一致（大小写、空格都要匹配），否则无法解析；
2. 无需导入/导出的字段，添加@ExcelIgnore注解，避免冗余；
3. 导入时的数据校验（如@NotBlank），可提前拦截非法数据，减少数据库异常。

三、核心实战二：Excel批量导入数据库（小工具核心功能）

Excel导入的核心逻辑：前端上传Excel文件 → 后端通过EasyExcel监听器解析Excel数据 → 数据校验 → 批量存入数据库，全程无冗余代码，适配小工具的高效落地需求。

3.1 自定义EasyExcel监听器（核心）

EasyExcel采用“监听器模式”解析Excel，自定义监听器处理每一行解析后的数据，实现数据校验、批量入库（避免频繁操作数据库，提升性能）：

import com.alibaba.excel.context.AnalysisContext;
import com.alibaba.excel.event.AnalysisEventListener;
import com.example.demo.dto.ExcelUserDTO;
import com.example.demo.entity.SysUser;
import com.example.demo.service.SysUserService;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.BeanUtils;
import org.springframework.util.CollectionUtils;
import javax.validation.Validation;
import javax.validation.Validator;
import javax.validation.ValidatorFactory;
import java.util.ArrayList;
import java.util.List;

/**
 * EasyExcel 导入监听器（处理Excel解析后的每一行数据）
 * 说明：监听器不能被Spring管理，需手动new，因此通过构造方法传入Service
 */
@Slf4j
public class ExcelUserImportListener extends AnalysisEventListener<ExcelUserDTO> {

    // 批量入库阈值（每100条数据批量插入一次，可调整）
    private static final int BATCH_SIZE = 100;
    // 存储解析后的Excel数据
    private List<ExcelUserDTO> userList = new ArrayList<>();
    // 注入用户Service，用于批量入库
    private final SysUserService sysUserService;
    // 数据校验器（校验Excel中的数据合法性）
    private final Validator validator;

    // 构造方法，传入Service（监听器无法被Spring自动注入，手动传入）
    public ExcelUserImportListener(SysUserService sysUserService) {
        this.sysUserService = sysUserService;
        // 初始化校验器
        ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
        this.validator = factory.getValidator();
    }

    /**
     * 每解析一行Excel数据，就会调用该方法
     * @param data 解析后的一行数据（与ExcelUserDTO对应）
     * @param context 解析上下文
     */
    @Override
    public void invoke(ExcelUserDTO data, AnalysisContext context) {
        log.info("解析Excel数据：{}", data);
        // 1. 数据校验（校验用户名、角色非空等）
        var violations = validator.validate(data);
        if (!violations.isEmpty()) {
            // 校验失败，抛出异常（可自定义异常，返回具体错误信息）
            throw new RuntimeException("第" + (context.readRowHolder().getRowIndex() + 1) + "行数据非法：" + violations.iterator().next().getMessage());
        }
        // 2. 将数据添加到列表，达到阈值则批量入库
        userList.add(data);
        if (userList.size() >= BATCH_SIZE) {
            batchInsert(); // 批量入库
            userList.clear(); // 清空列表，避免内存占用过高
        }
    }

    /**
     * Excel解析完成后，调用该方法（处理剩余不足批量阈值的数据）
     */
    @Override
    public void doAfterAllAnalysed(AnalysisContext context) {
        // 解析完成后，若还有剩余数据，批量入库
        if (!CollectionUtils.isEmpty(userList)) {
            batchInsert();
            userList.clear();
        }
        log.info("Excel数据解析完成，已全部导入数据库");
    }

    /**
     * 批量插入数据库（将ExcelUserDTO转为SysUser）
     */
    private void batchInsert() {
        // 转换DTO为数据库实体
        List<SysUser> sysUsers = userList.stream().map(dto -> {
            SysUser sysUser = new SysUser();
            BeanUtils.copyProperties(dto, sysUser); // 复制属性（忽略@ExcelIgnore的字段）
            return sysUser;
        }).toList();
        // 调用MyBatis-Plus批量插入方法
        sysUserService.saveBatch(sysUsers);
        log.info("批量插入{}条用户数据到数据库", sysUsers.size());
    }
}

3.2 Mapper与Service层实现（批量入库）

基于MyBatis-Plus简化CRUD操作，无需手动编写SQL，聚焦核心导入功能：

3.2.1 SysUserMapper

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.example.demo.entity.SysUser;
import org.apache.ibatis.annotations.Mapper;

/**
 * 用户Mapper接口（继承BaseMapper，无需编写SQL）
 */
@Mapper
public interface SysUserMapper extends BaseMapper<SysUser> {
}

3.2.2 SysUserService

import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
import com.example.demo.entity.SysUser;
import com.example.demo.mapper.SysUserMapper;
import org.springframework.stereotype.Service;

/**
 * 用户Service层（继承ServiceImpl，自带批量插入、查询等方法）
 */
@Service
public class SysUserService extends ServiceImpl<SysUserMapper, SysUser> {
    // 无需额外编写方法，ServiceImpl已提供saveBatch（批量插入）、list（查询所有）等方法
}

3.3 导入接口设计（Controller）

提供Excel上传接口，接收前端传入的Excel文件，调用监听器解析并批量入库，返回导入结果（成功条数、失败原因），贴合小工具的前端调用需求：

import com.alibaba.excel.EasyExcel;
import com.example.demo.dto.ExcelUserDTO;
import com.example.demo.listener.ExcelUserImportListener;
import com.example.demo.service.SysUserService;
import org.apache.commons.io.FilenameUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;

import java.util.HashMap;
import java.util.Map;

/**
 * Excel导入导出控制器（小工具核心接口）
 */
@RestController
@RequestMapping("/excel")
public class ExcelImportExportController {

    @Autowired
    private SysUserService sysUserService;

    /**
     * Excel批量导入数据库
     * @param file 前端上传的Excel文件（.xlsx、.xls）
     * @return 导入结果（成功条数、提示信息）
     */
    @PostMapping("/import")
    public ResponseEntity<Map<String, Object>> importExcel(@RequestParam("file") MultipartFile file) {
        Map&lt;String, Object&gt; result = new HashMap<>();
        try {
            // 1. 校验文件是否为空
            if (file.isEmpty()) {
                result.put("code", 400);
                result.put("message", "请选择要导入的Excel文件");
                return ResponseEntity.badRequest().body(result);
            }
            // 2. 校验文件格式（仅允许.xlsx、.xls）
            String suffix = FilenameUtils.getExtension(file.getOriginalFilename()).toLowerCase();
            if (!"xlsx".equals(suffix) && !"xls".equals(suffix)) {
                result.put("code", 400);
                result.put("message", "文件格式不合法，仅支持.xlsx、.xls格式");
                return ResponseEntity.badRequest().body(result);
            }
            // 3. 初始化监听器（手动传入Service，因为监听器无法被Spring自动注入）
            ExcelUserImportListener listener = new ExcelUserImportListener(sysUserService);
            // 4. 解析Excel文件，开始导入
            EasyExcel.read(file.getInputStream(), ExcelUserDTO.class, listener)
                    .sheet() // 读取Excel第一个工作表（默认）
                    .headRowNumber(1) // 表头行数（1表示第0行是表头，从第1行开始读取数据）
                    .doRead(); // 开始解析

            // 5. 导入成功，返回结果
            result.put("code", 200);
            result.put("message", "Excel导入成功");
            return ResponseEntity.ok(result);
        } catch (Exception e) {
            // 6. 导入失败，返回错误信息
            result.put("code", 500);
            result.put("message", "Excel导入失败：" + e.getMessage());
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(result);
        }
    }
}

3.4 导入测试（Postman）

1. 准备测试Excel：创建user.xlsx，表头为「用户名、手机号、角色」，填入几条测试数据（如：test1、13800138000、普通用户）；

2. 请求方式：POST，接口地址：http://localhost:8080/excel/import；

3. 请求参数：file选择准备好的Excel文件；

4. 响应结果（成功）：

{
  "code": 200,
  "message": "Excel导入成功"
}

6. 验证：查看数据库sys_user表，可看到Excel中的数据已批量导入，状态自动填充为1，创建时间自动生成。

四、核心实战三：数据导出为Excel文件（小工具核心功能）

Excel导出的核心逻辑：查询数据库中的数据 → 转换为Excel解析实体（ExcelUserDTO） → 通过EasyExcel生成Excel文件 → 响应给前端，支持浏览器直接下载，贴合小工具的日常使用需求。

4.1 导出接口设计（Controller）

无需额外编写监听器，直接调用EasyExcel的write方法，将数据库数据导出为Excel，支持自定义Excel文件名、工作表名称，适配不同场景：

// 在ExcelImportExportController中新增导出接口
import org.springframework.web.bind.annotation.GetMapping;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.net.URLEncoder;
import java.util.List;
import java.util.stream.Collectors;

/**
 * 导出数据库数据为Excel文件（支持浏览器直接下载）
 * @param response Http响应（用于返回Excel文件）
 */
@GetMapping("/export")
public void exportExcel(HttpServletResponse response) throws IOException {
    try {
        // 1. 查询数据库中的所有用户数据（可根据需求添加筛选条件，如查询正常状态的用户）
        List<SysUser> sysUserList = sysUserService.list();
        if (sysUserList.isEmpty()) {
            response.setContentType("application/json;charset=utf-8");
            response.getWriter().write("{\"code\":400,\"message\":\"暂无数据可导出\"}");
            return;
        }

        // 2. 将数据库实体（SysUser）转为Excel解析实体（ExcelUserDTO）
        List<ExcelUserDTO> excelUserList = sysUserList.stream().map(sysUser -> {
            ExcelUserDTO dto = new ExcelUserDTO();
            BeanUtils.copyProperties(sysUser, dto);
            return dto;
        }).collect(Collectors.toList());

        // 3. 配置响应头，让浏览器识别并下载Excel文件
        response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
        response.setCharacterEncoding("utf-8");
        // 自定义Excel文件名（URLEncoder.encode处理中文乱码）
        String fileName = URLEncoder.encode("用户数据导出_" + System.currentTimeMillis(), "UTF-8");
        // 设置响应头，指定文件名和下载方式
        response.setHeader("Content-disposition", "attachment;filename=" + fileName + ".xlsx");

        // 4. 使用EasyExcel生成Excel并响应给前端
        EasyExcel.write(response.getOutputStream(), ExcelUserDTO.class)
                .sheet("用户列表") // Excel工作表名称
                .doWrite(excelUserList); // 写入数据，完成导出
    } catch (Exception e) {
        // 导出失败，返回错误信息
        response.setContentType("application/json;charset=utf-8");
        response.getWriter().write("{\"code\":500,\"message\":\"Excel导出失败：" + e.getMessage() + "\"}");
    }
}

4.2 导出测试（浏览器/Postman）

1. 方式一（浏览器）：直接访问接口地址：http://localhost:8080/excel/export，浏览器会自动下载Excel文件；

2. 方式二（Postman）：发送GET请求，接口地址同上，点击“Save Response” → “Save to a file”，保存Excel文件；

3. 验证：打开下载的Excel文件，可看到数据库中的用户数据已完整导出，表头与ExcelUserDTO注解配置一致，无冗余字段。

关键注意点：1. 响应头配置必须正确，否则浏览器可能无法识别Excel文件，导致下载后无法打开；2. 中文文件名需用URLEncoder.encode处理，避免中文乱码；3. 导出大数据量时，可使用EasyExcel的分批查询+分批写入，避免内存溢出。

五、小工具落地优化（可选，提升体验）

为了让你的小工具更专业、更易用，补充2个实用优化点，可直接集成到代码中：

5.1 导入失败回滚（避免部分数据导入成功）

在Service层添加事务注解，当导入过程中出现异常时，自动回滚所有已插入的数据，保证数据一致性：

// 在SysUserService的批量插入方法上添加事务注解（或在Controller方法上添加）
import org.springframework.transaction.annotation.Transactional;

@Service
public class SysUserService extends ServiceImpl<SysUserMapper, SysUser> {

    // 添加事务注解，出现异常自动回滚
    @Transactional(rollbackFor = Exception.class)
    public boolean saveBatch(List<SysUser> entityList) {
        return super.saveBatch(entityList);
    }
}

5.2 导出数据筛选（适配实际需求）

修改导出接口，支持按条件筛选导出（如按角色、状态筛选），让小工具更灵活：

// 新增带筛选条件的导出接口
@GetMapping("/export/filter")
public void exportExcelByFilter(
        @RequestParam(required = false) String role, // 按角色筛选
        @RequestParam(required = false) Integer status, // 按状态筛选
        HttpServletResponse response) throws IOException {
    try {
        // 构建查询条件（MyBatis-Plus的条件构造器）
        QueryWrapper<SysUser&gt; queryWrapper = new QueryWrapper<>();
        if (role != null && !role.isEmpty()) {
            queryWrapper.eq("role", role);
        }
        if (status != null) {
            queryWrapper.eq("status", status);
        }
        // 按条件查询数据
        List<SysUser> sysUserList = sysUserService.list(queryWrapper);
        // 后续逻辑与普通导出一致（转换DTO、生成Excel）
        // ...（省略重复代码，与exportExcel方法一致）
    } catch (Exception e) {
        // 异常处理
        response.setContentType("application/json;charset=utf-8");
        response.getWriter().write("{\"code\":500,\"message\":\"Excel导出失败：" + e.getMessage() + "\"}");
    }
}

六、常见问题与解决方案（小工具落地避坑）

1. Excel导入时，提示“监听器中Service为null”？

   解决方案：EasyExcel监听器不能被Spring自动注入（生命周期问题），需通过构造方法手动传入Service，如new ExcelUserImportListener(sysUserService)。
   

2. 导出Excel后，打开提示“文件损坏”？

   解决方案：① 检查响应头配置是否正确（Content-Type是否为application/vnd.openxmlformats-officedocument.spreadsheetml.sheet）；② 确保EasyExcel的write方法正常执行，无异常中断；③ 避免在导出过程中关闭响应流。
   

3. 导入时，手机号转为科学计数法？

   解决方案：在ExcelUserDTO的phone字段添加@NumberFormat("#")注解，或在Excel中将手机号列设置为“文本格式”。
   

4. 大数据量导入时，内存溢出？

   解决方案：① 调整监听器中的BATCH_SIZE（如100、200），减少单次内存占用；② 开启EasyExcel的分批读取，通过.headRowNumber(1).batchRead(100)配置；③ 避免在监听器中存储过多数据。
   

5. Excel表头与实体类注解不匹配，解析无数据？

   解决方案：确保@ExcelProperty的value与Excel表头完全一致（大小写、空格、特殊字符都要匹配），或通过index指定列索引（更稳妥）。
   

七、总结（小工具落地总结）

本文承接文件上传的基础，完整落地了Spring Boot + EasyExcel的Excel导入导出核心功能，精准贴合小工具开发需求，代码可直接复制复用，核心要点总结：

• 依赖引入：仅需引入EasyExcel核心依赖，搭配MyBatis-Plus，简化开发，轻量高效；

• 实体设计：通过EasyExcel注解绑定Excel表头，关联数据库实体，实现“Excel→实体→数据库”无缝映射；

• 批量导入：自定义监听器处理解析、校验、批量入库，事务回滚保证数据一致性；

• 数据导出：配置响应头，直接将数据库数据导出为Excel，支持浏览器下载和条件筛选。

掌握本文内容后，你可以直接将这些代码集成到自己的小工具中，快速实现Excel导入导出核心功能，精准满足用户数据管理需求，助力小工具引流转化。后续可进一步扩展：模板下载（提供Excel导入模板）、导入导出进度显示、异常日志记录等，让小工具更专业、更易用。