# json-lens

**Repository Path**: lkg/json-lens

## Basic Information

- **Project Name**: json-lens
- **Description**: JSON 数据可视化分析工具，支持 JSON 格式化、结构树查看、TypeScript 类型生成和 Schema 转换，帮助开发者快速理解复杂 JSON 数据结构。
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-08-25
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# JSON Lens

纯前端 JSON 数据可视化工具 —— 粘贴即解析，结构树、字段定位、多语言转换一站式完成。

![输入图片说明](public/json.png)

![React](https://img.shields.io/badge/React-18.3-61dafb)
![Vite](https://img.shields.io/badge/Vite-4.5-646cff)
![TypeScript](https://img.shields.io/badge/TypeScript-5.4-3178c6)
![Node](https://img.shields.io/badge/Node-14%2B-339933)
![License](https://img.shields.io/badge/License-MIT-green)

在线预览：http://json.systempro.site

## 项目简介

JSON Lens 是一个面向开发者的 Web 端 JSON 数据与结构查看工具。把一段 JSON 贴进去，它会同时给你三种互补的视角——格式化代码、可折叠结构树、字段信息面板，并内置一组常用转换工具（Schema / TypeScript / Java / Go 生成、Diff、统计、JSONPath 提取、转义等）。

项目为纯前端应用，无后端、无数据库、不收集任何用户数据：所有解析、格式化、转换都在浏览器本地完成，刷新即清空。

适用场景：

- 快速校验接口返回的 JSON 是否合法，并定位报错行号
- 在复杂嵌套结构中查找某个字段、查看其类型与取值
- 把 JSON 一键转换为 TypeScript 接口 / Java 类 / Go 结构体，直接用于编码
- 对比两份 JSON 的差异、抽取同类字段、生成 Schema

## 功能特性

- 多视图联动：格式化代码 + 结构树 + 字段信息面板，三处点击互相定位
- 结构树虚拟滚动：基于 react-window，万级节点依旧流畅；数组超过 50 项自动折叠，可一键展开
- 字段信息面板：查看选中字段的类型、深度、出现次数、示例值；一键复制 JSONPath（通配 / 索引两种写法）并定位到原文
- 大文件友好：导入时自动清理 BOM、零宽字符、全角标点等脏数据；解析报错回显行号与列号
- 工具箱：JSON 压缩、Schema 生成、TypeScript 接口生成、Java 类生成、Go 结构体生成、结构分析、JSONPath 字段提取、JSON Diff、统计信息、转义 / 反转义、复制、下载
- 模块放大：格式化代码与结构树均支持全屏放大查看
- 零后端：数据只在浏览器本地处理，不上传任何服务器

## 技术栈

| 分类 | 选型 | 说明 |
| --- | --- | --- |
| 构建 | Vite 4.5 | 兼容 Node 14 的最后一个大版本 |
| 框架 | React 18.3 + TypeScript 5.4 | |
| 编辑器 | Monaco Editor 0.45 | VS Code 同款编辑器，Worker 已自包含打包 |
| 虚拟列表 | react-window 1.8 | 结构树虚拟滚动 |
| Diff | diff 5.2 | JSON 对比 |
| 样式 | 轻量 CSS（CSS 变量） | 不引入 Tailwind，避免额外构建负担 |

版本约束：本项目刻意锁定在 Node 14.21.x 兼容的依赖版本（Vite 5 / Tailwind 4 / @xyflow/react 12 均要求 Node ≥18，已排除）。更高版本的 Node 可正常构建，依赖本身无需升级系统 Node。

## 环境要求

- Node.js ≥ 14.21.x（推荐 14.21.x；更高版本亦可）
- npm 随 Node 自带，无需升级全局 npm

## 快速开始

```bash
# 1. 克隆仓库
git clone https://gitee.com/sitepulse/json-lens.git
cd json-lens

# 2. 安装依赖（仅当前项目目录，不影响其他项目）
npm install

# 3. 启动本地开发服务（默认 http://localhost:5173）
npm run dev

# 4. 生产构建，产物输出到 dist/
npm run build

# 5. 本地预览构建产物（默认 http://localhost:4173）
npm run preview
```

可用脚本：

| 命令 | 作用 |
| --- | --- |
| `npm run dev` | 启动 Vite 开发服务器，支持热更新，用于本地开发调试 |
| `npm run build` | 执行生产构建，将应用打包为静态文件输出到 `dist/` |
| `npm run preview` | 以静态方式预览 `dist/` 构建产物（不重新打包） |
| `npm run typecheck` | 仅做 TypeScript 类型检查（`tsc --noEmit`），不产出文件 |

提示：若 `npm run dev` 出现 504 / Outdated Optimize Dep 类依赖缓存报错，删除 `node_modules/.vite` 目录后重新启动即可。

## 目录结构

```
json-lens/
├─ index.html              # 应用入口 HTML
├─ package.json           # 依赖与脚本
├─ vite.config.ts         # Vite 配置（base 设为 './' 便于静态部署）
├─ tsconfig.json          # TypeScript 配置
├─ public/
│  └─ json.png            # README 宣传图
├─ .gitignore
└─ src/
   ├─ main.tsx            # 渲染入口
   ├─ App.tsx             # 顶层布局与状态
   ├─ monaco-setup.ts     # Monaco Worker 自包含配置
   ├─ vite-env.d.ts
   ├─ styles/
   │  └─ global.css       # 全局样式（轻量 CSS 变量体系）
   ├─ components/         # UI 组件
   │  ├─ Header.tsx        # 顶部栏
   │  ├─ JsonInput.tsx     # JSON 输入区（粘贴 / 导入 / 示例 / 格式化 / 解析）
   │  ├─ MonacoEditor.tsx  # Monaco 编辑器封装
   │  ├─ FormatPanel.tsx   # 格式化代码视图（支持放大）
   │  ├─ TreeView.tsx      # 结构树（虚拟滚动 + 字段信息面板）
   │  ├─ Toolbox.tsx       # 底部工具箱
   │  ├─ Modals.tsx        # 各工具弹窗
   │  ├─ Modal.tsx         # 通用弹窗
   │  └─ StatusBar.tsx     # 状态栏（长度 / 大小 / 节点数）
   └─ lib/                # 纯逻辑库（无 UI 依赖）
      ├─ jsonUtils.ts      # JSON 解析 / 类型判断 / 格式化
      ├─ tree.ts           # 结构树构建
      ├─ formatWithPos.ts  # 带行号定位的格式化
      ├─ fileImport.ts     # 文件导入（BOM / 脏字符清理 + 报错定位）
      ├─ schema.ts         # JSON Schema 生成
      ├─ tsInterface.ts    # TypeScript 接口生成
      ├─ javaClass.ts      # Java 类生成
      ├─ goStruct.ts       # Go 结构体生成
      ├─ jsonpath.ts       # JSONPath 字段提取
      ├─ escape.ts         # 转义 / 反转义
      ├─ structAnalysis.ts # 结构分析
      ├─ stats.ts          # 统计信息
      ├─ download.ts       # 文件下载
      ├─ toast.ts          # 轻提示
      ├─ sample.ts         # 内置示例 JSON
      └─ types.ts          # 公共类型
```

## 部署

项目为纯静态站点，`npm run build` 后 `dist/` 即为可托管产物，可部署到任意静态服务器。

### Gitee Pages

1. 执行 `npm run build` 生成 `dist/`
2. 将 `dist/` 提交到仓库（或使用 CI 自动构建）
3. 在仓库 服务 → Gitee Pages 中：
   - 部署分支：选择包含 `dist/` 的分支（如 `main`）
   - 部署目录：选择 `/dist`
   - 点击「启动」

由于 `vite.config.ts` 中 `base` 已设为 `'./'`，部署到 `https://<用户名>.gitee.io/<仓库名>/` 子路径时资源路径自动相对化，无需额外配置。

### 其他静态托管

Nginx / GitHub Pages / Cloudflare Pages / 任意对象存储 + CDN 均可直接托管 `dist/` 目录，无需服务端渲染或接口。

## 开源协议

本项目基于 MIT 协议开源，可自由用于学习、修改与商用，请保留原始版权声明。

## 说明与边界

- 关系图（力导向可视化）当前版本未包含，专注「代码 + 结构树 + 字段信息」三视图。
- 超大 JSON（建议 5MB 以内）解析体验最佳；更大文件建议先精简或折叠深层结构。
- 所有处理均在浏览器本地完成，刷新页面后数据即清空，不会持久化。