SpringBoot+Vue3 数据导入设计：从 Excel 校验到批次处理、错误回执与安全重试

🌐 文档地址：https://ruoyioffice.com
 👇 文章底部获取源码和演示地址 👇
 💬 ：17156169080（获取产品咨询）

一次员工资料导入里，可能同时出现新增员工、更新部门、重复工号、无效组织和格式错误。最糟糕的导入结果不是全部失败，而是成功了一半，却没有告诉操作人员哪几行成功、哪几行失败、失败后能不能只修正失败行。

▲ Excel 行进入校验工作台，合格数据和失败数据分开处理，错误回执保留原行号与失败原因。

本文不重复 Excel 库的注解教程，而是从企业后台的业务可靠性出发，讨论一次导入如何成为可追踪的数据入口。

一、导入按钮背后至少有五种语义

用户看到的是“选择文件、点击导入”。
 系统实际需要确定：

1. 哪一行代表一条业务数据；
2. 哪个字段是唯一身份；
3. 已存在记录是更新还是拒绝；
4. 部分成功时事务边界在哪里；
5. 失败后如何反馈和重试。

1.1 导入不是数据库批量 INSERT

数据库写入只回答“这条记录能不能写进去”。
 导入还要回答“这条 Excel 行是否符合业务规则、应该写到哪个对象、失败后如何让人修复”。

因此，解析、校验、分流、写入和回执最好有清晰阶段。
 不一定要拆成五个微服务，但代码和结果结构要能区分它们。

1.2 先保留原行，再做标准化

错误提示中的“第 18 行组织不存在”依赖原始行号。
 如果解析后立即丢弃空行、排序或合并，回执就无法准确定位原始内容。

建议保存原行号和关键原始值，标准化后的字段单独保存。

二、Vue3 导入弹窗应该让用户知道会发生什么

▲ 导入弹窗应同时说明模板、覆盖策略和结果，而不是只提供一个上传按钮。

当前前端导入组件已经抽象了模板下载、导入请求、更新支持和失败映射等结构。
 它可以被用户、角色、部门和员工等多个模块复用。

2.1 更新支持必须写清楚

updateSupport 不是一个纯技术开关。
 它决定已存在唯一键时是否允许覆盖。

如果允许更新，页面必须说明：

• 以什么字段判断存在；
• 哪些列会被覆盖；
• 空值是清空还是忽略；
• 组织、角色和岗位是否需要额外权限；
• 更新失败是否回滚该行。

2.2 结果结构要面向人阅读

前端类型中可以看到 createKeys、updateKeys 和 failureMap 等结果字段。
 它们把成功新增、成功更新和失败原因分开，适合在弹窗中展示摘要与详情。
 下面的类型在现有结果字段上增加批次与计数字段，属于扩展示意，不是组件原类型的逐字摘录。

export interface ImportExcelResult {  batchId?: string;  status?: 'PRECHECK' | 'RUNNING' | 'PARTIAL' | 'DONE';  totalRows?: number;  successCount?: number;  skipCount?: number;  failureCount?: number;  message?: string;  createKeys?: string[];  updateKeys?: string[];  failureMap?: Record<string, string>;  createUsernames?: string[];  updateUsernames?: string[];  failureUsernames?: Record<string, string>;}

这组结构仍有扩展空间。
 如果要支持批次重试，建议在结果中增加批次 ID、原始行号和目标记录 ID，而不是只返回一串用户名。

2.3 工作表、列头和字典要显式约定

一个 Excel 文件可能包含多个工作表。
 如果系统只读取第一个工作表，用户把说明页放在最前面就会导致整批导入失败。
 模板应明确工作表名称、是否允许新增工作表、列头是否允许别名以及空白行如何处理。

字典值也不能只依赖中文显示名。
 例如员工状态“在职”可能对应 1，组织类型“部门”可能对应 DEPT。
 模板可以同时展示编码和说明，服务端以编码作为写入值，以显示名作为辅助提示。

2.4 跨行关系需要第二阶段校验

同一文件中可能先出现员工，再出现员工负责的岗位或组织。
 单行校验时目标对象尚未落库，不能简单认为引用不存在。
 可以先构建文件内的临时索引，再执行跨行关系校验，最后决定新增顺序。

跨行校验失败时，错误回执要指出关联行号。
 例如“第 18 行岗位负责人引用第 42 行员工，但第 42 行工号重复”，比单独提示“员工不存在”更容易修复。

