Birdor JSON Formatter 实现规格：页面结构、状态机、错误类型与测试样例

本系列导航

• 上一篇：Birdor 风险复盘清单
• 下一篇：Birdor JWT Decoder 实现规格
• 返回目录：Birdor 商业计划书目录

本章关键词

JSON Formatter、实现规格、页面结构、状态机、错误类型、测试样例、本地执行、工具页模板。

适合阅读的人

• 准备实现 Birdor JSON Formatter 的工程师。
• 需要把 PRD 转成可验收产品规格的人。
• 想用 JSON Formatter 沉淀 Birdor 工具页标准的人。

本章摘要

JSON Formatter 是 Birdor 第一批基础工具中的样板工具。它的价值不只是格式化 JSON，而是验证工具页基础模式：本地执行、输入输出区域、操作按钮、错误提示、隐私说明、相关工具、FAQ、指标和后续 API 复用。

本文把 JSON Formatter PRD 和 首批工程 Issue 转成实现规格。实现时应优先保证正确性、稳定性和错误体验，AI schema 推断、批量处理、大文件 Worker 和 API 不进入第一版。

页面结构

JSON Formatter 页面建议分为六个区域：

首屏必须能直接使用。SEO 内容和 FAQ 放在工具下方，不应把工具挤到折叠以下。

数据模型

页面状态建议包含：

error 对象建议包含：

状态机

状态流转建议如下：

关键原则：任何失败都不能清空原始输入。用户输入是资产，工具必须保护它。

操作规则

Format：

• 输入为空时显示空输入提示。
• 输入合法时使用缩进输出。
• 输出区显示格式化结果。
• 更新 lastAction 为 format。

Minify：

• 输入合法时输出无多余空白的 JSON。
• 不改变字符串内部内容。
• 更新 lastAction 为 minify。

Validate：

• 输入合法时展示 valid 状态。
• 可输出格式化结果，也可只显示校验成功。
• 第一版建议同时输出格式化结果，方便用户继续复制。

Sample：

• 填入包含对象、数组、字符串、数字、布尔、null 的示例。
• 示例应简短，不超过首屏太多。

Clear：

• 清空 input、output、error。
• 状态回到 idle。

Copy：

• 优先复制 output。
• 如果 output 为空但 input 有内容，不自动复制 input，避免误导。
• 复制失败时显示浏览器权限提示。

Download：

• 下载 output 为 .json。
• output 为空时 disabled。

错误类型

第一版至少处理：

JavaScript 的 JSON.parse 错误文案在不同浏览器中可能不同，因此错误类型提取要容错。第一版可以先展示通用 message，再逐步增强行列定位。

测试样例

合法样例：

{"name":"Birdor","tools":["json","jwt"],"pro":false,"count":2}

预期：Format 输出带缩进 JSON，Minify 输出紧凑 JSON，Validate 成功。

嵌套样例：

{"user":{"id":1,"roles":["admin","api"]},"meta":{"active":true,"deletedAt":null}}

预期：嵌套结构缩进正确，数组和 null 保留。

缺少逗号：

{"name":"Birdor" "tools":["json"]}

预期：进入 error，提示语法错误，保留输入。

尾随逗号：

{"name":"Birdor",}

预期：提示 JSON 不支持尾随逗号。

空输入：

预期：提示请粘贴 JSON。

指标

第一版事件：

• json_format_click
• json_minify_click
• json_validate_click
• json_parse_success
• json_parse_error
• json_copy_click
• json_download_click
• json_related_tool_click

事件不记录原始 JSON。只记录长度、成功/失败、错误类型、操作类型即可。

验收标准

• 页面可访问，metadata 正确。
• 桌面和移动端可完成 format、minify、validate。
• 非法 JSON 不清空输入。
• 常见错误有可理解提示。
• Copy、Download、Sample、Clear 可用。
• 页面明确说明本地处理。
• 相关工具和 FAQ 可见。
• 事件埋点不记录敏感输入。

非目标

第一版不做：

• AI schema 推断。
• JSON5。
• JSON Schema validate。
• 大文件 Worker。
• 批量上传。
• 登录历史。
• API endpoint。

这些能力可以进入后续版本，但不应阻塞基础工具上线。

延伸阅读

