Spring Boot + EasyExcel 实现 Excel 导入导出

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<String, Object> 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()
                    .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 导入成功"}

5. 验证：查看数据库 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("用户列表")
                .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> 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() + "\"}");
    }
}

六、常见问题与解决方案

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

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

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

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

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

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

导出 Excel 后，打开提示'文件损坏'？

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

Excel 导入时，提示'监听器中 Service 为 null'？

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

七、总结

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

• 依赖引入：仅需引入 EasyExcel 核心依赖，搭配 MyBatis-Plus，简化开发，轻量高效；
• 实体设计：通过 EasyExcel 注解绑定 Excel 表头，关联数据库实体，实现'Excel→实体→数据库'无缝映射；
• 批量导入：自定义监听器处理解析、校验、批量入库，事务回滚保证数据一致性；
• 数据导出：配置响应头，直接将数据库数据导出为 Excel，支持浏览器下载和条件筛选。

掌握本文内容后，你可以直接将这些代码集成到自己的项目中，快速实现 Excel 导入导出核心功能，满足用户数据管理需求。后续可进一步扩展：模板下载（提供 Excel 导入模板）、导入导出进度显示、异常日志记录等，提升系统易用性。