2.5 预检结果不是永久承诺

预检完成后，其他管理员可能停用组织、修改岗位或占用同一工号。
 正式写入前应重新检查关键唯一键和引用对象，并把变化记录为“预检后数据发生变化”。
 不要为了保持预检结果而覆盖后来已经完成的人工修改。

2.6 只允许上传 xls/xlsx 不等于完成校验

文件扩展名只是第一道门。
 服务端还需要校验 MIME、文件大小、工作表名称、列头、公式和宏风险。
 对于公开上传接口，还要考虑恶意文件和存储路径安全。

三、行级校验：把错误留在离它最近的地方

▲ 大批量导入需要显示进度和结果边界；后台任务完成不等于业务数据全部正确。

▲ 工作台页面将模板、批次和进度放在同一上下文中，便于操作人员确认当前处理阶段。

行级校验建议分三层：

例如员工行里的组织编码不存在，属于行级错误。
 同一个工号在同一文件出现两次，属于批次内重复。
 导入 10 万行超过租户配额，属于批次级错误。

3.1 错误消息要告诉人怎么改

“数据不合法”无法指导修复。
 更好的消息包含：

• 原始行号；
• 列名；
• 原值；
• 失败原因；
• 建议动作。

例如：“第 18 行，所属组织=研发一组?，组织编码不存在，请改为已启用组织编码”。

3.2 唯一键需要显式选择

员工可能以工号唯一，也可能以外部系统 ID 唯一。
 角色可能以角色标识唯一，部门可能以组织编码唯一。
 同一个模块不应让每次导入都临时猜唯一键。

模板下载和接口文档应把唯一键写出来，结果回执也应返回它。

四、新增、更新与失败要走不同路径

4.1 新增不是“数据库不存在就插入”

新增前还要检查组织、岗位、角色、租户和默认值。
 如果关联对象不存在，应该让该行失败并回执原因，而不是悄悄创建一个同名组织。

4.2 更新不应覆盖所有字段

员工导入更新时，姓名、手机号、岗位、状态的覆盖策略可能不同。
 有些字段由 HR 导入维护，有些字段由员工自助或审批流程维护。

建议为导入类型定义可更新字段白名单。
 空值是否覆盖也应单独配置。

4.3 部分成功要选择事务粒度

整批事务的优点是结果一致，缺点是一个错误可能让整批回滚。
 逐行事务能提高成功率，但需要让用户准确看到哪些行已写入。

可以采用“预检全部、写入分批、结果逐行”的折中方式。
 对于核心主数据，先预检并生成待执行批次，再由用户确认写入，通常更安全。

4.4 重复键和外部系统 ID 要统一口径

同一批次里可能同时出现内部工号、外部系统 ID 和手机号。
 它们都能帮助定位员工，但不一定都能作为更新唯一键。
 接口需要明确主唯一键，其他字段只用于辅助校验或冲突提示。

如果外部系统 ID 发生变更，不能因为手机号相同就自动合并两名员工。
 应将冲突行置为人工确认，并在回执中展示命中的候选记录。
 自动合并属于高风险动作，必须有明确权限和审计。

4.5 关联对象失败时不要静默创建

组织、岗位和角色是员工导入的典型关联对象。
 如果编码不存在，最安全的结果是该行失败并给出可用编码提示。
 自动创建同名组织可能绕过审批、数据权限和组织树治理。

批次级预检可以提前统计缺失的关联编码，帮助管理员一次性补齐主数据。
 补齐后重新预检，原始文件和批次身份仍然保留，避免操作人员重复上传造成多批结果。

五、批次模型：让一次导入拥有身份

▲ 批次保存一次文件边界，原始行保留回执依据，成功行关联目标记录，失败行可再次处理。

如果系统只在接口调用中临时处理 Excel，失败后就没有批次身份，重试只能重新上传整个文件。
 批次模型至少需要：

• 批次 ID；
• 文件名和文件摘要；
• 操作人和租户；
• 创建时间、状态和进度；
• 失败数、成功数、跳过数；
• 原始文件或受控引用；
• 结果回执位置。

5.1 幂等键要贯穿批次和行

同一个文件因为浏览器重复点击提交两次，不应该生成两批员工。
 可以使用文件哈希、操作人、业务类型和时间窗口生成批次幂等键。

行级写入还要使用业务唯一键和批次 ID，防止同一批次重试时重复插入。

