当前位置：首页 > news >正文

cJSON-轻量级 C 语言 JSON 解析库的使用（一）

news 来源：原创 2025/7/22 7:26:35

文章目录

cJSON：轻量级 C 语言 JSON 解析库的使用
- 前言
- 一、cJSON 简介
- - 核心特点：
- 二、核心数据结构解析
- 三、深入解析 API 设计
- - 1. 解析 JSON
  - 2. 访问数据
  - 3. 构建 JSON
- 四、内存管理策略
- 五、高级应用技巧
- - 1. 引用系统
  - 2. 批量操作
  - 3. 原地修改
- 六、性能优化技巧
- - 1. 使用预分配缓冲区
  - 2. 非格式化输出
  - 3. 使用引用而非复制
- 七、实战案例：配置文件解析器
- 八、总结

cJSON：轻量级 C 语言 JSON 解析库的使用

前言

在当今互联网时代，JSON (JavaScript Object Notation) 已成为数据交换的通用格式。对于 C 语言开发者来说，cJSON 库提供了一种简单而强大的方式来处理 JSON 数据。本文将深入剖析 cJSON 的设计理念、核心功能和实际应用场景。

一、cJSON 简介

cJSON 是由 Dave Gamble 开发的一个轻量级 JSON 解析和生成库，使用纯 C 语言编写，仅包含一个头文件和一个源文件，总代码量不到 4000 行。它的设计理念是：简单、高效、易用。

核心特点：

轻量级：整个库只有两个文件
零依赖：仅依赖标准 C 库
跨平台：支持各种操作系统和编译器
完整支持 JSON 规范
MIT 许可证：可自由用于商业和非商业项目

二、核心数据结构解析

cJSON 的核心是 cJSON 结构体，它采用了链表和树形结构的混合设计：

typedef struct cJSON {struct cJSON *next;     // 链表后指针struct cJSON *prev;     // 链表前指针struct cJSON *child;    // 子节点指针int type;              // 节点类型char *valuestring;     // 字符串值int valueint;         // 整数值（已废弃）double valuedouble;   // 浮点数值char *string;         // 键名
} cJSON;

这种设计有几个关键优势：

双向链表设计使得数组元素的遍历和操作变得简单高效
树形结构通过 child 指针实现，完美表达 JSON 的层次结构
类型系统通过位运算实现，支持快速类型判断

三、深入解析 API 设计

1. 解析 JSON

// 基础解析函数
cJSON *root = cJSON_Parse("{\"name\":\"张三\",\"age\":25}");// 高级解析选项
const char *end_ptr = NULL;
cJSON *root = cJSON_ParseWithOpts(json_string, &end_ptr, 1);

cJSON 的解析过程是一次性完成的，它会将整个 JSON 字符串解析为内存中的树状结构。这种设计在处理小型 JSON 时非常高效，但对于超大型 JSON 可能会有内存压力。

2. 访问数据

// 获取对象成员
cJSON *name = cJSON_GetObjectItem(root, "name");
if (cJSON_IsString(name)) {printf("姓名: %s\n", name->valuestring);
}// 获取数组元素
cJSON *array = cJSON_GetObjectItem(root, "skills");
int size = cJSON_GetArraySize(array);
for (int i = 0; i < size; i++) {cJSON *item = cJSON_GetArrayItem(array, i);printf("技能 %d: %s\n", i, item->valuestring);
}

cJSON 提供了丰富的 API 来访问 JSON 数据，包括大小写敏感和不敏感的查找。

3. 构建 JSON

// 创建对象
cJSON *person = cJSON_CreateObject();
cJSON_AddStringToObject(person, "name", "李四");
cJSON_AddNumberToObject(person, "age", 30);// 创建嵌套结构
cJSON *address = cJSON_CreateObject();
cJSON_AddStringToObject(address, "city", "北京");
cJSON_AddItemToObject(person, "address", address);// 生成 JSON 字符串
char *json_str = cJSON_Print(person);

cJSON 的构建 API 设计非常直观，遵循了"创建-添加-生成"的模式，使得构建复杂 JSON 结构变得简单。

