十二、【ESP32全栈开发指南： IDF开发环境下cJSON使用】

一、JSON简介

JSON（JavaScript Object Notation）是一种轻量级的数据交换格式，具有以下核心特性：

• 完全独立于编程语言的文本格式

• 易于人阅读和编写

• 易于机器解析和生成

• 基于ECMAScript标准子集

1.1 JSON语法规则

{
  "name": "ESP32",
  "cores": 2,
  "features": ["WiFi", "Bluetooth", "Low Power"],
  "metadata": {
    "voltage": 3.3,
    "package": "QFN48"
  }
}

• 「对象」：花括号 {} 包裹的键值对集合

• 「数组」：方括号 [] 包裹的值列表

• 「键名」：必须使用双引号包裹

• 「分隔符」：键值对用逗号分隔

1.2 支持的数据类型

二、添加cJSON库

在ESP-IDF环境中，cJSON库已集成在组件中：

// 包含头文件
#include "cJSON.h"

// CMakeLists.txt 配置
idf_component_register(
    ...
    REQUIRES cJSON
)

三、生成JSON数据

3.1 创建JSON结构体

cJSON *root = cJSON_CreateObject();  // 创建根对象
cJSON *sensor_data = cJSON_CreateObject();  // 创建子对象

3.2 添加各种类型数据

// 添加基本类型
cJSON_AddStringToObject(root, "device", "ESP32-S3");
cJSON_AddNumberToObject(root, "temperature", 25.6);
cJSON_AddBoolToObject(root, "connected", true);

// 添加嵌套对象
cJSON_AddItemToObject(root, "sensor", sensor_data);
cJSON_AddStringToObject(sensor_data, "type", "DHT11");
cJSON_AddNumberToObject(sensor_data, "humidity", 45.7);

// 添加整型数组
int gpio_pins[3] = {12, 13, 14};
cJSON *pins_array = cJSON_CreateIntArray(gpio_pins, 3);
cJSON_AddItemToObject(root, "gpio_pins", pins_array);

// 添加对象数组
cJSON *networks = cJSON_CreateArray();
for (int i = 0; i < 2; i++) {
    cJSON *network = cJSON_CreateObject();
    cJSON_AddStringToObject(network, "ssid", (i == 0) ? "HomeWiFi" : "OfficeAP");
    cJSON_AddNumberToObject(network, "rssi", -65 + i*10);
    cJSON_AddItemToArray(networks, network);
}
cJSON_AddItemToObject(root, "networks", networks);

3.3 输出与序列化

// 格式化输出
char *json_str = cJSON_Print(root);
ESP_LOGI("JSON", "Generated JSON:\n%s", json_str);

/* 输出结果：
{
  "device": "ESP32-S3",
  "temperature": 25.6,
  "connected": true,
  "sensor": {
    "type": "DHT11",
    "humidity": 45.7
  },
  "gpio_pins": [12, 13, 14],
  "networks": [
    {"ssid": "HomeWiFi", "rssi": -65},
    {"ssid": "OfficeAP", "rssi": -55}
  ]
}
*/

3.4 内存管理

cJSON_free(json_str);  // 释放打印字符串
cJSON_Delete(root);    // 递归释放整个JSON树

❝

「重要提示」：cJSON_Delete() 会递归释放所有子节点，只需在根节点调用一次

❞

四、解析JSON数据

4.1 基础解析流程

const char *json_str = "{\"status\":\"active\",\"uptime\":3600}";

cJSON *root = cJSON_Parse(json_str);
if (root == NULL) {
    const char *error_ptr = cJSON_GetErrorPtr();
    if (error_ptr != NULL) {
        ESP_LOGE("JSON", "Error before: %s", error_ptr);
    }
    return;
}

// 提取数据
cJSON *status = cJSON_GetObjectItem(root, "status");
cJSON *uptime = cJSON_GetObjectItem(root, "uptime");

if (cJSON_IsString(status)) {
    ESP_LOGI("JSON", "Status: %s", status->valuestring);
}

if (cJSON_IsNumber(uptime)) {
    ESP_LOGI("JSON", "Uptime: %d seconds", uptime->valueint);
}

cJSON_Delete(root);

4.2 解析复杂结构

// 示例JSON
const char *config_str = "{ \"sensors\": [ \
    {\"type\":\"temperature\", \"pin\":12}, \
    {\"type\":\"humidity\", \"pin\":14} \
]}";

cJSON *root = cJSON_Parse(config_str);
cJSON *sensors = cJSON_GetObjectItem(root, "sensors");

if (cJSON_IsArray(sensors)) {
    int sensor_count = cJSON_GetArraySize(sensors);
    for (int i = 0; i < sensor_count; i++) {
        cJSON *sensor = cJSON_GetArrayItem(sensors, i);
        cJSON *type = cJSON_GetObjectItem(sensor, "type");
        cJSON *pin = cJSON_GetObjectItem(sensor, "pin");
        
        if (cJSON_IsString(type) && cJSON_IsNumber(pin)) {
            ESP_LOGI("SENSOR", "Type: %s, GPIO: %d", 
                    type->valuestring, pin->valueint);
        }
    }
}

4.3 错误处理技巧

// 安全获取对象项
cJSON* safe_get_object(cJSON *obj, const char *key, cJSON_type type) {
    cJSON *item = cJSON_GetObjectItem(obj, key);
    if (!item) {
        ESP_LOGW("JSON", "Missing key: %s", key);
        return NULL;
    }
    if (item->type != type) {
        ESP_LOGW("JSON", "Type mismatch for %s", key);
        return NULL;
    }
    return item;
}

// 使用示例
cJSON *temp = safe_get_object(root, "temperature", cJSON_Number);
if (temp) {
    // 安全使用数据
}

五、实战技巧与最佳实践

5.1 内存优化技巧

// 使用缓冲器避免碎片化
char json_buffer[512];
cJSON *root = cJSON_CreateObject();
cJSON_AddStringToObject(root, "message", "Hello JSON");

// 直接打印到固定缓冲区
cJSON_PrintPreallocated(root, json_buffer, sizeof(json_buffer), true);
ESP_LOGI("JSON", "Compact JSON: %s", json_buffer);

// 释放资源
cJSON_Delete(root);

5.2 常用库函数速查

5.3 常见问题解决方案

1. 「内存泄漏」：确保每个 cJSON_Create*() 都有对应的 cJSON_Delete()
2. 「无效指针」：检查 cJSON_Parse() 返回值是否为NULL

3. 「类型错误」：使用 cJSON_IsNumber() 等函数验证数据类型

4. 「键名错误」：使用 cJSON_HasObjectItem() 检查键是否存在

❝

「性能提示」：在实时系统中避免频繁解析大型JSON，可考虑预解析或二进制格式

❞

结语

cJSON为ESP32提供了高效的JSON处理能力，本文涵盖了从基础操作到高级技巧的全方位内容。实际开发时请注意：

1. 始终进行错误检查

2. 在解析前验证JSON格式有效性

3. 使用预分配缓冲区处理大数据

4. 及时释放内存资源

❝

示例代码兼容ESP-IDF v4.4+，可在GitHub获取完整工程：esp32-cjson-demo

❞

「附：内存管理示意图」

cJSON_CreateObject()
  ├── cJSON_AddStringToObject()  // 分配字符串内存
  ├── cJSON_CreateArray()         // 分配数组内存
  │    └── cJSON_CreateObject()   // 嵌套对象
  └── ... 
cJSON_Print()           // 分配输出字符串内存
cJSON_free()            // 释放输出字符串
cJSON_Delete()          // 递归释放所有节点