• JSON Formatter PRD
• Birdor PRD 开发 Backlog
• Birdor 首批工程 Issue
• 工具页通用组件规格
• 第三十二章：前端工具页架构
• JSON Formatter 工具页 SEO 模板

大文件处理策略

JSON Formatter 的第一版不做大文件 Worker，但需要预留策略：

预留策略意味着：第一版的代码结构应该把格式化处理封装成一个独立函数，方便后续替换为 Worker 调用。

与 YAML/XML 的复用边界

JSON Formatter 完成后，YAML 和 XML 工具可以大量复用：

复用重点是"壳"（布局、编辑器、按钮、错误面板），不是"核"（解析逻辑）。

可访问性细节

JSON Formatter 的可访问性要求：

错误恢复增强

第一版错误提示是基础，后续可以增强：

测试覆盖建议

第一版的测试不需要全覆盖，但关键路径必须有测试：

FAQ 补充

Q: JSON Formatter 是否需要支持 JSON5？
第一版不需要。JSON5 是扩展格式，用户基数远小于标准 JSON。如果后续用户反馈中频繁出现 JSON5 需求，可以作为 Pro 功能或独立工具添加。标准 JSON Formatter 应严格遵循 RFC 8259。

Q: 格式化后的 JSON 应该按字母排序吗？
不应该。JSON 对象的键顺序在 ES2015+ 中是有意义的（按插入顺序）。自动重排序可能破坏用户预期的字段排列。如果需要排序功能，作为独立的"Sort JSON"工具提供，不要在格式化中默认排序。

Q: 输入框应该支持哪些编码？
第一版假设输入是 UTF-8。如果遇到其他编码（如 GBK），应提示"检测到非 UTF-8 编码，请转换为 UTF-8 后重试"。自动编码检测会增加复杂度和体积，不建议第一版加入。

Q: 格式化输出是否应该在 URL 中可分享？
是的，这是高价值功能。可以在 URL query 中编码输入内容（或短ID引用服务端存储），用户分享链接后接收方能看到相同内容。但要注意隐私：如果包含敏感数据，应使用私密模式（不存储在可分享的 URL 中）。

Q: JSON Formatter 是否适合作为 AI 工具的训练示例？
不适合。JSON Formatter 的输出是确定性的，没有需要"智能"判断的空间。AI 的价值在于理解 JSON 的语义（如"这个 JSON 代表什么数据结构"、“如何优化这个 schema”），这些功能可以作为独立的 AI JSON Assistant 工具，不应该污染基础的 JSON Formatter。

JSON Formatter 在 CI/CD 中的集成场景

虽然 JSON Formatter 主要是一个前端网页工具，但它的格式化逻辑可以自然地延伸到 CI/CD 场景：

Birdor 的 API 版本（/v1/json/format）可以让团队把标准化格式化加入工作流，而不必在每台机器上安装 jq。

JSON 格式化性能基准

不同方案的格式化性能对比（测试数据：10MB JSON）：

前端工具的格式化因为数据量通常 < 100KB，性能差异可以忽略。关键是正确性和错误体验。

JSON Formatter 与 JSON Schema 的关联

JSON Formatter 和 JSON Schema 是互补关系：

Birdor 可以在 JSON Formatter 页面底部添加一个"验证 Schema"入口，引导用户到 JSON Schema Validator 工具，形成工作流连接。

FAQ 补充（续）

Q: 是否应该在格式化时自动排序 JSON 键？
不推荐默认排序，但可以作为选项。默认排序会破坏用户预期的字段顺序（比如 API 文档中字段有逻辑顺序）。如果用户需要排序（比如为了 diff 对比），提供一个独立的"Sort Keys"按钮。

Q: JSON Formatter 如何处理循环引用？
标准 JSON 不支持循环引用。如果用户粘贴了一个被序列化了的循环引用对象（比如用 util.inspect 输出），JSON.parse 会失败，应提示"输入包含循环引用或非标准 JSON 结构"。不要用 eval() 或自定义解析器去处理循环引用，这会带来安全问题。

Q: 格式化输出是否支持折叠/展开？
建议作为默认视图的一部分。可以折叠数组和对象，方便查看大型 JSON 的顶层结构。但如果折叠/展开的实现会增加大量 JS 体积，可以放到第二版。第一版至少提供文本输出。