5.2 失败重试不能重新处理成功行

重试请求需要带上原批次和失败行集合。
 服务先验证这些行确实属于失败状态，再重新校验和写入。
 如果成功行被再次提交，应该返回“已处理”，而不是重复更新。

5.3 批次审计要记录策略快照

批次执行时使用了哪个模板版本、唯一键、覆盖策略和租户规则，应该保存到批次快照。
 后续即使配置页面发生变化，仍能解释当时为什么把某行判定为新增或更新。
 审计信息还应记录确认人、执行人、重试人和每次状态变化时间。

对于敏感主数据，可以限制批次原始文件和回执的下载次数，并在下载时写入审计日志。
 批次完成不代表文件可以永久保留，原始文件和错误回执也要遵守企业数据保留策略。

5.4 模板也需要版本身份

同一个“员工导入模板”可能随着业务增加列、改变字典值或调整必填规则。
 如果接口只按文件名判断模板，旧模板可能被静默接受，最终产生半正确数据。

建议模板携带模板编码和版本号，服务端根据版本选择列映射、校验规则和可更新字段。
 下载模板时返回版本说明，导入结果中也记录命中的模板版本。

模板升级时，旧版本可以在过渡期继续导入，但要在页面明确提示即将停用。
 禁止让前端显示新版列头，而后端仍按旧列序号读取。

5.5 预检和正式写入要分开确认

对于员工、组织、角色等主数据，推荐先上传并完成预检，再由有权限的用户确认正式写入。
 预检结果要明确哪些行会新增、哪些行会更新、哪些行会跳过、哪些行阻断。

确认动作使用批次 ID 和版本号，服务端再次检查批次仍处于可执行状态。
 如果期间模板规则或组织数据发生变化，应要求重新预检，而不是直接沿用旧结果。

public void confirmBatch(String batchId, String operator) {    ImportBatch batch = batchService.require(batchId);    String tenantId = batch.getTenantId();    auditService.checkTenant(operator, tenantId);    if (!batch.isAwaitingConfirm()) {        throw new ImportStateException("批次不允许确认");    }    if (!permissionService.canImport(operator,            batch.getTenantId(), batch.getBizType())) {        throw new AccessDeniedException("没有导入权限");    }    auditService.record("IMPORT_CONFIRM", batchId, operator);    batchService.lockForExecution(batchId);    importExecutor.execute(batchId);}

确认后批次进入执行锁定状态，普通用户不能再修改原始文件或校验结果。
 如果需要修正，应该创建新的重试批次并关联原批次。

六、核心代码：让校验结果可回执

下面是一个按行生成结果的压缩示意。

public ImportRowResult validateRow(        ImportRow row, ImportContext context) {    List<String> errors = new ArrayList<>();    String key = normalize(row.getEmployeeNo());    if (StringUtils.isBlank(key)) {        errors.add("员工工号不能为空");    }    if (!context.deptCodes().contains(row.getDeptCode())) {        errors.add("所属组织编码不存在");    }    if (context.duplicateKeys().contains(key)) {        errors.add("文件内存在重复工号");    }    if (!errors.isEmpty()) {        return ImportRowResult.failure(                row.getRowNo(), key, errors);    }    return ImportRowResult.success(            row.getRowNo(), key, resolveOperation(key, context));}

返回结果中保留原行号，比只抛出第一个异常更适合批量处理。

6.1 写入时保护更新范围

public void writeRow(ImportRowResult result,        ImportContext context) {    if (result.isFailure()) {        return;    }    if (result.operation() == Operation.CREATE) {        employeeMapper.insert(buildCreate(result));        return;    }    EmployeeDO employee = employeeMapper.selectByNo(            result.uniqueKey(), context.tenantId());    if (employee == null) {        throw new ImportWriteException("更新目标不存在");    }    EmployeeDO update = buildAllowedUpdate(result);    update.setId(employee.getId());    employeeMapper.updateById(update);}

实际代码还需要并发锁、租户条件、审计和事务。
 这里强调更新字段要从白名单构造，而不是把整行 Excel 映射成 DO 后覆盖数据库。

6.2 结果回执要可下载

public ImportSummary buildSummary(        List<ImportRowResult> results) {    if (results == null || results.isEmpty()) {        return ImportSummary.empty();    }    return new ImportSummary(            count(results, Operation.CREATE),            count(results, Operation.UPDATE),            results.stream()                    .filter(ImportRowResult::isFailure)                    .collect(Collectors.toMap(                            r -> String.valueOf(r.rowNo()),                            ImportRowResult::message,                            (a, b) -> a)));}

