企业官网建设流程全解析

• 前端
• 开发工具

FeHelper（Web 前端助手）内置的 JSON 格式化工具，是面向 Web 开发者的全功能 JSON 处理面板：不仅能一键完成格式化、压缩、语法校验，还内置了 JSONP 识别、URL/Unicode 自动解码、BigInt 大数精度保护、按键排序、节点级复制/下载/编辑，以及 JSONPath 提取、表格视图与基于 Chrome 内置 Gemini Nano 的本地 AI 修复/类型生成能力。阅读本文后，你将掌握该工具的完整操作路径、每一项开关的真实作用，以及其底层"宽松解析 → BigInt 还原 → 嵌套解码 → 排序 → 安全序列化"的完整处理管线，可直接套用到自己的 JSON 调试与接口联调工作中。

一、工具定位与功能全景

JSON 格式化工具是 FeHelper 提供的核心 JSON 数据处理工具，帮助开发者快速完成 JSON 的美化（格式化）、压缩、校验、乱码解码、按键排序、BigInt 处理、JSONPath 提取与表格化阅读。它同时具备两种存在形态：

• 手动工具页：在 FeHelper 工具市场中打开独立的 JSON 格式化页面（apps/json-format/index.html），粘贴 JSON 后手动格式化；
• 页面自动格式化：通过内容脚本（apps/json-format/content-script.js）在浏览器直接访问.json接口地址时，自动把纯文本 JSON 渲染成可折叠、可高亮的树形视图，并常驻顶部工具栏。

从功能类别看，工具覆盖四大部分：

二、界面布局：Lite / Omni 双模式与左右 / 上下双布局

1. Lite 与 Omni 两种模式

工具页在apps/json-format/index.html中通过 Vue 的uiMode字段切换两种模式：

• Lite（精简模式，默认）：顶部只保留"格式化 / 压缩"主按钮、左右/上下布局切换和排序单选组，适合快速处理；
• Omni（全功能模式）：在 Lite 基础上增加完整工具栏——JSONLint、自动解码、节点编辑、嵌套解析四个开关，Uni 编码 / Uni 解码 / URL 解码三个转换按钮，以及"JSON 片段 / 在线 JSON / Mock 数据 / 工具市场"入口。

模式切换通过setUiMode()写入chrome.storage.local的JSON_FORMAT_UI_MODE键（FH_UI_MODE为全局产品模式兜底），刷新后仍然保持（见 index.js 中loadUiMode实现）。Omni 模式的解析结果区还会出现提取（JSONPath）、表格、AI三个进阶动作按钮。

2. 左右 / 上下布局

通过changeLayout(type)在left-right与up-down之间切换，并持久化到 localStorage 的local-layout-key键：

• 左右布局：输入区在左、解析结果在右，适合宽屏显示器；
• 上下布局：输入区在上、结果区在下，适合窄屏或浏览器窗口较矮的场景。

切换后页面容器会挂载layout-left-right/layout-up-down类，并调用 CodeMirror 的refresh()保证编辑器重排正确。

三、基础使用：格式化、压缩与语法校验

1. 基本操作流程

1. 在输入框（CodeMirror 编辑器，#jsonSource）粘贴待处理的 JSON 数据；
2. 点击"格式化"按钮（或直接等待自动格式化触发，见下文"实时格式化"）；
3. 解析结果展示在右侧（左右布局）或下方（上下布局），支持折叠/展开、元数据视图与纯文本 JSON 视图切换。

2. 压缩

点击"压缩"后，工具会先执行一次format()，然后把格式化结果的安全序列化文本回写到输入框，实现"一行 JSON"。该行为由compress()方法配合disableEditorChange()实现（见 index.js）。

3. JSONLint 语法校验与错误定位

默认开启的JSONLint开关（存储键jsonformat:json-lint-switch）使用 Jison 生成的严格解析器（apps/json-format/json-lint.js）。当输入不合法时，结果面板会给出：

