Excel 批量转 JSON 工具的技术实现与选型指南

一、背景：为什么”Excel 转 JSON”值得认真对待

在数据集成、接口联调、配置生成、测试数据准备等场景中，Excel 长期扮演着”业务侧数据入口”的角色，而 JSON 则是服务端与前端之间最通用的数据交换格式。两者之间的转换看似简单——读表、拼键值对、写文件——但真正落地到工程实践中，往往会遇到一系列细节问题：

• 批量处理需求：业务方通常一次提供几十个甚至上百个表格文件，逐个手工转换效率极低；
• 列名不规范：Excel 表头常包含中文、空格、特殊符号，直接作为 JSON 键名会导致下游解析困难；
• 空行与脏数据：表格末尾的空行、合并单元格残留、格式不统一的行，容易产生无效记录；
• 界面阻塞：转换过程若在主线程执行，文件稍大就会造成界面假死，用户体验差；
• 过程不可见：批量转换缺少进度与结果反馈，出错后难以定位是哪个文件、哪一行的问题。

因此，一个”好用”的转换工具，本质上不是完成一次格式映射，而是要把输入管理、规则配置、任务调度、结果反馈这四个环节都处理妥当。下文围绕这样一套通用技术方案展开，既可作为自研工具的参考设计，也可作为评估现成方案的检查清单。

二、整体架构设计

一个可用的批量转换工具，可以划分为四层：

┌─────────────────────────────────────────┐
│  交互层：文件添加（选择/拖拽）、选项配置、日志展示  │
├─────────────────────────────────────────┤
│  任务层：批量任务队列、异步执行、状态与进度管理      │
├─────────────────────────────────────────┤
│  转换层：Excel 解析 → 行过滤 → 列名映射 → JSON 序列化 │
├─────────────────────────────────────────┤
│  IO 层：文件读写、输出路径与命名规则、异常捕获       │
└─────────────────────────────────────────┘

这种分层的价值在于职责隔离：交互层不关心解析细节，转换层不依赖具体 UI 框架，任务层负责把二者解耦。后续若要增加 CSV、YAML 等输入输出格式，只需扩展转换层，其余部分基本不动。

三、核心功能模块的实现要点

3.1 文件解析：兼容 .xls 与 .xlsx

Excel 存在两代主流格式：早期的二进制格式（.xls）与基于 XML 压缩包的开放格式（.xlsx）。通用做法是引入成熟的开源解析库，按扩展名分派到不同的读取器，并统一抽象为”工作表 → 行 → 单元格”的二维结构。需要注意：

• 表头行定位：默认取第一行作为列名，但应允许配置表头所在行号，以兼容带标题说明的报表；
• 单元格类型归一：数字、日期、布尔值在 Excel 内部类型不同，输出前需统一转为字符串或按规则保留数值类型；
• 资源释放：批量场景下必须确保每个文件读取后及时关闭流，否则大文件批量处理容易造成句柄泄漏。

3.2 空行过滤：定义”空”的判定标准

“跳过空行”看似一句话，实则需要明确判定规则。推荐采用”整行所有单元格均为空或仅含空白字符”作为空行定义，并可进一步提供两种策略：

• 严格模式：仅跳过完全空白的行；
• 宽松模式：跳过所有列均为空的行，但允许部分列为空的行保留（输出中对应键值为空字符串或 null）。

规则应在界面上明确说明，避免使用者对结果产生预期偏差。

3.3 列名映射：从表头到 JSON 键名

这是影响输出可用性的关键功能。典型实现是维护一张”原始列名 → 目标键名”的映射表：

{
  "用户 姓名": "userName",
  "注册时间": "registerTime",
  "订单金额(元)": "orderAmount"
}

实现上有几点建议：

1. 未映射列的兜底策略：可配置为”保留原列名””自动转驼峰””忽略该列”三种，避免映射表不完整时丢数据；
2. 键名合法性校验：目标键名应满足常见标识符规范，工具可在转换前做一次预校验并提示冲突项；
3. 映射配置可持久化：将映射表保存为本地配置文件，便于同类表格重复使用，减少重复劳动；
4. 重复键检测：多个原始列映射到同一目标键时，应给出告警而非静默覆盖。

3.4 输出规则：路径与命名

输出文件默认与源文件同目录、同名替换扩展名（如 data.xlsx → data.json），这是最符合直觉的约定。同时建议补充：

• 输出目录可指定：批量处理时避免污染源目录；
• 重名处理：目标文件已存在时的覆盖/跳过/重命名策略；
• 编码与格式：统一使用 UTF-8，输出采用带缩进的格式化 JSON 便于人工核对，或提供压缩选项用于生产环境。

3.5 异步执行与实时日志

批量转换属于典型的 IO 密集型任务，必须放到后台线程执行，主线程只负责界面响应。推荐模式：

主线程：收集文件列表 → 校验参数 → 提交任务 → 更新按钮状态
后台线程：逐个文件执行转换 → 通过回调/信号上报进度 → 写日志
完成回调：恢复按钮状态 → 汇总成功/失败数量

日志区域应至少包含：每个文件的开始与结束、输出路径、记录条数、失败原因（文件损坏、格式不符、权限不足等）。转换期间禁用”开始转换”按钮，防止重复提交。

四、技术选型：自研还是使用现成方案

面对”有没有好用工具”这个问题，实际有三条路径，各有适用边界：

路径	优点	局限	适用场景
通用表格软件手工导出	零成本、上手快	无法批量、无法做列名映射、易出错	一次性、少量数据
脚本自行处理	灵活、可版本化、易集成 CI	需要开发能力，异常处理需自行完善	有开发资源、规则稳定的团队
带界面的专用小工具	批量化、可视化配置、非技术人员可用	功能边界固定，复杂规则需定制	业务人员频繁提交表格的团队

对于大多数团队，务实的做法是：规则简单且一次性用表格软件手工处理；规则稳定且需反复执行用脚本固化；提交方是非技术角色且频率高，则值得投入一个带界面的转换工具。自研时不必追求大而全，先把”批量 + 空行过滤 + 列名映射 + 日志反馈”四件事做扎实，就已覆盖绝大部分真实需求。

如果转换结果需要进一步进入云端数据链路，可将输出的 JSON 文件按通用方式上传至对象存储，再由下游的数据处理或消息队列服务消费，这一环节使用各云厂商通用的存储与消息类能力即可，不涉及特定产品的专有接口。

五、常见问题与排查清单

在实际使用中，以下问题出现频率最高，可作为工具设计与使用时的检查项：

1. 表头含合并单元格：解析后仅首列有值，其余列为空，需在解析阶段做横向填充或提示用户整理源表；
2. 日期与数字精度丢失：Excel 日期本质是序列号，需按格式转换；长数字（如订单号）应避免被科学计数法截断，建议按文本读取；
3. 文件被占用：源文件正在被表格软件打开时读取可能失败，应在日志中明确提示关闭文件；
4. 超大批量内存压力：单文件行数极大时应采用流式逐行处理，而非一次性载入内存；
5. 异常中断：单个文件失败不应终止整个批次，应记录失败项并继续处理剩余文件。

六、小结

Excel 转 JSON 是一个”需求简单、细节不少”的典型工程问题。一个称手的工具，其价值不在于转换动作本身，而在于把批量调度、规则配置、异常处理与过程反馈这些容易被忽略的环节做完整。开发者在自研时，建议按本文的分层架构组织代码，优先保证转换规则的可配置性与失败场景的可观测性；在选择现成方案时，也可对照上述功能点逐项评估，判断其是否真正匹配团队的表格规范与协作流程。