回执可以在弹窗中展示，也可以生成带错误列的 Excel。
 重要的是同一行号和同一错误原因在两种展示中保持一致。

七、异步批次与进度

▲ 批次、行级处理和回执分别记录进度；图中异步编排属于设计方案，具体模块需按接入范围实现。

几万行数据不适合让 HTTP 请求一直等待。
 可以把上传、预检、执行和结果查询拆成异步批次。

进度字段至少区分：

• 文件已上传；
• 正在解析；
• 正在校验；
• 等待确认；
• 正在写入；
• 部分成功；
• 已完成；
• 失败。

“进度 100%”只说明任务结束，不说明数据全部成功。
 页面应同时展示成功、更新、失败和跳过数量。

7.1 进度写入要防止倒退

多个消费者或重试任务可能同时更新批次状态。
 建议使用状态机或带版本条件的更新，禁止一个迟到的“解析完成”覆盖已经进入“写入完成”的状态。

7.2 大批次要限制并发

导入本质上会放大数据库写入和关联查询。
 应按批次分片，控制线程数和数据库连接，避免一次导入拖垮其他后台业务。

性能优化应先测量：解析耗时、校验耗时、写入耗时和失败比例。
 不要仅因为“批量 SQL 更快”就跳过逐行回执。

7.3 断点恢复要以行状态为准

批次执行中断后，恢复任务不能只根据最后一个页码继续。
 某一页可能已经写入一半，或者消息已确认但回执尚未更新。
 更可靠的做法是为每一行维护 PENDING、SUCCESS、FAILED、SKIPPED 状态，并以行状态决定是否继续处理。

恢复时先读取处于 PENDING 或超时 RUNNING 的行，再校验目标记录是否已经写入。
 目标已存在且带有同一批次标识时，直接补回成功状态；目标不存在时才重新执行写入。
 这样可以降低网络重试、进程重启和消息重复带来的重复写入风险。

7.4 进度数字要能解释

“已完成 80%”对操作人员帮助有限。
 页面应该能解释总行数、已校验、待确认、成功新增、成功更新、跳过、失败和预计剩余时间。
 如果校验完成但等待人工确认，进度条不应继续自动增长。

批次列表可以按状态筛选，并支持从摘要跳转到失败行、原始文件和错误回执。
 导出回执时保留批次 ID，防止用户下载多个同名文件后无法判断来源。

7.5 查询和写入要分别限流

校验阶段可能频繁查询组织、岗位和角色。
 应按批次预加载可缓存的字典，并限制单批次的并发查询数量。
 写入阶段则更关注数据库锁、事务大小和索引命中率，不能和读取限流混为一谈。

当多个租户同时导入时，队列需要按租户或业务类型分配配额。
 单个大批次不能占满所有执行线程，否则其他租户的日常业务也会被拖慢。
 批次详情应区分排队等待时间、关联查询耗时和数据库写入耗时。容量评估除了文件大小，还要考虑每行引用校验的次数、更新比例以及并发租户数量；否则同样一万行数据，压测结果可能相差很大。

八、安全与数据质量

Excel 可能包含公式、超长字符串、恶意文件和敏感信息。
 上传文件要放在受控目录或对象存储，不直接拼接用户文件名。
 导出错误回执时也要考虑手机号、身份证号和工资数据脱敏。

8.1 文件安全和业务权限要同时校验

上传接口要校验文件大小、MIME、扩展名和内容特征。
 解析器应禁用不需要的宏、外部链接和危险公式。
 原始文件和错误回执使用受控对象存储，下载时再次校验租户、批次归属和操作者权限。

不要把原始 Excel 放在公开静态目录，也不要把本地绝对路径返回给前端。
 文件名只用于展示，物理路径使用系统生成的对象键。

8.2 数据质量需要可量化

导入质量可以按新增成功率、更新成功率、失败率、跳过率和重复率统计。
 对于组织、岗位、角色等引用字段，还可以记录“引用命中率”。
 这些指标帮助实施人员判断是模板问题、主数据问题还是接口同步问题。

如果一个批次失败主要集中在组织编码，修复动作应优先补齐组织主数据，而不是让操作员在 Excel 中重复修改同一列。
 系统可以在错误回执中附带可用组织编码提示，但不要为了导入成功自动创建组织。

