老系统二次开发：如何优雅实现Excel自动导入接口

手头这套 MS 系统是我们内部跑了好几年的业务管理后台名字里的 MS 纯粹是 Management System 的缩写。这周接到的任务是在不动线上老逻辑的前提下给现有源码新增一个自动导入接口——让业务方手里那些又多又乱的 Excel 数据能够自动化落库替代原先管理员一条条手工录入的笨办法。任务听上去不大真正动起来才发现在老源码里把新接口做得优雅、安全、可回退比新写一个模块要难得多。这篇文章尽量把整个改造过程复盘出来包括接口协议、源码分层改动、幂等与并发处理、上线后的坑和排查手段适合正在给老系统做二次开发、或者想自己动手做数据自动导入功能的同学参考。改造期间我踩了哪些坑、为什么最后选择了源码层改造而不是独立脚本、接口幂等怎么实现才算稳这些我都会掰开来讲。先说明一点MS 系统在我这里只是一个内部管理系统的代号不是任何商业产品但这一套改造思路放到大部分老业务系统上都是通用的。1. 项目背景与整体设计思路——为什么非要改源码1.1 在源码里加接口而不是外挂脚本先说背景。我们团队维护的 MS 系统是一个典型的内部管理平台包含客户、商品、订单、库存这些基础模块。旧系统的数据录入完全依赖管理员在后台一项项创建。平时量小没什么感觉一到月度活动几百上千条商品资料、客户资料要手敲进去出错率直线上升重复劳动也非常严重。业务方最终提了一个需求做一个自动导入功能他们把按模板整理好的 Excel 或 CSV 传上来系统直接读进数据库。面对这个需求最常见的方案有两个。一个是写独立脚本定时扫描某个目录发现文件就插库另一个就是标题里提到的直接改 MS 的源码在系统内部新增一个自动导入接口。我选了后者原因并不复杂独立脚本看着轻便但它拿不到系统内部的用户上下文和权限上下文。导入数据需要校验操作人是否有权限需要记录谁在什么时间导入了什么数据也需要复用系统里已有的编码规则、校验逻辑和日志链路。把这些在脚本里重写一遍工作量不一定比改源码小后续维护风险反而更高。系统本身已经有完整的用户体系和权限拦截接口放在源码里一进来就能借力。改源码还有一层现实考虑老系统一般没有独立的数据同步模块业务方希望导入之后的效果和手工建单完全一致包括触发后续的状态流转、消息通知。只有接入源码的服务逻辑才能保证“导入即走正常业务流程”而不是数据进去了流程没动留下一堆半吊子脏数据。从长期维护的角度看多一套外挂脚本就是多一套没人愿意接手的代码不如直接把能力长在主系统里。1.2 需求拆解与方案设计动手之前我把需求拆成了几块。最核心的是导入入口业务方上传一个标准模板文件系统解析后自动匹配字段完成校验、去重、落库然后返回导入结果。拆开以后可以分成五个环节文件上传、模板解析、数据校验、幂等控制、结果反馈。这五个环节里最容易被忽略的是“结果反馈”。第一次做导入功能的人很容易默认文件传上去、数据库里有数据就算完事。但业务方真正关心的是哪些行导进去了、哪些行因为什么原因被拒了。如果一次导入五千条其中三百条失败总不能只给一句“部分失败”就糊弄过去。我这次把结果反馈设计成两层第一层是任务级状态成功、失败、部分失败第二层是明细结果失败行号、失败原因全部落地前台按批号就能查。在设计接口结构时我给自己定了几个硬性指标接口要幂等同一个批号重复提交不会产生重复数据要可控单次导入量设上限要可追踪每个导入动作都有对应记录还要可回退发现导入有问题能从历史任务里找出这批数据的范围。这些指标不是拍脑袋定的都是业务方以前手工操作时踩过的坑。比如“可回退”这条就是因为曾经有人手工录错一批数据结果找不回错误范围只能全表核对教训太深刻。1.3 接口协议与幂等设计接口协议我采用的是比较保守的 REST 风格POST /api/import/auto参数包含文件、模板类型和批号。为什么不设计成 GET 或把数据直接写在 URL 里因为文件体量大GET 不适合传输大段数据也不适合携带文件POST 是符合直觉的选择。为了兼容以后不同数据源我把模板类型设计成枚举比如 PRODUCT、CUSTOMER、ORDER分别对应不同导入模板。以后要加新的导入场景只需要扩展枚举和对应的解析处理器不需要在 Controller 层堆 if-else。幂等是这次改造里最核心的一环。所谓幂等简单说就是同一个导入请求发一次和发一百次对系统数据产生的结果必须一样。实现我用了两层机制应用层用 batchNo 判断如果发现批号对应的任务已经存在直接返回原任务的执行结果不再重复解析数据库层用唯一索引兜底把 batchNo 和业务主键绑在一起。即使应用层判断漏了数据库这层也会拦住重复插入。提示接口幂等不是“加个判断”就完事需要应用层和数据库层一起兜底。只靠代码判断并发场景下查和插之间有缝隙数据库唯一约束才是真正的最后防线。2. 核心功能实现细节——自动导入的关键环节2.1 入库表设计与批号机制源码改造先动手的通常是表结构。这块不复杂但规划不好后面很痛苦。我新增了两张表一张存导入任务一张存导入明细。任务表字段包括主键、批号、模板类型、状态、总条数、成功条数、失败条数、操作人、导入时间、完成时间。明细表记录每一行的导入结果字段包括任务主键、行号、业务主键、状态、错误信息。就这么简单的两张表既解决了结果反馈也解决了可追溯。批号设计有一个容易忽略的点批号最好由调用方生成而不是后端在收到请求时临时生成。为什么因为业务方可能在网络超时后重试同一个请求如果后端每次生成新批号重试就变成了新导入幂等就无从谈起。我在接口里约定 batchNo 由调用方传入格式建议用“业务前缀时间戳随机数”比如 PRODUCT_20250317103015_8291。如果调用方不传后端也会生成一个但这样就不能保证重试幂等只能算尽力而为。建表 SQL 大概是这样的CREATE TABLE import_task ( id bigint(20) NOT NULL AUTO_INCREMENT, batch_no varchar(64) NOT NULL COMMENT 调用方传入的批号, template_type varchar(32) NOT NULL COMMENT 模板类型, status tinyint(4) NOT NULL DEFAULT 0 COMMENT 0处理中 1成功 2部分成功 3失败, total_count int(11) NOT NULL DEFAULT 0, success_count int(11) NOT NULL DEFAULT 0, fail_count int(11) NOT NULL DEFAULT 0, operator varchar(64) DEFAULT NULL, create_time datetime DEFAULT NULL, finish_time datetime DEFAULT NULL, PRIMARY KEY (id), UNIQUE KEY uk_batch_no (batch_no) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4; CREATE TABLE import_detail ( id bigint(20) NOT NULL AUTO_INCREMENT, task_id bigint(20) NOT NULL, row_no int(11) NOT NULL COMMENT Excel行号, biz_key varchar(128) DEFAULT NULL COMMENT 业务主键, status tinyint(4) NOT NULL COMMENT 1成功 2失败, error_msg varchar(512) DEFAULT NULL, PRIMARY KEY (id), KEY idx_task_id (task_id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;2.2 文件解析与数据校验模板解析我采用了流式读法没有一次性把整个 Excel 塞进内存。原因很直接一次导入的数据量大EasyExcel 这类库支持逐行回调读一行处理一行内存占用很平稳。操作时我在监听器里维护一个累计行数的计数器每读一行就做基础字段检查比如必填项是否为空、格式是否是数字、日期格式是否合法。这比一次读全量再遍历安全性高一个量级。数据校验是这次实现里最琐碎、也最值钱的部分。业务方传来的数据永远是“看起来对实际五花八门”。我遇到过手机号带空格、日期格式五花八门、数字列里混进去中文注释、Excel 里隐藏行和空行掺杂。所以校验逻辑我坚持“先校验后落库”先拿模板映射规则把表头、字段类型、必填项、长度限制全部跑一遍错误行收集到一个列表里。校验完成后如果有错误默认允许“跳过错误行继续导入”和“有错就中断”两种配置但最终都会把错误明细写进导入明细表供前台下载对照。EasyExcel 的监听器结构大致是这样public class ImportDataListener extends AnalysisEventListenerMapInteger, String { private final ListMapInteger, String rows new ArrayList(); private final int batchSize 500; Override public void invoke(MapInteger, String row, AnalysisContext context) { rows.add(row); if (rows.size() batchSize) { saveRows(rows); rows.clear(); } } Override public void doAfterAllAnalysed(AnalysisContext context) { if (!rows.isEmpty()) { saveRows(rows); rows.clear(); } } private void saveRows(ListMapInteger, String rows) { // 这里调用校验和落库逻辑 } }2.3 批量落库与事务边界控制落库这里有一个老生常谈的坑以为包在一个大事务里最安全结果数据量大时内存和锁全部吃紧一条脏数据导致全部回滚。我的做法是分批提交每批 500 条左右。批内业务逻辑在一个事务里批与批之间独立提交。这样即使中间某批出了问题也只影响这一批前面已经提交的数据不会跟着回滚。导入进度也更好做每提交一批就更新一次任务表的成功条数用户看到的不再是漫长的等待而是逐渐跳动的进度。事务边界的控制上我特别提醒一个反直觉的东西不要为了追求“要么全部成功要么全部失败”就把几万条数据包进一个事务。业务导入和人手动录入很像你不可能要求手敲一百条、敲错一条就把前面九十九条全部抹掉。合理的做法是给用户一个选择严格模式下只要有错误就整体失败宽容模式下错误行单独记录正确行照常导入。默认我推荐宽容模式配合明细表让用户下载错误文件处理后再补导。写成代码大概是这样的伪代码Override Transactional(rollbackFor Exception.class) public void executeImport(String batchNo, ListRowData validRows) { ListListRowData batches partition(validRows, 500); for (ListRowData batch : batches) { // 每个批次在一个事务里提交 insertBatch(batch); updateTaskProgress(batchNo, batch.size()); } }3. 实操改造过程记录——从找分层到自测上线3.1 找分层、定位扩展点进入源码之后第一步并不是写代码而是摸清项目本身的架构习惯。我先把 MS 系统的模块结构读了一遍发现它是经典的三层结构Controller 层、Service 层、Dao 层数据访问层用的 MyBatis数据库是 MySQL。为了不破坏原有代码风格我新增功能时严格沿用这套分层并且保持和旧代码一致的包路径、命名习惯。老系统改造最怕的就是一个人一种风格时间一长整个工程就变成了补丁堆。定位扩展点的时候我格外关注两件事。第一原有的登录拦截器是否覆盖了新接口如果不覆盖权限就是空壳谁拿到接口地址都能导数据这个必须第一时间确认。第二原有的全局异常处理器能不能把自定义导入业务异常正确转换成前台提示如果不能新增接口内部也要做自有的异常兜底。这两件事看起来是“小细节”但实际大系统上线出问题十有八九都是这些基础防线没接好。3.2 从实体到接口逐层落地编码顺序我习惯自底向上先写实体类再写 Mapper然后 Service最后 Controller。这样做是为了每层都能单独编译过、单独测试不至于写完 Controller 才发现下面一层全是问题。实体类按前面设计的表结构建字段和数据库列对齐。Mapper 按 MyBatis 惯例写了对应的 insert 和 selectById、selectByBatchNo。Service 层是重点我用 Transactional 注解控制事务方法里按上一节的分批策略循环处理监听器解析出来的数据集合。Controller 层做的是参数收口接收文件、模板类型、批号调用 Service把任务结果封装成统一的返回对象。Controller 层实现大概是这样RestController RequestMapping(/api/import) public class AutoImportController { PostMapping(/auto) public ResultString autoImport(RequestParam(file) MultipartFile file, RequestParam(templateType) String templateType, RequestParam(batchNo) String batchNo) { if (file.isEmpty()) { return Result.fail(导入文件不能为空); } if (file.getSize() MAX_FILE_SIZE) { return Result.fail(文件大小超过上限); } String taskId importService.createTask(file, templateType, batchNo); return Result.ok(taskId); } }Service 的核心职责就是创建任务、解析文件、分发校验、分批落库。每个环节都可能抛异常我统一用自定义异常封装由全局异常处理器转成前台友好的提示。3.3 配置开关和上线前自测老系统改造上线最怕的就是没有退路。我在配置中心里加了几个开关导入功能总开关、单次导入行数上限、支持的文件类型、严格模式还是宽容模式。上线时先关掉总开关让业务方把历史模板和数据先准备好正式启用时打开开关控制风险范围。为什么这么谨慎因为自动导入一开可能几千条数据直接进生产库一旦模板理解错了脏数据会在一瞬间铺开比人工录入慢吞吞的出错要难收拾得多。自测环节我用了完整的“三段式”先用小数据量跑通接口功能再用十万行数据压批量性能和内存最后用脏数据测试各种校验分支。中间发现两个问题都挺典型。第一个是 Excel 模板里第一行有统计信息表头没有真实从第一列开始导致解析错位第二个是日期列在不同 Excel 里会自动变格式有人填的是文本有人填的是真正的日期单元格解析逻辑必须兼容这两种情况。这些问题不实测根本发现不了所以强烈建议给老系统做导入功能时自测数据一定要贴近业务方真实使用的文件而不是自己造一个干干净净的模板。4. 上线后的问题排查与避坑经验4.1 高频踩坑案例这一路改下来我整理了四个典型故障基本覆盖自动导入功能的绝大多数坑。第一个是 CSV 乱码业务方保存的 CSV 可能是 GBK 编码读取时不指定字符集导入后中文全部变成问号。解决方式是自动识别文件头 BOM并且允许在接口参数里指定编码。第二个是重复导入第一次调接口数据进去了业务方以为没成功又调了一次结果变成两份。这个就是上一节说的幂等没做好补唯一索引后才真正压住。第三个是大文件内存溢出一次性把整个 Excel 读进内存几万行数据轻松把堆内存打爆改成流式读取后问题消失。第四个是接口响应超时同步执行几万条导入要几十秒网关和调用方都等不住后来改成异步任务先返回任务编号再用接口查询任务状态。问题现象问题根因解决方案中文全部乱码CSV 编码不匹配检测 BOM支持指定字符集数据导入两次缺少幂等机制批号去重 数据库唯一索引内存溢出一次性加载整个文件流式读取逐行回调处理接口响应超时同步处理耗时过长异步任务 查询任务进度4.2 排查工具与日志手段排查这类问题我的经验是先有一个贯穿全链路的任务标识。每次导入任务生成时把 batchNo 同时写入日志上下文之后所有解析、校验、落库处理都会带上这个标识出问题时 grep 一条日志就能看到整个过程。没有这个机制几个问题混在一起时排查效率会低很多。另外要重点记录每个阶段的耗时比如上传耗时、解析耗时、校验耗时、落库耗时。数字一出来性能瓶颈一眼就能定位。导入任务状态的更新也要养成习惯。任务刚创建是“处理中”解析完成更新为“待处理”落库成功后更新为“成功”有失败行则更新为“部分成功”整体失败则更新为“失败”。这个状态机虽然简单但它是后续所有监控、告警、统计的基础。我用定时任务扫表的方式监控这些状态超过五分钟还处于“处理中”的记录自动报警出问题时能做到第一时间感知。4.3 必须知道的安全和回滚策略自动导入直接面向生产数据安全回滚策略必须提前想好。我个人的原则是三条导入前别动原表导入时用事务绑定任务导入后留足人工核查入口。尽量不做原地覆盖更新而是通过新增数据加状态字段来体现导入结果。比如导入客户资料我不会直接把旧客户覆盖掉而是把新数据标为“待生效”或“草稿”等业务方核查确认后再生效。这样可以避免因为模板字段对应错了把一整批正确数据全部洗掉。真到了必须回滚的场景我的建议是通过导入任务明细表反查找出这批数据写入时用的批号按批号精准删除。少用“按时间删”或“按操作人删”这种模糊条件批号才是这批数据的身份证。删除前要导出备份删除后要做数量核对确认删干净了才算完。实际项目里我见过太多人图省事全表清掉重导结果业务数据在导入期间又有新增重导后两边对不上折腾得更久。5. 这次改造沉淀下来的几条判断代码写完之后我把自己关在会议室里复盘了整个改造过程沉淀了几条对老系统二次开发非常有用的判断。第一条老系统改造最值钱的部分不是新增了多少功能而是你是否把新功能和原有逻辑放在同一套规则里。凡是绕过原有权限体系、日志体系、事务体系的新功能未来一定会变成新的历史包袱。第二条自动导入这类接口做得好不好边界不在“能不能导进去”而在“导错了能不能说清楚”结果反馈和追溯能力才是业务方真正感知到的价值。第三条改造过程中所有看似啰嗦的配置开关、状态机、唯一索引都是给未来那个“半夜被电话叫起来处理问题”的自己留的退路。最后再说一个我个人的习惯改老代码之前先把需要改动的文件复制一份放到专门的 backup 目录不要只依赖版本管理。版本管理能帮你回滚代码备份目录能让你随时随地对照旧实现排查某些隐性问题时特别好用。源码改造和盖房子一样打地基的时候多花点耐心后面住进去才踏实。