Skip to content

Latest commit

 

History

History
422 lines (336 loc) · 10.4 KB

File metadata and controls

422 lines (336 loc) · 10.4 KB

JSON Formatter & Validator - 产品需求文档 (PRD)

1. 项目概述

1.1 产品定位

打造一个现代化、高性能的在线 JSON 工具,提供格式化、验证、编辑等核心功能,界面采用酷炫现代的配色方案,提供极致的用户体验。

1.2 目标用户

  • 前端/后端开发者
  • API 测试工程师
  • 数据分析师
  • 任何需要处理 JSON 数据的技术人员

1.3 核心价值

  • 即时响应:本地处理,无需上传到服务器
  • 强大功能:格式化、压缩、验证、编辑一体化
  • 现代设计:酷炫配色,流畅动画,极致体验
  • 安全隐私:所有数据本地处理,不存储任何信息

2. 核心功能需求

2.1 JSON String ↔ JSON Object 双向转换 (P0 - 最高优先级)

2.1.1 JSON String → JSON Object (解析 & 格式化)

功能描述

  • 将压缩的 JSON 字符串解析并转换为易读的格式化形式
  • 支持自定义缩进(2空格、4空格、Tab)
  • 实时格式化,输入即响应
  • 智能识别输入类型(JSON 字符串 vs JSON 对象)

交互流程

  1. 用户在左侧输入区粘贴/输入压缩的 JSON 字符串
  2. 系统自动检测、解析并格式化
  3. 右侧显示区展示格式化后的 JSON 对象
  4. 提供一键复制功能

输入示例

"{\"name\":\"John\",\"age\":30,\"city\":\"New York\"}"

输出示例

{
  "name": "John",
  "age": 30,
  "city": "New York"
}

2.1.2 JSON Object → JSON String (字符串化)

功能描述

  • 将 JSON 对象转换为 JSON 字符串格式
  • 保留转义字符(引号、换行等)
  • 支持格式化或压缩模式

交互流程

  1. 用户在左侧输入区粘贴/输入 JSON 对象
  2. 点击"To String"按钮
  3. 右侧显示区展示转换后的 JSON 字符串
  4. 字符串带有完整的转义字符

输入示例

{
  "name": "John",
  "age": 30
}

输出示例

"{\"name\":\"John\",\"age\":30}"

技术要求

  • 响应时间 < 100ms(对于 < 1MB 的 JSON)
  • 支持大文件(10MB+)的处理
  • 错误处理:格式错误时高亮错误位置
  • 自动识别输入是 JSON String 还是 JSON Object

2.2 JSON 验证 (P0)

功能描述

  • 实时语法验证
  • 精确定位错误位置(行号、列号)
  • 友好的错误提示信息

错误提示要求

  • 显示错误类型(语法错误、意外字符等)
  • 高亮错误行
  • 提供修复建议(如缺少逗号、引号等)

2.3 JSON 压缩/Minify (P0)

功能描述

  • 移除所有空白字符
  • 生成最小化的 JSON 字符串
  • 显示压缩前后大小对比

输出信息

  • 原始大小
  • 压缩后大小
  • 压缩率百分比

2.4 JSON 美化与语法高亮 (P0)

功能描述

  • 语法高亮显示
    • 键名:蓝色/青色
    • 字符串值:绿色
    • 数字:橙色
    • 布尔值:紫色
    • null:红色
    • 括号/逗号:灰色
  • 支持暗色/亮色主题切换

2.5 折叠/展开功能 (P1 - 高优先级)

功能描述

  • 支持对象和数组的折叠/展开
  • 点击行首的折叠图标进行操作
  • 记住用户的折叠状态

交互细节

  • 折叠时显示 {...}[...]
  • 显示折叠内容的项目数量
  • 支持全部展开/全部折叠快捷操作

2.6 JSON 编辑功能 (P1)

功能描述

  • 直接在界面上编辑 JSON 值
  • 支持添加/删除键值对
  • 支持拖拽排序(可选)