8.3 更新策略要保护人工维护字段

员工导入经常同时面对 HR 维护、员工自助和外部系统同步。
 字段级来源应明确，例如手机号由员工自助维护、部门由 HR 导入维护、账号状态由系统流程维护。
 导入更新只覆盖属于当前来源的字段，其他字段保持原值。

当用户勾选“覆盖空值”时，页面需要二次确认，并显示预计影响字段数。
 执行日志记录覆盖策略、模板版本和操作者，便于发生误覆盖时定位责任。

数据质量方面，导入不是替代主数据治理。
 如果组织编码混乱、员工工号没有唯一约束，再完善的弹窗也只能把问题推迟到下一次导入。

九、验收用例

建议覆盖：

1. 纯新增文件全部成功。
2. 新增和更新混合，确认唯一键和更新白名单。
3. 文件内重复行只保留明确失败。
4. 外部组织不存在，回执原行号和组织值。
5. 空值更新不覆盖人工维护字段。
6. 一行失败不影响其他允许成功的行。
7. 重复提交相同文件不重复创建。
8. 只修正失败行后重试，成功行保持不变。
9. 任务中断后恢复，不让进度倒退。
10. 不同租户使用相同工号互不影响。

验收时不要只准备一份全是正确数据的 Excel。
 至少准备一份包含重复工号、失效组织、空值覆盖、超长手机号和跨租户相同工号的混合文件。
 先执行预检，再确认写入，最后只修复失败行重试。

9.1 验收结果应包含证据

每条失败记录要能回到原始行号、列名、原值、模板版本和批次 ID。
 每条成功记录要能回到目标记录 ID和写入时间。
 重试记录要能看到原批次、失败行集合和新的执行批次。

如果系统提供下载错误回执，回执文件中的行号、错误信息和页面详情必须一致。
 如果页面显示“更新成功”，还要能查看更新字段摘要，避免用户误以为整行所有字段都被覆盖。

9.2 把导入样本做成回归集

模板升级、唯一键调整、组织树变化或导入组件重构后，自动重放历史样本。
 回归断言不仅检查数据库最终行数，还要检查新增、更新、跳过、失败数量和错误原因是否符合预期。
 对于幂等场景，重复提交同一批次后，目标记录数量和审计日志数量都不应增加。

大批次性能回归还要记录解析、校验、写入和回执生成耗时。
 如果新增一个校验导致耗时明显上升，应先分析查询次数和缓存命中率，而不是直接关闭校验。

十、快速体验

在线演示地址为 https://ruoyioffice.com/web/，账号 admin / admin123。
 可从系统管理的用户、角色、岗位导入入口体验模板、覆盖策略和回执。
 租户迁移导入属于更大批次的异步场景，适合观察进度和结果边界。

源码可阅读前端 import-excel-modal 的类型与组件，以及各模块的导入请求实现。
 不同模块的导入能力并不天然完全一致，统一批次、断点恢复和失败重试要以实际接入范围为准。

常见问题

Excel 导入应该全部成功或全部失败吗？

取决于业务。
 主数据通常更适合先预检再确认；低风险批量维护可以允许部分成功，但必须返回逐行结果。

更新支持应该默认打开吗？

不建议默认打开。
 必须明确唯一键、可更新字段、空值语义和操作审计。

为什么一定要保留原行号？

因为错误回执最终要回到用户看到的 Excel。
 原行号是修复问题和只重试失败行的最短路径。

失败行重试会不会重复写入？

只有在批次 ID、业务唯一键和幂等约束共同生效时，才能安全避免重复。
 单纯再次调用导入接口不等于幂等。

FastExcel 或 EasyExcel 能解决哪些问题？

它们可以解决文件解析和部分校验问题，不能替代业务唯一键、权限、批次、回执和重试设计。

结语

可靠的 Excel 导入不是“把表格数据塞进数据库”，而是把每一行变成可解释、可定位、可重试的业务结果。
 当新增、更新和失败分别拥有明确语义，导入才从一次性脚本变成企业数据入口。

如果这篇对你有用，点个「在看」或收藏。

🌐 演示地址：https://ruoyioffice.com/web
 📦 GitHub 源码：https://github.com/yuqing2026/ruoyi-office
 📦 Gitee 源码：https://gitee.com/yqzy1688/ruoyi-office
 💬 微信：17156169080（获取产品咨询）

打开演示地址直接查看系统。