• 精确错误位置：错误位置：N行，M列；缺少字符或字符不正确，并高亮出错片段；
• 反斜杠专项提示：当错误信息包含Invalid escape/Unexpected token/Bad escaped character且原文含\时，工具会额外提示"JSON 字符串中的反斜杠需要写成\\，例如 Windows 路径应写为\"C:\\a\\b\""；
• 原文兜底：解析失败时提供"查看原文预览"按钮，超大响应（超过 12000 字符）默认只展示前 12000 字符，避免失败态拖慢页面。

提示：格式化过程中的解析并非只走严格 JSON 解析，而是走"宽松修正"管线（见第五节），因此 JSONLint 更常用于验证修正前的原始文本是否标准。

四、高级处理功能逐个拆解

1. JSONP 自动识别与解包

在format()中，工具首先用正则/^([\w\.]+)\(\s*([\s\S]*)\s*\)$/判断输入是否为callbackName({...})形式的 JSONP：

• 匹配成功则取出callbackName（funcName），只对其中的 JSON 主体做解析；
• 格式化完成后，结果区上下会分别渲染callbackName(与)，还原完整 JSONP 形态（jfCallbackName_start/jfCallbackName_end），复制或下载时也保持完整包裹。

2. 自动解码：URL 编码 + Unicode 解码

勾选"自动解码"（存储键jsonformat:auto-decode）后，格式化流程会追加两个步骤：

1. JsonEnDecode.urlDecodeByFetch(source)：通过data:text/javascript;charset=utf8的 fetch 方式做 URL 解码，兼容各种编码场景（见 json-decode.js）；
2. JsonEnDecode.uniDecode(txt)：把\uXXXX形式的 Unicode 转义还原为可读字符。

这适合处理接口返回的被双重编码的 JSON（如日志中看到的%7B%22...%22%7D或\u5f00\u53d1之类内容）。

3. 嵌套解析：字符串中的"内嵌 JSON"

开启"嵌套解析"（存储键jsonformat:nested-escape-parse）后，工具会递归扫描对象/数组的值：

• unpackTopLevelEscapedJSON()：若顶层本身是"被转义成字符串"的 JSON，先解包一层；
• deepParseJSONStrings()：对任意字符串值尝试JSON.parse，成功且结果是对象/数组的，递归展开成真实节点。

这对"接口把整个 JSON 当字符串塞在字段里"的场景非常有效。若开启后反而解析失败（例如普通字符串被误判），结果区会提供"关闭嵌套解析后重试"的一键降级按钮。

4. BigInt 大数精度保护（重点）

JSON 标准数字在 JavaScript 中受Number双精度限制，超过 15 位精度的整数（如995815895020119788889）会被舍入失真。本工具通过双保险解决：

• 解析侧：parseWithBigInt()（见 format-lib.js 与 json-auto-utils.js）先把引号外16 位及以上的整数字面量标记为"__BigInt__xxx"，再用JSON.parse的 reviver 还原为原生BigInt；15 位及以下保持number，不引入额外开销；
• 序列化侧：safeStringify()用占位符策略（__FH_BIGINT__、__FH_NUMSTR__、__FH_BIGNUM__）让 BigInt、科学计数法大数、json-bigint 的{s,e,c}结构都还原为不带引号的纯数字文本，保证"格式化后能再次被解析且不丢精度"；
• 排序侧：JsonABC.sortObj显式跳过JSON.BigNumber实例，避免大数对象参与字符串比较导致意外结果（见 json-abc.js）。

对应回归测试见 test/json-utils.test.js：验证了 16 位及以上整数、负大整数、科学计数法、BigNumber duck-type 还原等场景（{"id": 995815895020119788889}解析后等于BigInt('995815895020119788889')）。

5. 节点编辑

开启"节点编辑"开关（存储键jsonformat:edit-on-click）后，点击格式化结果中的任意节点，该节点文本会回填到输入框（通过window._OnJsonItemClickByFH回调），方便对单个片段做再处理。此外每个节点悬停时提供三个操作：

• 复制：仅复制当前节点（含其子节点）的 JSON；
• 下载：把当前节点片段下载为FeHelper-时间戳.json（优先走chrome.downloads，沙盒环境降级为弹窗展示原文）；
• 删除：从结果树中删除当前节点。

6. 按键排序

排序单选组支持三种模式（Omni 与 Lite 均有）：

