做了多年若依开发导入功能算是我被问得最多的模块之一。很多人拿着若依框架做管理系统业务表建好了列表页出来了结果一到“导入Excel”这一步就卡住要么是前端不知道用什么组件要么是后端写出来的导入逻辑漏洞百出要么是导入几万条数据直接把服务干崩。这篇我系统梳理一下若依导入功能从零到一的完整落地过程前后端都讲思路、代码、坑点一次说清楚适合刚接触若依的同学照着抄也适合写了一段时间但想优化导入逻辑的老手对照检查。1. 导入功能整体设计与前置准备1.1 若依导入功能解决了什么问题若依RuoYi是基于Spring Boot的快速开发脚手架前后端分离版、微服务版、单体版都有但不管哪个版本导入功能解决的业务痛点是一致的让用户通过Excel批量录入数据而不是在页面上一条一条手工填。典型的场景比如用户批量导入、学生信息导入、商品库存导入、考勤记录导入一个Excel表格几百上千行如果靠手敲录入慢而且容易出错导入功能就是把这些线下表格一键变成线上数据。若依框架本身其实已经封装了比较完善的Excel处理工具类ExcelUtil基于Apache POI实现注解式解析。也就是说你在实体字段上加一个Excel注解框架就能自动帮你把Excel的列映射成Java对象的属性不需要像传统方式那样写一堆row.getCell(0).getStringCellValue()之类的样板代码。这也是若依导入功能的底层逻辑注解驱动解析。框架把“读Excel、写Excel、校验Excel格式”这些重复劳动封装好了我们只需要关心业务校验和落库逻辑。1.2 环境与版本选型我用的是若依前后端分离版RuoYi-Vue后端Spring Boot 2.5.x前端Vue 2 Element UI数据库MySQL 8.0。如果你是若依微服务版RuoYi-Cloud或者单体版RuoYi导入功能的实现思路完全一致无非是模块路径和依赖管理方式稍微调整。我建议新手直接用RuoYi-Vue这个版本它结构清晰前端是成熟的Vue生态后端模块划分也直观导入功能在这个版本的文档和社区案例最多遇到问题容易搜到解决方案。这里多说一句版本问题。有人问我“若依的Plus版本”或者“芋道源码版”能不能用同样的教程我的回答是核心逻辑一样但工具类包名可能有差异。比如芋道yudao框架在若依基础上做了很多增强ExcelUtil的位置和API有变化但POI的底层机制不变。所以你在看这篇教程的时候重点理解“思路和流程”再对照自己项目里的工具类路径去适配。1.3 准备工作建表、加依赖导入功能既然是批量写数据库那肯定先得有张业务表。我这里用一个常见的“学生信息导入”来演示表结构如下CREATE TABLE student ( id BIGINT AUTO_INCREMENT PRIMARY KEY, student_no VARCHAR(32) NOT NULL COMMENT 学号, name VARCHAR(50) NOT NULL COMMENT 姓名, gender CHAR(1) DEFAULT 0 COMMENT 性别0男 1女 2未知, birthday DATE DEFAULT NULL COMMENT 出生日期, phone VARCHAR(20) DEFAULT NULL COMMENT 手机号, email VARCHAR(100) DEFAULT NULL COMMENT 邮箱, grade VARCHAR(20) DEFAULT NULL COMMENT 班级, status CHAR(1) DEFAULT 0 COMMENT 状态0正常 1停用, create_by VARCHAR(64) DEFAULT , create_time DATETIME DEFAULT CURRENT_TIMESTAMP, update_by VARCHAR(64) DEFAULT , update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, remark VARCHAR(500) DEFAULT NULL COMMENT 备注 ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT学生信息表;表建好之后确认后端项目的pom.xml里有POI依赖。若依框架默认在ruoyi-common模块里已经引入了POI如果你自己新建了一个非若依标准的模块需要手动加上!-- Apache POI -- dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version4.1.2/version /dependency还要确保前端项目安装了依赖RuoYi-Vue的前端一般不需要额外安装上传组件因为Element UI自带el-upload。我们直接用就行。2. 后端导入核心实现从Controller到Service2.1 实体类与Excel注解配置若依导入的精髓就在Excel注解。这个注解能告诉ExcelUtilExcel的某一列对应Java对象的哪个字段。我们写一个学生实体类继承BaseEntitypublic class Student extends BaseEntity { private static final long serialVersionUID 1L; /** 主键 */ private Long id; /** 学号 */ Excel(name 学号, width 20, prompt 请输入学号) private String studentNo; /** 姓名 */ Excel(name 姓名, width 30) private String name; /** 性别 */ Excel(name 性别, readConverterExp 0男,1女,2未知, prompt 性别只能填0、1或2) private String gender; /** 出生日期 */ Excel(name 出生日期, width 20, dateFormat yyyy-MM-dd) private Date birthday; /** 手机号 */ Excel(name 手机号, width 20) private String phone; /** 邮箱 */ Excel(name 邮箱, width 30) private String email; /** 班级 */ Excel(name 班级, width 20) private String grade; /** 状态 */ Excel(name 状态, readConverterExp 0正常,1停用) private String status; /** 备注 */ Excel(name 备注, width 30) private String remark; // getter、setter 省略 }Excel注解里几个常用属性我解释一下nameExcel表头名称必须和Excel模板里的表头完全一致。width列宽。prompt导出模板时给该列生成批注提示方便填表人知道格式要求。dateFormat日期格式化默认是yyyy-MM-dd如果你的日期格式是yyyy/MM/dd或者带了时分秒要按实际情况改。readConverterExp读写转换表达式格式是“数据库值显示文本”。比如性别字段数据库存0但Excel里如果填了“男”靠这个配置就能自动把“男”转成0。注意如果不加这个属性用户填“男”就会解析失败。这里要注意一个细节Excel注解加载到字段上之后ExcelUtil是通过反射读取字段名和注解来映射数据的所以字段名不要乱改尤其是你预计别人会拿这个类做导入导出时表头字段和Java字段的对应关系一定要稳定。2.2 ExcelUtil的导入机制若依封装的ExcelUtilT是一个泛型工具类核心方法有两个importExcel(InputStream is)从输入流读Excel返回一个ListT。getMessage()获取导入过程中的校验提示信息比如某些单元格格式不对会被记录到这里。它的底层逻辑是先用POI把Excel文件解析成一个Workbook拿到第一个Sheet遍历每一行根据实体的Excel注解找到表头对应的字段再把单元格值转成对应Java类型。遇到readConverterExp配置的字段会用逗号分隔解析映射表达式把Excel文本转成数据库值或者反过来导出。我来写一下Controller层的调用代码RestController RequestMapping(/system/student) public class StudentController extends BaseController { Autowired private IStudentService studentService; /** * 导入学生数据 */ PostMapping(/importData) public AjaxResult importData(MultipartFile file, boolean updateSupport) throws Exception { ExcelUtilStudent util new ExcelUtilStudent(Student.class); ListStudent studentList util.importExcel(file.getInputStream()); String message studentService.importStudent(studentList, updateSupport); return AjaxResult.success(message); } /** * 下载导入模板 */ PostMapping(/importTemplate) public AjaxResult importTemplate() { ExcelUtilStudent util new ExcelUtilStudent(Student.class); return util.importTemplateExcel(学生数据); } }这里有两个关键点第一importData方法接收的MultipartFile file前端el-upload在提交文件时默认参数名就是file如果你改了参数名前端也要对应改。第二updateSupport这个参数很实用它表示“是否支持更新已存在的数据”。如果设为false导入时遇到学号已存在的记录会跳过并在消息里提示“学号xxx已存在”如果设为true则覆盖更新。这个逻辑一般放在Service层处理。2.3 Service层业务逻辑与校验Service层是导入功能的核心因为数据校验和落库都在这层做。我先写一个标准的实现Service public class StudentServiceImpl implements IStudentService { Autowired private StudentMapper studentMapper; Override Transactional(rollbackFor Exception.class) public String importStudent(ListStudent studentList, boolean updateSupport) { if (StringUtils.isNull(studentList) || studentList.size() 0) { throw new ServiceException(导入学生数据不能为空); } int successNum 0; int failureNum 0; StringBuilder successMsg new StringBuilder(); StringBuilder failureMsg new StringBuilder(); for (Student student : studentList) { try { // 根据学号查重 Student checkStudent studentMapper.selectStudentByStudentNo(student.getStudentNo()); if (checkStudent null) { student.setCreateBy(getUsername()); studentMapper.insertStudent(student); successNum; continue; } if (updateSupport) { student.setId(checkStudent.getId()); student.setUpdateBy(getUsername()); studentMapper.updateStudent(student); successNum; } else { failureNum; failureMsg.append(br/).append(failureNum).append(、学号 ).append(student.getStudentNo()).append( 已存在); } } catch (Exception e) { failureNum; String msg br/ failureNum 、学号 student.getStudentNo() 导入失败; failureMsg.append(msg).append(e.getMessage()); log.error(导入学生数据异常, e); } } if (failureNum 0) { failureMsg.insert(0, 很抱歉导入失败共 failureNum 条数据格式不正确错误如下); throw new ServiceException(failureMsg.toString()); } else { successMsg.insert(0, 恭喜您数据已全部导入成功共 successNum 条数据如下); } return successMsg.toString(); } }这段代码有几个设计心得值得说一是逐条校验而不是一把梭全插。很多新手把studentMapper.insertStudent放在循环外面一次性批量插入看起来性能好但一旦中间某条数据有问题整个事务回滚你连哪条数据错了都不知道。我在生产环境里踩过这个坑后来改成逐条处理每一条的成功失败都记录用户拿到提示就知道是第几行、哪个学号出错了。二是用学号做唯一性校验。业务表的唯一字段通常是导入去重的依据。如果你的业务没有唯一标识建议在导入前先让用户下载模板填好或者在数据库层面加唯一索引兜底。否则重复数据会越来越多后面查数据、统计数据都会出问题。三是事务回滚与错误提示的权衡。这里要注意当有失败数据时我直接用throw new ServiceException把事务整体回滚了但返回的错误信息是拼好的字符串。有同学问“我想让成功的插进去失败的不插”那就可以不抛异常而是把成功和失败的结果都返回给前端展示。两种策略各有适用场景如果业务允许部分成功就不要在Service层抛异常而是组装一个结果对象返回。2.4 数据导入模板下载模板下载在若依里一行代码就能搞定就是Controller里的importTemplate方法。前端调用// 下载模板 handleImportTemplate() { this.download(system/student/importTemplate, {}, student_template_${new Date().getTime()}.xlsx); }若依前端封装了一个download方法会拼接请求地址、带上token、处理blob下载。这个方法在很多页面里都用得到比手写axiosURL.createObjectURL省事很多。如果你在自己项目里写可以这样import { download } from /utils/request;模板生成后Excel注解里的prompt会变成Excel的单元格批注填表人鼠标悬停在表头上就能看到提示。这个细节很实用尤其是用户不懂“性别填0还是填1”这种问题时批注能大幅降低沟通成本。3. 前端导入交互实现3.1 页面按钮与文件上传组件若依前端页面我在“学生管理”菜单里加上了导入按钮、模板下载按钮交互流程是点击“导入” - 弹出对话框 - 选择Excel文件 - 点击确定上传 - 显示导入结果。核心代码template div el-button typesuccess plain iconel-icon-download clickhandleImportTemplate下载模板/el-button el-button typeprimary plain iconel-icon-upload2 clickopenImportDialog导入数据/el-button el-dialog title导入学生数据 :visible.syncimportOpen width500px append-to-body el-form refimportForm :modelimportForm label-width100px el-form-item label导入文件 propfile el-upload refupload :limit1 accept.xlsx, .xls :auto-uploadfalse :on-changehandleFileChange :on-removehandleFileRemove action# drag i classel-icon-upload/i div classel-upload__text将文件拖到此处或em点击上传/em/div div classel-upload__tip slottip仅支持 .xlsx / .xls 文件且不超过 10MB/div /el-upload /el-form-item el-form-item label是否更新 el-checkbox v-modelimportForm.updateSupport若学号已存在则更新/el-checkbox /el-form-item /el-form span slotfooter classdialog-footer el-button clickimportOpen false取 消/el-button el-button typeprimary :loadingimportLoading clickhandleImport确 定/el-button /span /el-dialog /div /templateel-upload这里用的是手动上传模式因为我们要在用户选好文件、点击“确定”后再提交而不是选完就自动上传。action#只是为了满足组件必填属性实际上传走的是自定义方法。3.2 事件处理与提交逻辑export default { data() { return { importOpen: false, importLoading: false, importForm: { updateSupport: false }, fileList: [] }; }, methods: { handleFileChange(file, fileList) { this.fileList fileList; }, handleFileRemove(file, fileList) { this.fileList fileList; }, handleImport() { if (this.fileList.length 0) { this.$modal.msgWarning(请先选择要导入的文件); return; } const formData new FormData(); formData.append(file, this.fileList[0].raw); formData.append(updateSupport, this.importForm.updateSupport); this.importLoading true; // 用你项目里封装好的post请求方法 request({ url: /system/student/importData, method: post, data: formData, headers: { Content-Type: multipart/form-data } }).then(response { this.$modal.msgSuccess(response.msg); this.importOpen false; this.getList(); }).finally(() { this.importLoading false; }); } } };有几个细节我特别提醒文件名与参数名。formData.append(file, this.fileList[0].raw)这个file必须和后端MultipartFile file参数名一致。Element UI的file.raw才是原始File对象file本身是封装过的直接append会出错。Content-Type。如果你用axios很多封装会自动根据FormData类型设置multipart/form-data但如果你的请求库默认不自动设置一定要显式写清楚否则后端拿到的文件流不完整。结果提示。若依的$modal.msgSuccess底层就是Element UI的Message组件。后端返回的AjaxResult.success(message)会把message塞到msg字段前端直接读response.msg就能展示。4. 实操过程与完整代码示例4.1 组装一个可直接运行的导入模块为了让大家少走弯路我把一个完整的学生导入模块代码整理如下从Mapper到Controller全部给出来照着抄就能跑通。StudentMapper.javapublic interface StudentMapper { Student selectStudentByStudentNo(String studentNo); int insertStudent(Student student); int updateStudent(Student student); ListStudent selectStudentList(Student student); }StudentMapper.xmlselect idselectStudentByStudentNo parameterTypestring resultMapStudentResult select id, student_no, name, gender, birthday, phone, email, grade, status, remark from student where student_no #{studentNo} /select insert idinsertStudent parameterTypeStudent useGeneratedKeystrue keyPropertyid insert into student( student_no, name, gender, birthday, phone, email, grade, status, create_by, create_time, remark ) values ( #{studentNo}, #{name}, #{gender}, #{birthday}, #{phone}, #{email}, #{grade}, #{status}, #{createBy}, sysdate(), #{remark} ) /insert update idupdateStudent parameterTypeStudent update student set if testname ! null and name ! name #{name},/if if testgender ! nullgender #{gender},/if if testbirthday ! nullbirthday #{birthday},/if if testphone ! nullphone #{phone},/if if testemail ! nullemail #{email},/if if testgrade ! nullgrade #{grade},/if if teststatus ! nullstatus #{status},/if if testremark ! nullremark #{remark},/if if testupdateBy ! null and updateBy ! update_by #{updateBy},/if update_time sysdate() /set where id #{id} /updateXML映射文件里selectStudentByStudentNo用学号精确查记录这个查询在导入循环里会被高频调用建议在student_no字段上建索引。如果数据量大到几万条逐条查询的性能瓶颈会出现后面第5节我再讲优化方案。/** * 学生Service接口 */ public interface IStudentService { String importStudent(ListStudent studentList, boolean updateSupport); }Controller代码前面已经有我这里补一个带日志和权限控制的版本RestController RequestMapping(/system/student) public class StudentController extends BaseController { Autowired private IStudentService studentService; Log(title 学生管理, businessType BusinessType.IMPORT) PreAuthorize(ss.hasPermi(system:student:import)) PostMapping(/importData) public AjaxResult importData(MultipartFile file, boolean updateSupport) throws Exception { ExcelUtilStudent util new ExcelUtilStudent(Student.class); ListStudent studentList util.importExcel(file.getInputStream()); String message studentService.importStudent(studentList, updateSupport); return AjaxResult.success(message); } Log(title 学生管理, businessType BusinessType.IMPORT) PreAuthorize(ss.hasPermi(system:student:import)) PostMapping(/importTemplate) public AjaxResult importTemplate() { ExcelUtilStudent util new ExcelUtilStudent(Student.class); return util.importTemplateExcel(学生数据); } }加上PreAuthorize和后端Log一是权限可控不是谁都能导入二是导入操作会被记入操作日志方便追溯。这是若依这套脚手架最有价值的地方业务代码只管业务日志、权限、校验这些横切能力都被框架吸收掉了。4.2 使用测试从下载模板到导入成功我在本地实测一遍完整流程给大家描述一下正常路径第一步启动若依后端和前端登录系统进入“学生管理”页面点击“下载模板”得到一个student_template_20250120103025.xlsx文件打开后表头是学号、姓名、性别、出生日期、手机号、邮箱、班级、状态、备注性别单元格有批注提示“性别只能填0、1或2”。第二步在模板里填几行测试数据注意学号不能重复出生日期格式保持yyyy-MM-dd状态填0或1。保存后用导入弹窗选择该文件勾选“若学号已存在则更新”点击确定。第三步页面提示“恭喜您数据已全部导入成功共 5 条数据如下”列表刷新5条记录全部显示。第四步我再故意填一个重复学号、一个日期格式错误的行测试失败场景。这次不勾更新点击确定后页面报错“很抱歉导入失败共 2 条数据格式不正确错误如下1、学号 20240102 已存在2、出生日期格式错误”。同时由于Service层抛了异常整个事务回滚刚才那5条本应正常插入的数据也全部没进去。这里就体现出设计上的取舍了。如果你希望部分成功部分失败而不是整体回滚可以调整Service实现不在失败时抛出异常而是把错误消息作为结果返回。具体怎么选要看业务需求。比如批量初始化数据通常要求要么全成要么全不成而日常补录数据最好是成功的先救回来失败的单独提示用户手工处理。4.3 大数据量导入的性能优化前面提过逐条查、逐条插在数据量小的时候没问题但当你拿一个5万行的Excel来导入这种写法会非常慢而且对数据库压力很大。我实测过逐条插入5万条数据需要几分钟用户根本等不起。这时候就要优化。常见的优化策略有三种第一种分批批量插入。不要逐条insert而是每攒500条或者1000条用MyBatis的foreach一次性插入。配合MySQL的JDBC批量提交性能能提升一个数量级。示例// 每500条批量插入一次 ListListStudent batchList ListUtils.partition(studentList, 500); for (ListStudent batch : batchList) { studentMapper.batchInsertStudent(batch); }XML里的batchInsertStudentinsert idbatchInsertStudent parameterTypelist insert into student( student_no, name, gender, birthday, phone, email, grade, status, create_by, create_time, remark ) values foreach collectionlist itemitem separator, ( #{item.studentNo}, #{item.name}, #{item.gender}, #{item.birthday}, #{item.phone}, #{item.email}, #{item.grade}, #{item.status}, #{item.createBy}, sysdate(), #{item.remark} ) /foreach /insert第二种预校验学号去重。逐条查selectStudentByStudentNo最大的开销是每次查询都走一次数据库。优化办法是先把所有要导入的学号收集到一个List里一次性查出来哪些已存在内存里构建一个Set后续直接通过Set.contains判断不再和数据库交互。ListString studentNos studentList.stream().map(Student::getStudentNo).collect(Collectors.toList()); SetString existSet studentMapper.selectStudentNoList(studentNos).stream().collect(Collectors.toSet()); // 循环里判断 existSet.contains(student.getStudentNo())第三种多线程导入。这是压轴方案适合几十万条级别的导入。把Excel解析出来的List按固定大小切分成若干份用线程池并发执行批量插入。但要注意并发插入对数据库连接池要求高而且事务控制更复杂不要为了炫技而滥用。我的经验是数据量5万以下用分批批量插入就够了超过10万再考虑多线程。4.4 前端上传组件的属性细节这里把Element UI的el-upload几个易错属性展开讲一下。action是必填属性很多新手直接填了后端上传地址结果发现还没点确定文件就传上去了。如果你要做“选择文件-点击确定再上传”的流程务必设置:auto-uploadfalse并且用on-change把文件暂存到前端变量里。limit控制最大文件数量这里设置1就是只允许选一个文件。同时要搭配on-exceed事件给用户提示否则超过限制时组件会静默忽略体验不好handleExceed(files, fileList) { this.$modal.msgWarning(只能选择一个Excel文件请先移除已选文件); }accept属性用来过滤文件选择器里的可见文件类型.xlsx, .xls。注意这个属性在不同浏览器上行为不完全一致只是辅助过滤后端的文件类型校验不能省。后端的校验我给一个参考if (file null || file.isEmpty()) { throw new ServiceException(上传文件不能为空); } // 校验文件后缀 String filename file.getOriginalFilename(); if (!filename.endsWith(.xlsx) !filename.endsWith(.xls)) { throw new ServiceException(仅支持 .xlsx 或 .xls 格式的Excel文件); }另外若依默认上传文件大小限制一般在application.yml里的spring.servlet.multipart.max-file-size配置默认是10MB。如果业务场景要导入大文件记得调大spring: servlet: multipart: max-file-size: 50MB max-request-size: 50MB4.5 导入错误信息如何落到文件里有同学问几百条数据导入失败时页面上报错信息显示不全能不能把错误信息生成一个文件让用户下载查看若依的ExcelUtil.importExcel本身只能返回解析后的List错误信息都放在getMessage()里。要做“错误文件回传”一般两个思路思路一是前端把response.msg的完整错误文本展示在一个可滚动的对话框里适合几十条以内的错误。再多了这个方案体验也不好。思路二是后端把每行数据连同错误原因写成一个新的Excel文件上传到服务器返回文件路径前端拿到路径后提供下载。这个方案适合错误数据量大的场景但工作量大一些需要额外写一个导出带错误标注Excel的方法。我是这样做的在导入失败时把带有错误原因的行收集到一个ListStudentExcelError里利用若依ExcelUtil的导出能力生成文件返回URL。前端在导入结果里显示“下载错误明细”按钮用户点开就能看到哪一行、哪个字段、因为什么原因失败非常直观。5. 常见问题与排查技巧实录5.1 导入乱码问题乱码大多数是文件编码问题。Excel的.xlsx本质是个zip包内部XML都是UTF-8一般不会乱码。乱码常见于旧版.xls文件或者用户在Windows上用WPS保存的“CSV UTF-8”实际是GBK编码的文件。若依的ExcelUtil底层用POI解析对.xlsx和.xls都能处理但CSV不在POI的默认支持范围内。所以我的建议是统一模板格式为.xlsx并在前端accept里只放.xlsx和.xls基本能规避乱码。如果确实遇到从其他系统导出的Excel内容正常、但若依解析出来中文乱码先检查POI版本旧版POI对某些Excel版本兼容性差再检查文件是不是真的Excel有些用户会把数据复制到文本文件里然后强行改后缀这种文件POI根本没法定为Excel解析出来全是null。5.2 空行和格式问题导致解析失败用户拿到的模板里可能有多余的空行或者某一行中间缺了几列这些都会导致导入结果和预期不一致。若依的ExcelUtil默认会跳过全空的行但如果一行里某个单元格有空格POI读到的是空白字符串而不是null这就会让数据校验变得不可控。我处理这类问题的经验是引入StringUtils.trim清洗或者直接在Service层把字符串字段做统一处理student.setName(StringUtils.trim(student.getName())); student.setPhone(StringUtils.trim(student.getPhone()));日期格式也是重灾区。用户习惯在Excel里填2024-1-1而不是2024-01-01ExcelUtil解析时如果严格按yyyy-MM-dd去格式化就会报错。我在实战中会把dateFormat设得宽容一些同时在模板批注里明确写出“日期格式必须是yyyy-MM-dd例如2024-01-05”。5.3 POI解析大文件内存溢出POI解析Excel时Workbook对象会把整个文件加载进内存一个10MB的Excel解压后可能是100MB甚至更多如果并发上来JVM堆很容易被撑爆。遇到大文件或者高并发导入建议用POI的SXSSFWorkbook这是写大Excel用的或者针对读取场景用XSSFReader流式解析。但若依的ExcelUtil默认用的还是传统的XSSFWorkbook小项目够用真要处理超大文件就得自定义导入逻辑了。这里提供一个下策中的上策限制单个文件大小和总行数。前端限制10MB后端也做同样的判断超过直接拒绝。对于绝大多数业务管理系统来说单次导入几千行足够了没必要非去挑战几十万行的场景。5.4 事务回滚导致“插入成功但查不到”有朋友遇到导入时控制台打印“插入成功”但列表里查不到数据怀疑是缓存问题。其实大概率是事务回滚了。回滚的原因可能是导入循环中某一条数据违反了数据库约束比如唯一索引冲突、非空字段为空Spring事务检测到异常后把整个insert回滚了。排查思路很简单把异常堆栈打出来看或者先只导入一条数据验证基本链路再逐步增加数据量。我在代码里给每条导入记录都加了try-catch这样至少能把失败的原因拼到返回消息里用户能直观看到是哪条数据、什么问题而不是什么都不显示。5.5 若依导入时报“error adding module to project: null”这个报错不是运行时导入功能的问题而是项目导入IDE时出现的。多半是Maven依赖的ruoyi-common模块没有正常解析或者本机Maven仓库缺包。解决办法是右键项目 - Maven - Reload Project然后检查pom.xml里是否有parent坐标写错。如果是在IDEA里打开若依全量项目还报这个错先把所有模块删掉重新导入再清一下IDEA缓存File - Invalidate Caches。5.6 生成模板时表头不显示中文用ExcelUtil.importTemplateExcel(学生数据)生成模板时表头应该自动显示为Excel注解里name指定的中文。如果表头空白最常见原因是实体字段的Excel注解写错了比如注解加在getter方法上而不是字段上。若依的ExcelUtil同时支持字段和getter但如果同一字段既在getter加又在字段加解析优先级会出问题。我建议规范统一全部加在字段上。5.7 启用readConverterExp后数据库值反了readConverterExp 0男,1女的意思是Excel里填“男”框架自动转成0如果填“女”自动转成1。如果你发现导入的数据和填的值正好反了肯定是表达式写反了。这个属性在导入、导出时会同时生效导出时数据库0会转成“男”写入Excel导入时Excel“男”会转成0存库。如果只想要导出转换而导入不转换可以再研究下Excel里的combo和edit属性不过大部分场景下统一用readConverterExp就够了。跟着这套流程走下来一个能跑通、能上线、能扛住日常业务量的导入功能就完整落地了。我个人在实际开发中的体会是导入功能看似简单但真正做得让人省心核心不在“把Excel读进来”而在“错误提示是否精准、边界情况是否兜住、数据量上来之后是否还能稳定”。若依把Excel解析这层最脏最累的活封装好了我们只需要在业务校验和异常捕获上多花心思。最后再分享一个小技巧上线前不管多急一定找用户拿一份真实业务Excel来测模板是模板真实数据里永远有意想不到的脏数据提前见过了上线后才不会手忙脚乱。