cJSON- API 深度解析：设计理念与实现原理（二）

文章目录

[cJSON API 深度解析：设计理念与实现原理](#cJSON API 深度解析：设计理念与实现原理)
- 一、核心解析函数
- - [1.1 基础解析函数](#1.1 基础解析函数)
  - [1.2 高级解析选项](#1.2 高级解析选项)
- [二、对象操作 API](#二、对象操作 API)
- - [2.1 对象创建](#2.1 对象创建)
  - [2.2 对象访问](#2.2 对象访问)
- [三、内存管理 API](#三、内存管理 API)
- - [3.1 基础内存操作](#3.1 基础内存操作)
  - [3.2 对象生命周期管理](#3.2 对象生命周期管理)
- [四、序列化 API](#四、序列化 API)
- - [4.1 基础序列化](#4.1 基础序列化)
  - [4.2 高级序列化](#4.2 高级序列化)
- [五、数组操作 API](#五、数组操作 API)
- - [5.1 数组创建与初始化](#5.1 数组创建与初始化)
  - [5.2 数组修改](#5.2 数组修改)
- [六、类型系统 API](#六、类型系统 API)
- - [6.1 类型检查](#6.1 类型检查)
  - [6.2 值访问](#6.2 值访问)
- 七、错误处理机制
- - [7.1 错误检测](#7.1 错误检测)
- 八、迭代器支持
- - [8.1 数组迭代](#8.1 数组迭代)

cJSON API 深度解析：设计理念与实现原理

一、核心解析函数

1.1 基础解析函数

c 复制代码

CJSON_PUBLIC(cJSON *) cJSON_Parse(const char *value);
CJSON_PUBLIC(cJSON *) cJSON_ParseWithLength(const char *value, size_t buffer_length);

这两个函数是 cJSON 最基础的解析入口：

cJSON_Parse: 适用于以 null 结尾的字符串
cJSON_ParseWithLength: 支持指定缓冲区长度，更安全，适合处理二进制数据

1.2 高级解析选项

c 复制代码

CJSON_PUBLIC(cJSON *) cJSON_ParseWithOpts(
    const char *value,
    const char **return_parse_end,
    cJSON_bool require_null_terminated
);

高级解析特性：

return_parse_end: 返回解析结束位置，用于错误定位
require_null_terminated: 强制要求字符串以 null 结尾
支持部分解析，可用于流式处理

二、对象操作 API

2.1 对象创建

c 复制代码

// 基础类型创建
CJSON_PUBLIC(cJSON *) cJSON_CreateNull(void);
CJSON_PUBLIC(cJSON *) cJSON_CreateTrue(void);
CJSON_PUBLIC(cJSON *) cJSON_CreateFalse(void);
CJSON_PUBLIC(cJSON *) cJSON_CreateBool(cJSON_bool boolean);
CJSON_PUBLIC(cJSON *) cJSON_CreateNumber(double num);
CJSON_PUBLIC(cJSON *) cJSON_CreateString(const char *string);

// 复合类型创建
CJSON_PUBLIC(cJSON *) cJSON_CreateArray(void);
CJSON_PUBLIC(cJSON *) cJSON_CreateObject(void);

创建函数设计特点：

统一的返回类型
内存自动管理
类型安全保证
错误处理机制

2.2 对象访问

c 复制代码

// 对象成员访问
CJSON_PUBLIC(cJSON *) cJSON_GetObjectItem(const cJSON * const object, const char * const string);
CJSON_PUBLIC(cJSON *) cJSON_GetObjectItemCaseSensitive(const cJSON * const object, const char * const string);

// 数组元素访问
CJSON_PUBLIC(cJSON *) cJSON_GetArrayItem(const cJSON *array, int index);
CJSON_PUBLIC(int) cJSON_GetArraySize(const cJSON *array);

访问函数特性：

支持大小写敏感和不敏感查找
边界检查保护
类型安全访问
链式访问支持

三、内存管理 API

3.1 基础内存操作

c 复制代码

// 内存管理钩子
typedef struct cJSON_Hooks {
    void *(CJSON_CDECL *malloc_fn)(size_t sz);
    void (CJSON_CDECL *free_fn)(void *ptr);
} cJSON_Hooks;

// 设置内存管理函数
CJSON_PUBLIC(void) cJSON_InitHooks(cJSON_Hooks* hooks);

内存管理特点：

可自定义分配器
平台无关性
调用约定兼容
内存追踪支持

3.2 对象生命周期管理

c 复制代码

// 对象删除
CJSON_PUBLIC(void) cJSON_Delete(cJSON *item);

// 对象复制
CJSON_PUBLIC(cJSON *) cJSON_Duplicate(const cJSON *item, cJSON_bool recurse);

生命周期管理特性：

递归删除保证
深浅拷贝支持
引用计数处理
内存泄漏防护

四、序列化 API

4.1 基础序列化

c 复制代码

// 格式化输出
CJSON_PUBLIC(char *) cJSON_Print(const cJSON *item);

// 非格式化输出
CJSON_PUBLIC(char *) cJSON_PrintUnformatted(const cJSON *item);

序列化特点：

自动内存管理
格式控制选项
UTF-8 支持
错误处理机制

4.2 高级序列化

c 复制代码

// 预分配缓冲区序列化
CJSON_PUBLIC(cJSON_bool) cJSON_PrintPreallocated(
    cJSON *item,
    char *buffer,
    const int length,
    const cJSON_bool format
);

// 预估缓冲区序列化
CJSON_PUBLIC(char *) cJSON_PrintBuffered(
    const cJSON *item,
    int prebuffer,
    cJSON_bool fmt
);

高级特性：

缓冲区预分配
大小预估优化
格式化控制
性能优化选项

五、数组操作 API

5.1 数组创建与初始化

c 复制代码

// 基础数组创建
CJSON_PUBLIC(cJSON *) cJSON_CreateArray(void);

// 批量创建数组
CJSON_PUBLIC(cJSON *) cJSON_CreateIntArray(const int *numbers, int count);
CJSON_PUBLIC(cJSON *) cJSON_CreateFloatArray(const float *numbers, int count);
CJSON_PUBLIC(cJSON *) cJSON_CreateDoubleArray(const double *numbers, int count);
CJSON_PUBLIC(cJSON *) cJSON_CreateStringArray(const char *const *strings, int count);

数组操作特点：

类型安全保证
批量操作支持
边界检查
内存优化

5.2 数组修改

c 复制代码

// 添加元素
CJSON_PUBLIC(cJSON_bool) cJSON_AddItemToArray(cJSON *array, cJSON *item);

// 删除元素
CJSON_PUBLIC(void) cJSON_DeleteItemFromArray(cJSON *array, int which);

// 插入元素
CJSON_PUBLIC(cJSON_bool) cJSON_InsertItemInArray(cJSON *array, int which, cJSON *newitem);

// 替换元素
CJSON_PUBLIC(cJSON_bool) cJSON_ReplaceItemInArray(cJSON *array, int which, cJSON *newitem);

修改操作特性：

位置验证
自动维护链表
内存管理
错误处理

六、类型系统 API

6.1 类型检查

c 复制代码

// 类型判断函数
CJSON_PUBLIC(cJSON_bool) cJSON_IsInvalid(const cJSON * const item);
CJSON_PUBLIC(cJSON_bool) cJSON_IsNull(const cJSON * const item);
CJSON_PUBLIC(cJSON_bool) cJSON_IsBool(const cJSON * const item);
CJSON_PUBLIC(cJSON_bool) cJSON_IsNumber(const cJSON * const item);
CJSON_PUBLIC(cJSON_bool) cJSON_IsString(const cJSON * const item);
CJSON_PUBLIC(cJSON_bool) cJSON_IsArray(const cJSON * const item);
CJSON_PUBLIC(cJSON_bool) cJSON_IsObject(const cJSON * const item);

类型系统特点：

位运算优化
类型安全保证
NULL 检查
复合类型支持

6.2 值访问

c 复制代码

// 类型安全的值访问
CJSON_PUBLIC(char *) cJSON_GetStringValue(const cJSON * const item);
CJSON_PUBLIC(double) cJSON_GetNumberValue(const cJSON * const item);

// 值修改
CJSON_PUBLIC(char*) cJSON_SetValuestring(cJSON *object, const char *valuestring);
#define cJSON_SetNumberValue(object, number) ((object != NULL) ? cJSON_SetNumberHelper(object, (double)number) : (number))

值操作特性：

类型检查
自动转换
内存管理
错误处理

七、错误处理机制

7.1 错误检测

c 复制代码

// 错误信息获取
CJSON_PUBLIC(const char *) cJSON_GetErrorPtr(void);

// 错误状态检查
if (root == NULL) {
    const char *error_ptr = cJSON_GetErrorPtr();
    if (error_ptr != NULL) {
        // 处理错误
    }
}

错误处理特点：

统一的错误接口
错误位置定位
错误信息描述
错误恢复机制

八、迭代器支持

8.1 数组迭代

c 复制代码

// 数组迭代宏
#define cJSON_ArrayForEach(element, array) \
    for(element = (array != NULL) ? (array)->child : NULL; \
        element != NULL; \
        element = element->next)

// 使用示例
cJSON *element;
cJSON_ArrayForEach(element, array) {
    // 处理每个元素
}

迭代器特性：

简化遍历操作
NULL 安全检查
链表遍历优化
双向遍历支持

这些 API 的设计充分体现了 cJSON 的设计理念：简单、高效、安全。通过合理的抽象和封装，既保证了使用的便利性，又不失灵活性和性能。