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 模板