排序由JsonABC.sortObj(jsonObj, parseInt(sortType), true)执行（第三个参数noarray=true表示不排序数组内部顺序，仅排序对象键），且选择后立即触发format()重新渲染。

五、编码转换按钮

Omni 工具栏提供三个转换按钮，作用对象都是输入框全文：

• Uni 编码：JsonEnDecode.uniEncode()把中文、符号等转为\uXXXX（保留{}[]:,"等 JSON 结构字符，见 json-decode.js 中的白名单替换逻辑）；
• Uni 解码：JsonEnDecode.uniDecode()把\uXXXX还原为原始字符；
• URL 解码：JsonEnDecode.urlDecodeByFetch()对全文做 URL 解码，适合处理%编码的报文。

六、JSONPath 提取与表格视图

解析成功且结果是对象/数组时，结果区右上角出现两个进阶入口：

1. JSONPath 提取

点击"提取"打开查询弹窗，支持一套内置 JSONPath 引擎（queryJsonPath/evaluateJsonPath，见 index.js），内置示例包括：

$ 根对象 $.data 获取 data 属性 $.data.* 获取 data 下所有属性 $.data[0] data 数组第一个元素 $.data[*] data 数组所有元素 $.data[?(@.name)] 过滤：有 name 属性的元素 $..name 递归查找所有 name 属性 $.data[0:3] 数组切片前 3 个元素 $.data[-1] 最后一个元素（负索引）

查询结果以表格列出（序号 / Path / 类型 / 值预览），并支持复制值 JSON、复制路径、复制明细 JSON、下载 JSON；单个结果行也可单独复制路径或值。文件名会根据表达式自动生成（如$.data.items[*].name→jsonpath_data_items__name.json）。

2. 表格视图

点击"表格"（openTableViewModal+ table-utils.js）把 JSON 转成更易阅读的表格：

• 数组型数据 →网格表格（列 = 字段，行 = 数组元素，并展示来源路径$...）；
• 单对象数据 →键值对表格（字段 / 值）。

七、本地 AI 能力：修复、体检与类型生成

解析结果区集成基于Chrome 内置 Gemini Nano（本地执行，不会静默上传云端）的 AI 动作（详见 index.js 中JSON_DERIVED_AI_TASKS与 test/json-format-ai-actions.test.js）：

• AI 修复：仅当解析失败时出现，AI 解释错误原因、定位可疑位置并生成可应用的合法 JSON；应用前会用本地parseWithBigInt再次校验，且要求输入快照未变化，防止误覆盖；
• 结构体检：扫描根类型、节点数、nullable 字段、数组可选字段、类型不稳定字段、混合数组、超深嵌套（>6 层）等，输出"结论 / 风险字段 / 建议"；
• TS 类型：根据样例保守推断并生成可复制到项目中的ts类型定义（根类型Root）；
• JSON Schema：按 JSON Schema Draft 2020-12 生成，required只包含样例中稳定出现的字段；
• Zod Schema：生成import { z } from "zod"风格的可复用校验代码（RootSchema+type Root = z.infer<typeof RootSchema>）。

AI 可用性通过AI.getBuiltInAvailability()检测，状态包括checking / unsupported / unavailable / downloadable / downloading / available；模型未就绪时面板会明确提示"FeHelper 不会在本地模型不可用时把 JSON 自动发送到云端"。

八、页面自动格式化与可配置项

在浏览器中直接打开.json接口地址时，apps/json-format/content-script.js会接管页面并注入自动格式化 UI。其行为由后台脚本 apps/background/background.js 中requestJsonformatOptions维护的一组默认配置驱动：

自动格式化页面的皮肤主题定义在 content-script.js 的SKIN_THEME中：0默认、1simple、2light、3dark、4vscode、5github、6vegetarian。后台脚本还内置了配置迁移逻辑（FH_JSONFORMAT_DEFAULTS_MIGRATED/FH_JSONFORMAT_FIX_ENCODING_RESTORED标记），老用户升级后自动补全新默认值，相关行为由 test/json-format-settings.test.js 回归守护。

九、底层原理：一条完整的"解析 → 转换 → 渲染"管线

