如何验证 JSON：完整指南与示例

JSON（JavaScript 对象表示法）是现代 Web API、配置文件和数据交换的基石。但无效的 JSON 会导致应用程序崩溃、API 集成失败，并造成数小时的调试困扰。本指南将带你了解验证 JSON 所需的一切知识，从基本语法检查到使用真实示例的高级 Schema 验证。

为什么 JSON 验证很重要

无效的 JSON 是 Web 应用程序中最常见的错误来源之一。一个放错位置的逗号、一个未加引号的键或一个尾随逗号都可能导致 JSON.parse() 抛出 SyntaxError，从而使整个数据管道崩溃。验证可以在这些错误传播到系统并造成下游故障之前及早捕获它们。

除了语法正确性之外，验证还确保 JSON 数据符合预期的结构。API 可能返回有效的 JSON，但缺少必需字段、数据类型错误或值超出可接受范围。Schema 验证解决了这些结构性问题。

JSON 语法规则

在深入了解验证工具之前，理解使 JSON 有效的规则至关重要。JSON 具有由 RFC 8259 定义的严格语法，即使单个字符违规也会使整个文档无效。

字符串必须使用双引号

所有字符串值和对象键必须用双引号括起来。单引号不是有效的 JSON 字符串分隔符，这是从 JavaScript 转来的开发者常犯的错误。

// Invalid - single quotes
{'name': 'Alice', 'age': 30}

// Valid - double quotes
{"name": "Alice", "age": 30}

对象键必须加引号

与 JavaScript 对象字面量不同，JSON 要求所有对象键都用双引号括起来。未加引号的键是语法错误。

// Invalid - unquoted keys
{name: "Alice", age: 30}

// Valid - quoted keys
{"name": "Alice", "age": 30}

不允许尾随逗号

JSON 不允许在对象或数组的最后一项后有逗号。这是另一个常见错误，特别是在手动编辑 JSON 时。

// Invalid - trailing comma
{
  "name": "Alice",
  "age": 30,
}

// Valid - no trailing comma
{
  "name": "Alice",
  "age": 30
}

不支持注释

JSON 不支持注释。// 单行注释和 /* */ 多行注释在 JSON 中都无效。如果你需要文档说明，请使用单独的文件或 JSONC 等格式。

常见 JSON 验证错误

了解最常见的错误有助于你快速发现和修复它们。以下是你最常遇到的错误：

• 意外的标记：通常由单引号、未加引号的键或尾随逗号引起。错误消息包含解析失败的位置。
• JSON 输入意外结束：JSON 字符串不完整或为空。这通常发生在网络请求返回空响应时。
• 意外的非空白字符：主 JSON 值之后的额外内容，例如未包裹在数组中的第二个对象。
• 无效的数字：带有前导零（0 本身除外）的数字、十六进制表示法或 NaN / Infinity 值不是有效的 JSON。

在 JavaScript 中验证 JSON

在 JavaScript 中验证 JSON 最简单的方法是将 JSON.parse() 包装在 try-catch 块中。如果 JSON 无效，该方法会抛出 SyntaxError。

function validateJSON(jsonString) {
  try {
    JSON.parse(jsonString);
    return { valid: true };
  } catch (error) {
    return {
      valid: false,
      error: error.message
    };
  }
}

const result = validateJSON('{"name": "Alice"}');
console.log(result);
// { valid: true }

const badResult = validateJSON("{'name': 'Alice'}");
console.log(badResult);
// { valid: false, error: "Unexpected token '..." }

在 Python 中验证 JSON

Python 提供了 json 模块，其中包含用于解析 JSON 字符串的 json.loads()。与 JavaScript 类似，无效的 JSON 会引发带有详细位置信息的 json.JSONDecodeError。

import json

def validate_json(json_string):
    try:
        json.loads(json_string)
        return {"valid": True}
    except json.JSONDecodeError as e:
        return {
            "valid": False,
            "error": str(e),
            "line": e.lineno,
            "column": e.colno
        }

result = validate_json('{"name": "Alice"}')
print(result)
# {'valid': True}

JSON Schema 验证

语法验证只能告诉你 JSON 是否格式正确。JSON Schema 让你定义预期的结构并根据它验证数据。Schema 指定了必需字段、数据类型、值范围、字符串模式和嵌套对象结构。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["name", "email"],
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0 }
  }
}

流行的 JSON Schema 验证器包括 JavaScript 的 Ajv、Python 的 jsonschema 和 Java 的 json-schema-validator。这些库根据你的 Schema 验证 JSON 数据，并为每个违规生成详细的错误消息。

在线 JSON 验证工具

当你需要在不编写代码的情况下快速检查 JSON 文档时，在线验证器是最快的选择。它们提供带有错误高亮和行号的即时反馈。

JSON 验证最佳实践

• 尽早验证：在系统边界（如 API 端点和文件导入函数）检查 JSON，在数据进入业务逻辑之前。
• 使用 Schema 验证：在语法之外，使用 JSON Schema 验证数据结构，以捕获缺失字段、错误类型和超出范围的值。
• 提供清晰的错误消息：当验证失败时，包含字段路径、预期类型和实际值，以帮助用户快速修复问题。
• 在客户端和服务器端都进行验证：客户端验证提供即时反馈，而服务器端验证确保安全性和数据完整性。
• 在 CI/CD 中自动化验证：使用 ajv-cli 或 jsonschema 等工具在构建管道中验证 JSON 固定文件和配置文件。
• 记录验证错误：记录带有上下文的验证失败，以识别模式并修复数据生产者中的根本原因。