四、内存管理策略

cJSON 的内存管理设计非常清晰：

解析函数返回的 cJSON 对象需要通过 cJSON_Delete() 释放
打印函数返回的字符串需要通过 free() 释放
自定义内存管理通过 cJSON_InitHooks() 实现

// 自定义内存分配器
cJSON_Hooks hooks;
hooks.malloc_fn = my_malloc;
hooks.free_fn = my_free;
cJSON_InitHooks(&hooks);

这种设计使得 cJSON 可以轻松集成到各种内存管理系统中，包括嵌入式系统和自定义内存池。

五、高级应用技巧

1. 引用系统

// 创建字符串引用（不复制字符串）
const char *constant_str = "固定字符串";
cJSON *str_ref = cJSON_CreateStringReference(constant_str);// 创建对象引用（不复制整个对象）
cJSON *obj_ref = cJSON_CreateObjectReference(existing_obj);

引用系统可以显著减少内存使用和复制开销，特别适合处理大型 JSON 或静态数据。

2. 批量操作

// 批量创建数组
int numbers[] = {1, 2, 3, 4, 5};
cJSON *array = cJSON_CreateIntArray(numbers, 5);// 批量创建字符串数组
const char *strings[] = {"苹果", "香蕉", "橙子"};
cJSON *str_array = cJSON_CreateStringArray(strings, 3);

批量操作 API 不仅代码更简洁，而且性能更高，因为它减少了函数调用次数和内存分配次数。

3. 原地修改

// 修改字符串值
cJSON_SetValuestring(name, "新名字");// 修改数值
cJSON_SetNumberValue(age, 40);// 替换对象成员
cJSON_ReplaceItemInObject(person, "address", new_address);

原地修改 API 允许在不重建整个 JSON 结构的情况下更新值，这在处理动态数据时非常有用。

六、性能优化技巧

1. 使用预分配缓冲区

char buffer[1024];
if (cJSON_PrintPreallocated(root, buffer, sizeof(buffer), 1)) {// 使用 buffer 中的 JSON 字符串
}

预分配缓冲区可以避免动态内存分配，显著提高性能，特别适合嵌入式系统。

2. 非格式化输出

// 紧凑输出（无空格、换行）
char *compact = cJSON_PrintUnformatted(root);

非格式化输出不仅节省空间，而且生成速度更快，适合网络传输和存储。

3. 使用引用而非复制

// 添加引用而非复制
cJSON_AddItemReferenceToObject(root, "ref_data", existing_data);

引用操作可以避免深度复制，显著提高性能和减少内存使用。

七、实战案例：配置文件解析器

typedef struct Config {char *server_host;int server_port;char *log_level;int max_connections;
} Config;Config* load_config(const char *filename) {// 读取文件内容char *content = read_file(filename);if (!content) return NULL;// 解析 JSONcJSON *json = cJSON_Parse(content);free(content);if (!json) {printf("解析错误: %s\n", cJSON_GetErrorPtr());return NULL;}// 创建配置对象Config *config = malloc(sizeof(Config));// 提取配置项cJSON *server = cJSON_GetObjectItem(json, "server");if (cJSON_IsObject(server)) {cJSON *host = cJSON_GetObjectItem(server, "host");cJSON *port = cJSON_GetObjectItem(server, "port");if (cJSON_IsString(host)) {config->server_host = strdup(host->valuestring);}if (cJSON_IsNumber(port)) {config->server_port = port->valueint;}}cJSON *log_level = cJSON_GetObjectItem(json, "log_level");if (cJSON_IsString(log_level)) {config->log_level = strdup(log_level->valuestring);}cJSON *max_conn = cJSON_GetObjectItem(json, "max_connections");if (cJSON_IsNumber(max_conn)) {config->max_connections = max_conn->valueint;}cJSON_Delete(json);return config;
}

八、总结

cJSON 凭借其简单、高效的设计理念，成为了 C 语言处理 JSON 的首选库之一。它的成功之处在于：

简单易用的 API 设计
高效灵活的内存管理
完整支持 JSON 规范
零依赖的轻量级实现