FracturedJson：让 JSON 既紧凑又可读的表格对齐格式化工具族

JSON 格式化工具几乎人人都用过，但绝大多数工具只有两种极端：要么整份”美化”成每个字段一行的竖直瀑布，要么压缩成单行。FracturedJson（GitHub: j-brooke/FracturedJson，MIT 协议）走的是中间路线：内容简单就单行内联，结构相似的若干行就按表格对齐，超长数组则每行排多个元素。本文基于官方主仓库、项目 Wiki、JS 实现与 VS Code 扩展的 README 做一手分析。

一、背景动机：美化与压缩之间的空白

标准 pretty-print 的问题是纵向膨胀：一个含几十个对象的数组，每个对象 4 个字段，就能拉出两百多行，横向扫视十分困难；而 minify 又把所有内容压成一行，肉眼无法阅读。FracturedJson 的主张是”easy for humans to read, but fairly compact”（人容易读，同时相当紧凑），用三种排版策略替代非此即彼的选择：

1. 内联（inline）：数组或对象既不太长也不太复杂时，写在单行；
2. 表格对齐（table）：若干结构相似的内联行连续出现时，字段按列对齐，像表格一样纵向可比；
3. 紧凑多行（compact multiline）：长数组每行放多个简单元素，跨越多行。

主仓库 README 给出的示例使用接近默认设置（MaxTotalLineLength=100）：SimilarArrays 里四个人的颜色数组按第二、第三列对齐；SimilarObjects 里四个怪物对象的 type、hp、loc、flags 各占一列，缺失字段（如 berserker 没有 flags、pittrap 没有 hp）留空而不是补默认值。

二、格式化模型：四个复杂度闸门

根据 VS Code 扩展 README 与 Wiki，是否内联、是否成表，由四个复杂度/长度参数共同决定：

此外还有两张”相似度”阈值：Table Object Minimum Similarity 与 Table Array Minimum Similarity（2.0.0 引入），决定相邻内联元素要多像才配成表。这意味着表格对齐不是”凡是对象就对齐”，而是先过相似度判断，再受长度与复杂度闸门约束。

对 JSON-with-comments（JSONC），3.0.0 起支持注释策略（Treat as Error / Remove / Preserve），官方 README 特别说明注释会随元素移动而跟随（“smart about keeping them with the elements to which they refer when things are moved around”）。需要注意，JS 实现 README 直言 JSON-with-comments “isn’t real JSON”，它是超集能力，不被标准 JSON 解析器接受。

三、分发形态：一个模型，五个官方实现

主仓库只承载 .NET 版本，完整分发矩阵见官方 Wiki 的 Available Versions and Ports 页面：

社区端口（官方 Wiki 列明，非官方维护）包括 JS 的 fjson-fmt、Python 的 fractured-json 与 pyfracturedjson、Rust crate fracturedjson。.NET 库提供 Reformat(string, startingDepth)（JSON 文本到 JSON 文本）与 Serialize<T>(obj, startingDepth, JsonSerializerOptions?)（对象到 JSON 文本）两个入口；JS 包对应 Reformat 与 Serialize，安装方式为 npm i fracturedjsonjs。

VS Code 扩展除整文档格式化外，还提供选区格式化、Minify JSON Document（压缩）与 Near-minify JSON Document（近压缩）：根元素的每个子项单独占一行，其余全部压缩。

四、演进中的口径：数字精度与默认值变迁

官方 Release Notes 披露过几处容易被忽略的历史口径偏差，值得单独记录：

1. 数字精度：2.x 版本会把所有数字解析为 64 位浮点数再处理，超过 16 位有效数字的数字会丢精度；3.0.0 起改为高精度数字原样保留。3.1.2 又修复了 64 位浮点溢出/下溢时被写成 Infinity 或 0（导致输出非法 JSON）的问题，现在这类数字直接沿用原文表示。
2. 数字对齐默认值：4.0.0 用 Number List Alignment 取代旧的 Don't Justify Numbers；5.0.0 把默认值从 Normalize（统一改写小数位数）改为 Decimal（按小数点对齐但原样保留写法），官方理由是”改写数字表示可能改变软件对数字的处理”。
3. 设置不向后兼容：3.0.0 大版本中大量设置项变更，旧版 2 的设置会被清空；构造器默认值保证同一主版本内稳定，追求最新默认应使用 Recommended() 工厂方法。
4. 东亚宽度：表格对齐需要测量字符串宽度，.NET 库默认用 String.Length（16 位 char 计数），对全角字符会错位；官方提供 StringLengthFunc 外接函数，建议配合 Wcwidth 库，并坦言最终是否对齐还取决于操作系统、字体与本地化。

五、客观分析：优势与局限

优势：

1. 排版策略分层清晰：内联/表格/紧凑多行三档，比”美化或压缩”二分法更贴合日志、配置、游戏数据这类半结构化文本的阅读习惯；
2. 模型与实现分离：同一格式化模型移植到 .NET、JS，浏览器页面可零安装试用，CLI 可接入脚本流水线；
3. 对脏数据谨慎：高精度数字原样保留、注释可保留可删除可报错，不擅自改写语义；
4. MIT 协议，库可直接嵌入产品。

局限（官方自述与通读可核实）：

1. 选区格式化有硬性前提：VS Code 扩展 README 明确，Format Selection 只接受完整 JSON 元素、或被方括号/花括号包起来即合法的一组元素；括号不平衡的选区无法处理；
2. 效果依赖参数调优：表格对齐高度依赖 MaxTotalLineLength，默认 100 在窄屏或超长字段上会退化为逐行展开，koala-oss 条目也建议从默认值入手逐步调整；
3. 对齐是视觉约定而非语义：列对齐不改变 JSON 数据本身，换字体、换终端、换平台后对齐可能错位（东亚宽度问题即官方自认）；
4. JSONC 非标准：带注释输出只能给人读，交回标准解析器会报错；
5. 官方实现语言集中在 .NET/JS：Python、Rust 端口均为社区维护，质量与更新节奏不由官方保证。

六、适用 / 不适用场景

适合： 阅读和对比接口返回的长数组、游戏配置与关卡数据、日志里的 JSON 片段；在 VS Code 里把 JSONC 配置整理成可读形态；用 .NET/JS 库在工具链里产出紧凑可读的调试输出。

不适合： 把格式化结果作为数据交换格式（排版纯属人读优化，应以 minify 传输）；需要严格保持列宽在所有终端一致的场景；标准 JSON 之外依赖注释做文档且要回传解析的流水线。

七、它意味着什么 / 谁该关注

FracturedJson 的价值不在”又一个美化器”，而在于把”可读性”拆成了可配置的长度、复杂度与相似度参数，让紧凑与可读可以权衡。经常和长 JSON 数组打交道的后端、游戏配置作者、日志分析人员可以先用浏览器页面试效果，再决定是否接入编辑器或脚本。

参考来源

• 官方主仓库 j-brooke/FracturedJson（README、目录结构、MIT）
• Wiki：Available Versions and Ports（官方实现与社区端口矩阵）
• Wiki：.NET Library（.NET Standard 2.0、Reformat/Serialize、宽度测量）
• FracturedJsonJs 仓库（npm fracturedjsonjs、用法示例）
• VS Code 扩展仓库 FracturedJsonVSC（功能、设置、Limitations、Release Notes）
• 在线格式化器（GitHub Pages）
• Koala 项目库条目 #1520