从源码看，手动工具页一次格式化的完整链路为（index.js 的format()→ format-lib.js 的Formatter.format()）：

1. 宽松修正：normalizeLooseJSONSource()只把引号外的单引号键、裸键（如{name: "x"}）补成标准双引号，不破坏字符串内部内容；
2. JSONP 解包：提取funcName(...)中的主体；
3. BigInt 安全解析：parseWithBigInt()标记大整数 → reviver 还原 BigInt；
4. 嵌套转义解析（可选）：unpackTopLevelEscapedJSON/deepParseJSONStrings递归展开字符串内嵌 JSON；
5. 排序（可选）：JsonABC.sortObj按键升/降序重排；
6. 安全序列化：safeStringify()用占位符技术输出不丢精度的文本；
7. 编码还原（可选）：URL 解码 + Unicode 解码；
8. 异步渲染：优先创建Worker（apps/json-format/json-worker.js）异步渲染大 JSON，遇到 CSP 限制、沙盒环境或 5 秒超时自动回退到同步formatSync，保证任何环境下都能出结果。

渲染结果支持折叠/展开全部节点、元数据/纯文本视图切换、全文复制，以及基于节点的多语言 JSONPath 提示（JavaScript / PHP / Python / Java / C# / Go / Ruby / Swift 八种语言格式，见 format-lib.js 的_formatJsonPath），选中即得可直接粘贴的取值代码。

十、使用技巧与注意事项

• 快速格式化：输入框内容变化即自动触发格式化（editor.on('change')→this.format()），无需手动点击；在自动格式化页面上，Ctrl + A可全选格式化结果，Ctrl + C直接复制全文，Esc退出选择态；
• 大 JSON 处理：建议用"压缩"模式减小体积；自动格式化页面受MAX_JSON_KEYS_NUMBER（默认 10000）保护，超限不渲染避免卡死；
• 编辑安全：手动编辑节点时注意保持 JSON 合法性；若输入含未转义反斜杠（如 Windows 路径C:\a\b），必须先写成C:\\a\\b，否则 JSONLint 会报Invalid escape；
• 自动解码前提：确保原始数据确实是 URL / Unicode 编码过的，对普通文本开启会改变原文语义；
• BigInt 精度：数值超过 15 位时以bigint类型处理，复制出的仍是纯数字文本；排序时大数不参与键排序，避免{s,e,c}结构被误比较；
• 嵌套解析取舍：接口把 JSON 当字符串返回时开启；普通字符串场景若解析异常，可一键关闭重试。

十一、常见问题

Q: 为什么我的 JSON 格式化后显示错误？A: 请先检查原始数据是否符合标准格式：键名必须用双引号包围、不能使用单引号、不能有多余逗号、括号必须配对；若原文含反斜杠，需要双写转义。JSONLint 会给出精确的行列位置。

Q: 如何处理包含特殊字符的 JSON？A: 使用工具栏的"Uni 编码"把特殊字符转为\uXXXX；对已编码数据使用"自动解码"或"Uni 解码 / URL 解码"还原。

Q: 为什么我的 BigInt 数据格式化后发生了变化？A: 正常情况下不会——工具对 16 位及以上整数全程以 BigInt 处理并在序列化时还原为纯数字文本；若仍发现变化，请确认原始数据本身就是字符串化的数字，或数据在进入工具前已被其他程序截断。

Q: JSONP 数据能直接格式化吗？A: 可以。工具自动识别callback({...})形态并剥离方法名，格式化结果会以callback(+ 格式化 JSON +)的形式完整还原。

Q: AI 按钮什么时候出现？A: "AI 修复"仅在解析失败时出现；"结构体检 / TS 类型 / Schema / Zod"仅在解析成功且使用 Chrome 内置 Gemini Nano（本地可用）时出现，默认不联网上传数据。

十二、相关工具

• JSON 比对工具：比较两个 JSON 数据的差异，定位结构变更；
• 代码美化工具：支持多种编程语言的代码格式化；
• 信息编码转换：支持多种编码格式的转换，与本文的 Uni/URL 解码互补。

• 前端
• 开发工具