JSON 数据结构基础

什么是 JSON？

JSON（JavaScript Object Notation）是一种轻量级的数据交换格式。它用纯文本表示结构化数据，人类可读，机器也容易解析。

在 API 中的角色：客户端和服务器之间传递数据时，几乎都用 JSON。

两种核心结构

1. 对象（Object）

用 {} 包裹，是一组 键值对（key-value pairs）。

{
  "name": "张三",           ← key: "name"，value: "张三"
  "age": 25,               ← key: "age"，value: 25
  "is_student": true       ← key: "is_student"，value: true
}

类比：对象就像一本字典或一个人的档案袋。每个字段（键）对应一个值，你可以通过键来查找值。

在 Python 中的等价物：dict 在 JavaScript 中的等价物：Object

2. 数组（Array）

用 [] 包裹，是一组有序的值。

["苹果", "香蕉", "橙子"]

类比：数组就像购物清单——有顺序，每个位置有对应的内容。

在 Python 中的等价物：list 在 JavaScript 中的等价物：Array

数据类型速查

嵌套：组合使用

实际 API 响应中，对象和数组几乎都会嵌套使用：

{
  "user": {                              ← 对象里套对象
    "name": "张三",
    "contact": {
      "email": "zhangsan@example.com"    ← 三层嵌套
    }
  },
  "orders": [                             ← 对象里套数组
    {
      "id": "001",
      "items": ["苹果", "香蕉"]           ← 数组里套对象，对象里套数组
    },
    {
      "id": "002",
      "items": ["橙子"]
    }
  ]
}

通俗比喻：这就像一份外卖订单：

• 最外层 {} = 整个订单
• user = 订餐人信息（又是一个对象）
• orders = 订单列表（数组），每个订单又是一个对象

API 中常见的 JSON 结构模式

模式 1：简单键值对

{
  "model": "gpt-4o",
  "temperature": 0.7,
  "max_tokens": 1024
}

适用场景：配置参数、设置选项

模式 2：消息数组

{
  "messages": [
    {"role": "system", "content": "你是一个翻译助手"},
    {"role": "user", "content": "你好"},
    {"role": "assistant", "content": "Hello!"},
    {"role": "user", "content": "谢谢"}
  ]
}

适用场景：对话历史。每个消息有 role（角色）和 content（内容）。

模式 3：混合嵌套（AI API 响应）

{
  "id": "msg_01A...",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "让我帮你查一下。"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A...",
      "name": "get_weather",
      "input": {
        "location": "Shanghai"
      }
    }
  ],
  "model": "claude-sonnet-4-5",
  "usage": {
    "input_tokens": 100,
    "output_tokens": 50
  }
}

拆解结构：

• 外层是对象（整条消息）
• content 是数组（可能包含文本块 + 工具调用块）
• 每个内容块是对象（有 type、text/input 等字段）
• usage 是对象里的对象（嵌套统计信息）

模式 4：工具调用参数

{
  "name": "get_weather",
  "description": "获取指定城市的天气",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "城市名，如 Shanghai"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"]
      }
    },
    "required": ["location"]
  }
}

拆解结构：

• input_schema 本身就是一个完整的 JSON Schema（用来描述数据结构的结构）
• properties 是对象，定义了每个参数的类型和描述
• required 是数组，列出了必填字段

JSON vs. JavaScript 对象

很多人混淆，关键区别：

// JavaScript 对象（合法）
const user = {
  name: "张三",         // 键可以不加引号
  greet() {             // 可以有函数
    // 输出问候语
  }
}

// JSON（合法）
{
  "name": "张三",        // 键必须有双引号
  "greet": "你好"       // 不能有函数，只能用字符串
}

JSON 的严格规则

1. 键必须用双引号：{"name": "张三"} ✅，{name: "张三"} ❌
2. 字符串必须用双引号："hello" ✅，'hello' ❌
3. 不能有尾随逗号：{"a": 1,} ❌，{"a": 1} ✅
4. 布尔值全小写：true / false ✅，True / False ❌
5. 空值是 null：{"a": null} ✅，{"a": None} ❌

如何解析 JSON

在代码中使用

Python：

import json

# 字符串 → Python 对象
data = json.loads('{"name": "张三", "age": 25}')
print(data["name"])  # 张三

# Python 对象 → JSON 字符串
json_str = json.dumps({"name": "张三"})

JavaScript：

// 字符串 → JavaScript 对象
const data = JSON.parse('{"name": "张三", "age": 25}');
// data.name 访问得到 "张三"

// JavaScript 对象 → JSON 字符串
const jsonStr = JSON.stringify({ name: "张三" });

命令行（curl 测试 API）：

curl -s https://api.example.com/data | jq .

常见错误

在 AI API 中的实际应用

理解这些结构后，再看 AI API 的文档就会清晰很多：

• 请求体：一个 JSON 对象，包含 model（字符串）、messages（消息数组）、tools（工具定义数组）等字段
• 响应体：一个 JSON 对象，包含 content（内容块数组）、usage（使用统计对象）等字段
• 工具参数：input 字段是一个嵌套的 JSON 对象，结构由 input_schema 定义

返回 REST API 基础概念 了解 API 的请求/响应流程 返回 SSE 流式输出原理 了解流式传输的 JSON 数据结构