Y Yuan Tools
2026/7/4

第三个工具：JSON 工具箱的设计与实现

我把开发中最常见的 JSON 格式化、修复、查询、转换、对比和类型生成整理成一个本地优先的小工具，并同时发布 Web 在线版和 Windows 桌面版。

第三个工具：JSON 工具箱的设计与实现

做完图片打码工具和二维码生成器之后，我开始思考一个更偏开发者日常的小工具：JSON 工具箱。

JSON 几乎出现在每一次接口联调、配置排查、日志分析和数据清洗里。很多时候我们只是想快速格式化一段接口返回，或者把一份数组对象转成 CSV，再或者从一个复杂响应里查出某个字段。单独打开多个网页工具当然也能完成，但它们经常有广告、加载慢、体验割裂，数据还要贴到外部网站。

所以这个工具的目标很明确：把 JSON 处理里最常用的一组能力集中起来，做成一个本地优先、响应快、界面干净的工具箱。

为什么不只做格式化

如果只做 JSON 格式化，这个工具会很快完成，但也很容易变成一个“同质化小功能”。我真正需要的是一个日常工作台。

这次我把第一版范围定在这些功能：

  • JSON 格式化、压缩、校验。
  • 常见错误修复，例如单引号、尾随逗号、未加引号的 key。
  • JSONPath 路径查询。
  • 结构树查看。
  • JSON 字符串转义和反转义。
  • JSON 与 CSV 互转。
  • JSON 与 YAML 互转。
  • 根据示例 JSON 生成 TypeScript 类型。
  • 两份 JSON 的结构差异对比。
  • 字符数、行数、对象数、数组数、最大深度等统计信息。

这些功能不只是为了“看起来多”，而是覆盖了开发和数据处理里高频出现的几个动作：整理、检查、提取、转换、对比、复用。

架构仍然延续同一套路线

这个工具继续沿用我现在的小工具标准架构：

flowchart LR
  A["Svelte + TypeScript UI"] --> B["Web 静态版"]
  A --> C["Tauri Windows 桌面版"]
  B --> D["博客在线工具页面"]
  C --> E["GitHub Release 下载"]
  A --> F["本地 JSON 处理核心逻辑"]

项目目录是：

D:\dev\yuan-tools\yuan-json-toolkit

中文名称是：

JSON 工具箱

我把核心处理逻辑放在：

src/lib/core/jsonTools.ts

UI 只负责输入、模式切换、运行和展示。这样后续如果要把某些大体积 JSON 处理迁移到 Web Worker，或者给某个模式加更细的测试，都不需要大改界面。

体验上的几个取舍

第一版没有做成一堆独立页面，而是采用“工作台”布局：

  • 左侧输入。
  • 右侧输出。
  • 顶部切换处理模式。
  • 底部显示状态、耗时和本地处理提示。

这样用户进入页面后，不需要阅读说明，也不用先选择一个复杂场景。粘贴内容，选择模式，点击运行，就能得到结果。

我还刻意没有在输入时自动持续处理。因为 JSON 内容可能很大，如果每次输入都同步解析和转换，界面会变卡。第一版采用点击运行的方式，减少不必要的计算。后续如果遇到更大文件场景，可以再把重任务放到 Web Worker。

发布时遇到的小问题

这次发布前后还修了两个流程和兼容性问题：一个是 GitHub Release 的说明文件曾经出现中文乱码，另一个是 Svelte 5 的应用挂载方式。

原因不是文章内容本身，而是 PowerShell 脚本在 Windows 下执行无 BOM 的中文 .ps1 时，可能会按系统代码页解释中文。最后我把发布资产脚本重新保存成 Windows PowerShell 能稳定识别的 UTF-8 格式，并重新生成 release notes。

这是一个小问题，但很值得记录。因为我的目标不是只做一个工具，而是长期重复发布很多工具。发布链路里任何一个小乱码，都会在未来被复制很多次。越早修掉，后面越省心。

第一次发布后，我在本地重新验证时发现页面虽然能打开，但工具交互无法正常使用。根因是入口文件还使用了旧的 new App(...) 写法，而当前项目依赖的是 Svelte 5。修复方式是改为 mount(App, ...)，并重新用浏览器点击“运行当前处理”验证 Web 静态包确实能产生结果。

最终产物

这次发布的仓库是：

https://github.com/yuan0727/yuan-json-toolkit

当前推荐下载的 Release：

https://github.com/yuan0727/yuan-json-toolkit/releases/tag/v0.1.1

Release 资产包括：

  • yuan-json-toolkit-win-v0.1.1.exe
  • yuan-json-toolkit-web-v0.1.1.zip
  • yuan-json-toolkit-guide-v0.1.1.md

博客上线后，工具页面会放在：

https://www.yuantools.com/tools/json-toolkit/

在线使用页面会放在：

https://www.yuantools.com/apps/json-toolkit/

下一步

JSON 工具箱第一版已经能覆盖大部分常见需求，但它还有继续增强的空间：

  • 大 JSON 处理放到 Web Worker。
  • 树视图改成真正可折叠的虚拟列表。
  • JSON 对比增加更直观的左右高亮。
  • CSV 转 JSON 增加类型推断。
  • 增加历史记录和常用片段。

这类工具的价值不在于一次做完所有功能，而在于它会在真实使用中不断变得顺手。对我的长期计划来说，这也是一个很好的作品：它既能服务在线流量，也能展示我把一个开发者需求做成完整应用的能力。