编辑功能

  • 双击值进行编辑
  • 自动类型识别(字符串、数字、布尔)
  • 实时验证编辑后的 JSON 合法性

2.7 搜索与过滤 (P1)

功能描述

  • 支持按键名搜索
  • 支持按值搜索
  • 高亮搜索结果
  • 支持正则表达式搜索

2.8 JSONPath 查询 (P2 - 中等优先级)

功能描述

  • 提供 JSONPath 输入框
  • 支持常用的 JSONPath 语法
  • 高亮匹配的节点

示例

  • $.store.book[*].title - 获取所有书名
  • $..price - 获取所有价格

2.9 JSON 转换功能 (P2)

功能描述

  • JSON ↔ XML
  • JSON ↔ YAML
  • JSON ↔ CSV(针对数组)
  • JSON 转代码(生成 TypeScript/JavaScript interface)

2.10 历史记录 (P0 - 最高优先级)

功能描述

  • 使用 localStorage 本地存储最近处理的 JSON
  • 最多保存 10 条记录(超出自动删除最旧记录)
  • 可快速加载历史记录
  • 支持搜索历史记录
  • 支持删除单条或清空全部历史

存储信息

  • JSON 内容(截取前 100 字符作为预览)
  • 时间戳
  • 文件大小
  • 验证状态(Valid/Invalid)

交互设计

  • 侧边栏显示历史记录列表
  • 每条记录显示:时间、预览、大小
  • 点击历史记录快速加载到编辑器
  • 支持右键菜单:删除、清空全部

隐私保护

  • 提供"隐私模式"选项,开启后不保存历史
  • 提供"一键清除历史"功能
  • 关闭浏览器时可选择是否保留历史

2.11 文件操作 (P1)

功能描述

  • 支持拖拽上传 JSON 文件
  • 支持导出为 .json 文件
  • 支持从 URL 加载 JSON

3. 界面设计要求

3.1 布局结构

+----------------------------------------------------------+
|  [Logo] JSON Formatter & Validator          [主题] [设置] |
+----------------------------------------------------------+
|  [工具栏] Format | Minify | Validate | Clear | Copy      |
+----------------------------------------------------------+
|                    |                                      |
|                    |                                      |
|   输入区域          |        输出/显示区域                  |
|   (Monaco Editor)  |        (语法高亮显示)                 |
|                    |                                      |
|                    |                                      |
+--------------------+--------------------------------------+
|  状态栏: Lines: 120 | Size: 3.2KB | Valid ✓              |
+----------------------------------------------------------+

3.2 配色方案(现代酷炫)

暗色主题(默认)

  • 背景色

    • 主背景:#0a0e27 (深蓝紫黑)
    • 编辑器背景:#1a1f3a
    • 侧边栏:#0f1229
  • 强调色

    • 主色:#00d4ff (霓虹蓝)
    • 次要色:#ff006e (霓虹粉)
    • 成功色:#00ff9f (霓虹绿)
    • 警告色:#ffb800 (霓虹黄)
    • 错误色:#ff3366 (霓虹红)
  • 文本色

    • 主文本:#e0e6ff
    • 次要文本:#8892b0
    • 键名:#00d4ff
    • 字符串:#00ff9f
    • 数字:#ffb800
    • 布尔值:#ff006e
    • null:#ff3366
  • 边框/分隔线

    • 边框:rgba(0, 212, 255, 0.2)
    • 悬停:rgba(0, 212, 255, 0.5)

亮色主题(可选)

  • 背景色

    • 主背景:#f5f7ff
    • 编辑器背景:#ffffff
  • 强调色

    • 主色:#0066ff
    • 次要色:#ff0055
    • 成功色:#00c896

3.3 动画效果

  • 按钮悬停:轻微放大(scale: 1.05)+ 发光效果
  • 主题切换:平滑过渡(transition: 0.3s)
  • 错误提示:从右侧滑入
  • 加载状态:霓虹脉冲动画
  • 折叠/展开:平滑高度过渡

