你一定遇到过这种情况：复制一段 JSON 粘进格式化工具，点"格式化"直接炸出一大坨红色错误信息"Invalid JSON"。仔细看才发现，是因为复制时带上了 HTML 实体、或者转义字符被转义了两次、或者JSON 里包含了不能直接粘贴的反斜杠。

这篇文章把 JSON 工具链里的高频坑按「JSON 格式化 / 校验」「JSON 转 Java 实体」「JSON 转其他格式」三类梳理一遍，配合在线工具让你 3 分钟内定位问题。

第一类：JSON 格式化/校验高频坑

坑 1：转义字符"双重转义"

从 Java 字符串里复制 JSON：

String json = "{\n  \"name\": \"test\",\n  \"desc\": \"这是个\\\"示例\\\"\"\n}";

复制出来变成：

{\n  \"name\": \"test\",\n  \"desc\": \"这是个\\\"示例\\\"\"\n}

正确做法：直接粘进 JSON 格式化工具——它先尝试标准解析，失败后自动按 Java 字符串字面量反转义再试一次，不需要手动点按钮。很多在线 JSON 工具没有这层回退，粘进去只会报 Invalid JSON。

坑 2：HTML 实体污染

从 Markdown 或邮件里复制，有时会把 " 也复制进来：

{"name": "test", "age": 18}

JSON 里不能直接出现 HTML 实体。需要先做 HTML 实体解码 再粘进工具。

坑 3：BOM / 零宽字符

从某些编辑器（Windows 记事本、带 BOM 选项的 VS Code）得到的 JSON 会带 UTF-8 BOM 前缀（3 字节 EF BB BF），肉眼完全看不见，但 JSON 解析器会在第一个字符就报错。JSON 格式化工具 会自动跳过 BOM；零宽空格（U+200B）目前不处理，遇到"看起来完全正常却解析失败"时，可以复制到十六进制编辑器确认有没有不可见字符。

第二类：JSON 转 Java 实体高频坑

坑 1：数组字段类型推断

{"tags": ["java", "spring"], "scores": [95, 87, 92]}

tags 是字符串数组、scores 是整数数组——大部分工具能识别。但如果数组里混合类型：

{"data": [1, "hello", null]}

混合数组推断不出统一的元素类型，JSON 转 Java 实体工具 直接把字段生成为 List<Object>，并在字段上注释说明。反序列化后元素是 LinkedHashMap，需要时按业务 instanceof 后强转。

如果这些元素其实是结构不同但有明确分类的对象（比如消息列表里的文本、图片、链接消息），更好的做法是定义 List<Parent> 配合 Jackson 的 @JsonSubTypes 做多态反序列化——前提是 JSON 里带类型标识字段，工具不会自动生成。

坑 2：日期字段类型推断

{"createTime": "2026-10-29T10:30:00Z", "expireTime": 1794012800000}

第一个是 ISO 8601 字符串、第二个是毫秒时间戳——JSON 转 Java 实体工具 会把两者分别生成为 String 和 Long，不做日期类型推断。确实需要时间字段时，手动把 String 改成 LocalDateTime 并按格式补 @JsonFormat；别指望自动推断，它在 "2026/10/29" 这类非标准格式上并不可靠。

坑 3：字段名与 Java 驼峰

JSON 用下划线命名 user_name、create_time，Java 用驼峰 userName、createTime。JSON 转 Java 实体工具 会自动转驼峰，并在字段名发生变化时补一行 @JsonProperty 保留原始 key。字段名里有特殊字符（"2fa_enabled"、"user.name"、"user-id"）时，Java 字段名不能以数字开头、不能带 . 和 -，工具会改名并加注解映射——生成后建议扫一眼字段名是否符合预期。

坑 4：未知字段怎么办

生成的实体类能不能忽略 JSON 里的未知字段（@JsonIgnoreProperties(ignoreUnknown = true)）？默认不处理的话，JSON 多了字段反序列化直接报错。JSON 转 Java 实体工具 不输出这个注解，需要的话在类声明上手动补一行。

第三类：格式互转（JSON ↔ YAML / XML）

这类坑主要是注释和锚点：

  • YAML 里的 # 注释 转 JSON 会丢失（JSON 没注释语法），YAML 的锚点 & 和引用 * 转 JSON 会展开成对象
  • XML 转 JSON 时根节点怎么处理（要不要去掉外层 <root> 包装）

工具链配合

原始 JSON
  │
  ▼
[JSON 格式化工具] ─── 自动反转义 / 跳过 BOM / 校验
  │
  ├──→ [JSON 转 Java 实体] ──→ 生成 Jackson 风格实体，自动驼峰转换
  │
  ├──→ [JSON 转 TypeScript] ──→ 生成 interface 定义
  │
  ├──→ [JSON 转 Go] ──→ struct + json tag
  │
  └──→ [JSON 转 SQL] ──→ INSERT INTO 语句

同一份样本 JSON，按需选不同方向的工具转换；各工具互相独立，切换方向时需要重新粘贴一次样本。

常见坑

  • "格式化后中文变乱码"：JSON 是 UTF-8，粘入时编码对不上就乱码。格式化工具应强制 UTF-8 输入输出。
  • "转义了双引号还是报错"：JSON 里的转义只针对 "、\、控制字符，' 不需要转义。
  • "实体加了字段反序列化却报 UnknownProperty"：反序列化开启了严格模式（FastJSON supportSmartMatch=false 或 Jackson 默认严格）。生成的实体类顶上按需补一行 @JsonIgnoreProperties(ignoreUnknown = true)。

相关工具与速查