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

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

一、核心解析函数

1.1 基础解析函数

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 高级解析选项

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

高级解析特性：

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

二、对象操作 API

2.1 对象创建

// 基础类型创建
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);

创建函数设计特点：

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

2.2 对象访问

// 对象成员访问
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);

访问函数特性：

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

三、内存管理 API

3.1 基础内存操作

// 内存管理钩子
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);

内存管理特点：

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

3.2 对象生命周期管理

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

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

生命周期管理特性：

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

四、序列化 API

4.1 基础序列化

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

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

序列化特点：

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

4.2 高级序列化

// 预分配缓冲区序列化
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
);

高级特性：

1. 缓冲区预分配
2. 大小预估优化
3. 格式化控制
4. 性能优化选项

五、数组操作 API

5.1 数组创建与初始化

// 基础数组创建
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);

数组操作特点：

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

5.2 数组修改

// 添加元素
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);

修改操作特性：

1. 位置验证
2. 自动维护链表
3. 内存管理
4. 错误处理

六、类型系统 API

6.1 类型检查

// 类型判断函数
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);

类型系统特点：

1. 位运算优化
2. 类型安全保证
3. NULL 检查
4. 复合类型支持

6.2 值访问

// 类型安全的值访问
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))

值操作特性：

1. 类型检查
2. 自动转换
3. 内存管理
4. 错误处理

七、错误处理机制

7.1 错误检测

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

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

错误处理特点：

1. 统一的错误接口
2. 错误位置定位
3. 错误信息描述
4. 错误恢复机制

八、迭代器支持

8.1 数组迭代

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

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

迭代器特性：

1. 简化遍历操作
2. NULL 安全检查
3. 链表遍历优化
4. 双向遍历支持

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