📚 JSON 完整语法教程 · 千肯AI

一、JSON 基础语法

1.1 数据类型

JSON 支持以下 6 种数据类型：

类型	说明	示例
String (字符串)	必须使用双引号	"Hello World"
Number (数字)	整数或浮点数	123, 3.14
Boolean (布尔值)	true 或 false	true, false
Null (空值)	表示空值	null
Object (对象)	花括号包裹的键值对	{ "key": "value" }
Array (数组)	方括号包裹的值列表	[1, 2, 3]

1.2 基本结构

JSON 构建于两种结构：

• 对象：无序的"键值对"集合，用花括号 {} 表示
• 数组：有序的值的列表，用方括号 [] 表示

二、JSON vs JavaScript 对象

2.1 主要区别对比

特性	JSON	JavaScript 对象
键名引号	必须用双引号 "key"	可以不用引号 key
字符串引号	只能用双引号 "value"	单引号或双引号都可以
尾随逗号	不允许	允许（ES5+）
注释	不支持	支持
undefined	不支持	支持
函数/方法	不支持	支持
NaN, Infinity	不支持	支持
前导零	不允许（如 007）	允许

2.2 代码示例对比

✅ 有效的 JSON：

{
  "name": "张三",
  "age": 25,
  "isStudent": false,
  "hobbies": ["reading", "coding"],
  "address": {
    "city": "北京",
    "zip": "100000"
  }
}

❌ 无效的 JSON（但是有效的 JavaScript 对象）：

{
  name: "张三",              // ❌ 键名必须用双引号
  'age': 25,                // ❌ 不能用单引号
  "score": NaN,             // ❌ JSON 不支持 NaN
  "func": function() {},    // ❌ JSON 不支持函数
  "data": undefined,        // ❌ JSON 不支持 undefined
  "number": 007,            // ❌ 不能有前导零
  "items": [1, 2, 3,],      // ❌ 不能有尾随逗号
  // 这是注释               // ❌ JSON 不支持注释
}

2.3 相互转换

在 JavaScript 中，可以使用以下方法进行转换：

// JavaScript 对象转 JSON 字符串
const obj = { name: "李四", age: 30 };
const jsonString = JSON.stringify(obj);
console.log(jsonString);  // '{"name":"李四","age":30}'

// JSON 字符串转 JavaScript 对象
const jsonStr = '{"name":"王五","age":28}';
const parsedObj = JSON.parse(jsonStr);
console.log(parsedObj.name);  // "王五"

三、JSON 的实际应用

3.1 前后端数据交换

JSON 最常见的用途是在 Web 应用中作为 API 的数据格式：

// API 返回的用户数据
{
  "code": 200,
  "message": "success",
  "data": {
    "userId": "U123456",
    "username": "zhangsan",
    "email": "zhangsan@example.com",
    "profile": {
      "avatar": "https://example.com/avatar.jpg",
      "bio": "Full Stack Developer"
    },
    "createdAt": "2024-01-15T08:30:00Z"
  }
}

3.2 配置文件

许多应用使用 JSON 作为配置文件格式：

// package.json 示例
{
  "name": "my-project",
  "version": "1.0.0",
  "description": "My awesome project",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "test": "jest"
  },
  "dependencies": {
    "express": "^4.18.0",
    "axios": "^1.4.0"
  }
}

3.3 AI 智能体开发中的应用

在 AI 智能体开发中，JSON 常用于：

• 定义智能体的配置参数
• 传递对话历史和上下文
• 结构化输出结果
• 工具调用的参数传递

// AI 智能体配置示例
{
  "agent": {
    "name": "客服助手",
    "model": "gpt-4",
    "temperature": 0.7,
    "maxTokens": 2000
  },
  "systemPrompt": "你是一个专业的客服助手...",
  "tools": [
    {
      "name": "searchKnowledgeBase",
      "description": "搜索知识库",
      "parameters": {
        "query": {
          "type": "string",
          "required": true
        }
      }
    }
  ]
}

四、JSON 的优缺点

五、常见错误和注意事项

5.1 常见语法错误

1. 忘记引号：键名必须用双引号
2. 使用单引号：JSON 只允许双引号
3. 尾随逗号：最后一个元素后不能有逗号
4. 注释：JSON 不支持任何形式的注释
5. 特殊字符未转义：如换行符、引号等需要转义

5.2 字符串转义

JSON 字符串中特殊字符需要使用反斜杠转义：

{
  "path": "C:\\Users\\Documents",
  "quote": "他说：\"你好\"",
  "newline": "第一行\\n第二行",
  "tab": "列1\\t列2"
}

5.3 最佳实践

• 始终使用 JSON.parse() 而不是 eval() 解析 JSON
• 使用 try-catch 捕获解析错误
• 对于复杂配置，考虑使用 JSON5 或 YAML
• 在传输前使用 JSON.stringify() 进行序列化
• 使用在线工具验证 JSON 格式的正确性

六、JSON 扩展格式

6.1 JSON5

JSON5 是 JSON 的超集，解决了 JSON 的一些限制：

• 支持注释
• 支持尾随逗号
• 支持单引号
• 支持 undefined、NaN、Infinity

6.2 YAML

YAML 是另一种流行的数据序列化格式，更适合配置文件：

• 更简洁的语法
• 支持注释
• 更好的可读性