3.4 响应式设计

  • 桌面端(> 1024px):双栏布局
  • 平板端(768px - 1024px):双栏布局,缩小间距
  • 移动端(< 768px):单栏布局,顶部切换输入/输出

4. 技术性能要求

4.1 性能指标

  • 首屏加载:< 2s
  • 格式化响应:< 100ms(1MB 内)
  • 支持文件大小:最大 10MB
  • 内存占用:< 100MB

4.2 兼容性

  • Chrome 90+
  • Firefox 88+
  • Safari 14+
  • Edge 90+

4.3 可访问性

  • 支持键盘快捷键
  • 符合 WCAG 2.1 AA 标准
  • 屏幕阅读器友好

5. 用户体验细节

5.1 快捷键

  • Ctrl/Cmd + F:格式化
  • Ctrl/Cmd + M:压缩
  • Ctrl/Cmd + K:清空
  • Ctrl/Cmd + C:复制结果
  • Ctrl/Cmd + V:粘贴到输入区
  • Ctrl/Cmd + Z:撤销
  • Ctrl/Cmd + Shift + F:搜索

5.2 错误处理

  • 网络错误:友好提示 + 重试按钮
  • 解析错误:精确定位 + 修复建议
  • 文件过大:提示压缩或分片处理

5.3 引导提示

  • 首次访问:简短的功能介绍
  • 空状态:提示可以粘贴 JSON 或拖拽文件
  • 示例数据:提供示例 JSON 快速体验

6. 数据安全与隐私

6.1 隐私保护

  • 所有处理均在本地浏览器完成
  • 不上传任何数据到服务器
  • 历史记录仅保存在本地 localStorage

6.2 敏感数据处理

  • 提供"隐私模式"选项,不保存历史记录
  • 提供一键清除所有本地数据功能

7. 未来扩展功能(V2.0)

7.1 协作功能

  • 生成分享链接(加密后的 JSON)
  • 实时协作编辑

7.2 高级功能

  • JSON Schema 验证
  • JSON Diff 对比
  • 批量处理多个 JSON 文件
  • API 测试功能(发送 JSON 请求)

7.3 集成功能

  • VS Code 插件
  • Chrome 扩展
  • CLI 工具

8. 成功指标

8.1 功能指标

  • JSON 格式化准确率:100%
  • 错误定位准确率:> 95%
  • 功能可用性:> 99.9%

8.2 性能指标

  • 平均响应时间:< 50ms
  • 页面加载时间:< 1.5s
  • 用户留存率:> 40%(7日)

8.3 用户满意度

  • 界面美观度评分:> 4.5/5
  • 功能完整性评分:> 4.3/5
  • 整体满意度:> 4.4/5

9. 项目里程碑

Phase 1 - MVP(2周)

  • ✅ 基础 UI 框架搭建
  • ✅ JSON 格式化功能
  • ✅ JSON 验证功能
  • ✅ 语法高亮
  • ✅ 压缩功能
  • ✅ 暗色主题

Phase 2 - 增强(1周)

  • ✅ 折叠/展开功能
  • ✅ 搜索功能
  • ✅ 文件上传/下载
  • ✅ 历史记录
  • ✅ 亮色主题

Phase 3 - 优化(1周)

  • ✅ 性能优化
  • ✅ 错误提示优化
  • ✅ 动画效果
  • ✅ 响应式设计
  • ✅ 快捷键支持

Phase 4 - 扩展(可选)

  • JSON 转换功能
  • JSONPath 查询
  • 编辑功能

10. 风险与挑战

10.1 技术风险

  • 大文件处理:可能导致浏览器卡顿

    • 解决方案:虚拟滚动 + Web Worker
  • 跨浏览器兼容性:不同浏览器的性能差异

    • 解决方案:充分测试 + Polyfill

10.2 用户体验风险

  • 学习曲线:功能过多可能让新用户困惑
    • 解决方案:渐进式引导 + 默认简洁模式

附录:参考资料

  1. 设计参考

  2. 代码参考

  3. 技术文档

    • JSON RFC 8259
    • Monaco Editor API
    • JSONPath 规范