ESP32 JSON 解析

ESP32 上的 JSON 解析：不只是“能用”，而是“高效、稳定、优雅”

你有没有遇到过这样的场景？设备连上了 MQTT，云端下发了一条配置指令，结果 ESP32 一解析就崩溃了——不是重启就是卡死。查了半天日志，最后发现是 NoMemory 错误。😅

或者更离谱的是，明明 JSON 格式完全正确，但取出来的值却是乱码？字符串指针指向了已经释放的缓冲区……这种问题不致命，却足够让你在凌晨两点对着串口调试器发呆。

别笑，这都是我们踩过的坑。而这一切，往往都源于一个看似简单的操作： 解析一段 JSON 字符串 。

在物联网的世界里，JSON 几乎无处不在。从阿里云 IoT 平台到 Home Assistant，从 REST API 到 OTA 更新包，数据格式清一色是 JSON。ESP32 作为最受欢迎的 Wi-Fi+蓝牙双模 MCU，自然成了处理这些数据的主力选手。

可问题是，ESP32 虽强，但它本质上还是个嵌入式设备 —— 内存有限、资源紧张。你不能像写 Python 那样随心所欲地 json.loads() ，否则轻则内存溢出，重则系统崩塌。

所以今天咱们不讲那些泛泛而谈的“怎么用 ArduinoJson”的入门教程。我们要深挖：
👉 为什么有些 JSON 解析会失败？
👉 同样的库，在不同情况下性能差异为何巨大？
👉 如何让 ESP32 在只有几 KB 可用 RAM 的情况下，依然安全地处理复杂的 JSON 数据？

准备好了吗？来吧，一起走进 ESP32 上最真实、最硬核的 JSON 解析实战。

---

为什么不能直接用标准 JSON 库？

先问一个问题：既然 C++ 有 nlohmann/json 这种现代、漂亮、功能齐全的 JSON 库，为什么不直接拿来给 ESP32 用？

答案很现实： 它太“胖”了 。

nlohmann/json 是为桌面级或服务器级应用设计的，依赖完整的 STL 和动态类型系统。编译后动辄几十 KB 甚至上百 KB 的代码体积，对 Flash 来说可能还能接受，但它的运行时行为才是真正的杀手：

• 大量临时对象分配
• 深度递归调用栈
• 不可控的堆内存增长

而 ESP32 的典型可用堆空间（SRAM）也就 300KB 左右，还要分给 TCP/IP 协议栈、WiFi 驱动、任务调度……留给你的可能不到 100KB。

更别说如果你用了 LVGL 做 UI 或者音频解码这类内存大户，那真是“雪上加霜”。

所以，我们必须换一种思路： 不是让硬件适应软件，而是让软件适配硬件 。

这就引出了目前 ESP32 社区事实上的标准答案 —— ArduinoJson 。

---

ArduinoJson 真的只是“方便”吗？

很多人觉得 ArduinoJson 好用，是因为它 API 简洁、文档齐全、例子丰富。但这只是表象。

真正让它成为 ESP32 上 JSON 处理王者的原因，是它从底层就开始为嵌入式环境量身定制的设计哲学。

它的核心思想是什么？

一句话总结： 预分配 + 统一内存池 + 最小化拷贝 。

什么意思？我们来看一段典型的解析流程：

const char* json = "{\"temp\":25.3,\"humid\":60}";
DynamicJsonDocument doc(512);
deserializeJson(doc, json);
float t = doc["temp"];

这段代码背后发生了什么？

1. DynamicJsonDocument(512) 在堆上申请一块 连续的 512 字节内存块 ；
2. deserializeJson() 把输入字符串逐字符扫描，把键名、数值、结构信息统统塞进这块内存；
3. 所有数据共用这个“池子”，没有额外 malloc；
4. 访问 doc["temp"] 实际上是在池子里查找对应节点。

整个过程就像搭积木：所有零件都来自同一盒材料，绝不临时去买新的。

这种设计带来了几个关键优势：

✅ 避免碎片化 ：一次性分配，一次性释放，不怕长期运行导致 heap 碎片
✅ 控制上限 ：你知道最多消耗多少内存，可以提前防御性判断
✅ 速度快 ：无需频繁系统调用，缓存友好，适合低速 CPU

🤔 小知识： deserializeJson() 默认不会复制字符串内容，而是直接保存原始指针！这意味着如果原始 json 缓冲区被释放或覆盖，后续访问就会出错 —— 很多初学者栽在这里。

---

静态 vs 动态文档：选哪个？什么时候选？

ArduinoJson 提供两种主要容器类型：

• StaticJsonDocument<N> ：在栈上分配固定大小 N 的内存
• DynamicJsonDocument ：在堆上动态分配，大小可变

听起来好像后者更灵活，是不是应该无脑选它？

错！恰恰相反，在大多数情况下你应该优先考虑静态文档。

为什么推荐 StaticJsonDocument ？

因为它快、安全、确定性强。

举个例子：

void handleConfig() {
    StaticJsonDocument<256> doc;
    deserializeJson(doc, input_buffer);
    // ...
} // 函数结束自动释放，零泄漏风险

这段代码：
- 分配在栈上 → 快速
- 生命周期明确 → 不会泄漏
- 不涉及 heap → 不怕碎片

相比之下， DynamicJsonDocument 虽然灵活，但每次 new/delete 都要走 heap 分配路径，而且容易忘记释放（尤其是在异常分支中）。

那什么时候该用动态的？

当你面对的数据尺寸不确定时。

比如接收 OTA 固件元信息，可能小到 200B，也可能大到 2KB。这时候你不可能定义一个 StaticJsonDocument<2048> 放在栈上 —— 栈空间通常只有几 KB，这么大会导致栈溢出！

正确的做法是：

if (payload_length > 512) {
    DynamicJsonDocument* doc = new DynamicJsonDocument(payload_length * 2);
    // ... 解析
    delete doc; // 记得释放！
}

当然，更好的方式是结合 RAII 模式封装成智能指针，但我们后面再说。

如何估算所需容量？

这是最关键的一步。很多人随便写个 1024 ，结果偶尔报 NoMemory ，查半天才发现是刚好超了几个字节。

ArduinoJson 官方提供了一个神器： ArduinoJson Assistant 。

你只要贴入示例 JSON，它就会告诉你最小推荐容量。例如：

{
  "device": "esp32",
  "sensors": [
    {"type": "temp", "val": 25.3},
    {"type": "humid", "val": 60}
  ]
}

Assistant 会告诉你至少需要 320 bytes 。

💡 实践建议：实际使用时建议在此基础上再增加 20%~50%，以防未来字段扩展。

---

内存池的秘密：Object Pool 和 String Pool

你以为 JsonDocument 就是一个大数组？其实它内部有两个独立区域协同工作：

1. Object Pool（对象池）

存储所有 JSON 结构的“骨架”信息，包括：
- 键名指针
- 值的类型（string/number/bool/array/object）
- 子节点索引或指针
- 引用计数等元数据

每个对象节点大约占用 16~32 字节，具体取决于架构和配置。

2. String Pool（字符串池）

用来存放字符串的实际内容。这里有两种策略：

策略	行为	适用场景
Copy	复制字符串到池内	输入缓冲区短暂存在（如网络包）
Reference	只保存指针	输入长期有效，想省内存

默认情况下，ArduinoJson 对长度小于 32 字符的字符串进行复制，长字符串则引用原地址 —— 这叫 zero-copy parsing 。

⚠️ 危险案例：引用失效

char* getJsonFromHttp() {
    char tmp[256];
    http.readBytes(tmp, len);
    return tmp; // 返回栈变量指针！
}

void badExample() {
    const char* json = getJsonFromHttp(); // 已经悬空！
    DynamicJsonDocument doc(512);
    deserializeJson(doc, json); // 解析成功，但字符串指针非法！
    const char* device = doc["device"];   // 下次访问可能出错！
}

这就是典型的“侥幸心理”编程：有时候能跑通，换个编译选项就崩了。

✅ 正确做法是强制复制：

deserializeJson(doc, json, DeserializationOption::CopyString());

或者干脆先把数据拷贝到全局缓冲区。

---

PSRAM：救命稻草还是饮鸩止渴？

很多开发者听说 ESP32 支持外接 PSRAM（通常是 4MB），于是兴奋地以为：“哇，我可以处理超大 JSON 了！”

理论上没错，但实际上你要小心几个陷阱。

启用 PSRAM 的前提条件

• 使用支持 PSRAM 的模块（如 ESP32-WROVER）
• 在开发环境中启用选项（Arduino IDE 中勾选，PlatformIO 加 -D BOARD_HAS_PSRAM ）
• 初始化时调用 ps_init() （某些 SDK 需手动）

一旦启用，你可以通过 ps_malloc() 分配内存到外部 RAM。

怎么让 ArduinoJson 用 PSRAM？

最简单的方法是重载 operator new ：

#ifdef BOARD_HAS_PSRAM
    void* operator new(size_t size) { return ps_malloc(size); }
    void* operator new[](size_t size) { return ps_malloc(size); }
#endif

这样所有 new DynamicJsonDocument(...) 都会优先使用 PSRAM。

但这招有点“暴力”，会影响整个程序的行为。更精细的做法是自定义分配器，不过 ArduinoJson v6 不支持，得等到 v7。

PSRAM 的代价你知道吗？

虽然容量大，但 PSRAM 比内部 SRAM 慢得多！

特性	Internal SRAM	PSRAM
速度	~133MHz	~40MHz（QSPI）
延迟	极低	较高
功耗	低	略高
是否可执行代码	✅ 是	❌ 否（仅数据）

所以你不该把它当作“无限内存”，而应视为“冷存储区”。就像电脑里的 SSD 和内存条的区别。

✅ 推荐用途：
- 存储大型 JSON 配置文件
- 缓存地图、语音脚本等非实时数据
- 图像帧缓冲（配合 TFT 屏）

❌ 不推荐：
- 实时传感器处理中间结果
- 中断上下文中的临时变量
- 高频访问的小对象

---

实战：MQTT 配置更新系统的健壮实现

让我们来看一个真实项目中的典型需求：

设备启动后连接 MQTT Broker，订阅 /config/device-123 主题。当云端推送新配置时，解析并应用参数，然后回复确认消息。

目标：既要快速响应，又要防止因 JSON 异常导致设备宕机。

Step 1：定义消息格式

{
  "version": 2,
  "cmd": "update_interval",
  "params": {
    "sample_interval_sec": 10,
    "upload_interval_sec": 30,
    "led_blink": true
  },
  "timestamp": 1712345678
}

Step 2：编写健壮解析函数

struct DeviceConfig {
    int sample_interval_sec = 5;
    int upload_interval_sec = 15;
    bool led_blink = false;
};

bool parseConfigUpdate(const char* payload, size_t len, DeviceConfig& config) {
    // 安全边界检查
    if (!payload || len == 0 || len > 2048) {
        log_e("Invalid payload length: %zu", len);
        return false;
    }

    // 创建足够大的动态文档（使用 PSRAM）
    DynamicJsonDocument* doc_ptr = new (std::nothrow) DynamicJsonDocument(1536);
    if (!doc_ptr) {
        log_e("Failed to allocate JsonDocument");
        return false;
    }
    auto& doc = *doc_ptr;

    // 设置最大嵌套深度（防恶意攻击）
    doc.setNestingLimit(8);

    // 解析（允许 UTF-8，复制短字符串）
    DeserializationError error = deserializeJson(
        doc, 
        payload, 
        len,
        DeserializationOption::FilterAndDetectUtf8()
    );

    if (error) {
        log_e("JSON parse failed: %s (code: %d)", error.c_str(), error.code());
        delete doc_ptr;
        return false;
    }

    // 提取顶层字段
    if (!doc.containsKey("cmd") || !doc["cmd"].is<const char*>()) {
        log_w("Missing or invalid 'cmd'");
        delete doc_ptr;
        return false;
    }

    const char* cmd = doc["cmd"];

    if (strcmp(cmd, "update_interval") != 0) {
        log_w("Unsupported command: %s", cmd);
        delete doc_ptr;
        return false;
    }

    // 读取 params 对象
    JsonObject params = doc["params"];
    if (params.isNull()) {
        log_w("Missing 'params' object");
        delete doc_ptr;
        return false;
    }

    // 安全提取数值（使用 | 提供默认值）
    config.sample_interval_sec = params["sample_interval_sec"] | config.sample_interval_sec;
    config.upload_interval_sec = params["upload_interval_sec"] | config.upload_interval_sec;
    config.led_blink = params["led_blink"] | config.led_blink;

    // 合理性校验
    if (config.sample_interval_sec < 1 || config.sample_interval_sec > 3600) {
        log_w("Invalid sample interval: %d", config.sample_interval_sec);
        config.sample_interval_sec = 5; // reset to safe default
    }

    log_i("✅ Config updated: sample=%d, upload=%d, blink=%s",
          config.sample_interval_sec,
          config.upload_interval_sec,
          config.led_blink ? "yes" : "no");

    delete doc_ptr;
    return true;
}

关键设计点解析：

1. 输入验证先行 ：长度、空指针、最大限制，防止越界
2. 错误码详细记录 ： error.code() 可用于分类统计故障类型
3. 使用 | 操作符设置默认值 ：即使字段缺失也不影响整体逻辑
4. 业务层校验 ：时间间隔必须在合理范围内
5. RAII 式清理 ：确保无论在哪一步失败都能释放内存

如何发送回执？

生成响应也很简单：

String generateAckResponse(const char* original_cmd) {
    DynamicJsonDocument doc(128);
    doc["status"] = "ok";
    doc["cmd"] = original_cmd;
    doc["timestamp"] = time(nullptr);

    String output;
    serializeJson(doc, output);
    return output;
}

注意这里用了 String ，虽然方便但会产生一次内存复制。追求极致性能可用 char buffer[128] 配合 serializeJson(doc, buffer) 。

---

流式解析：当内存真的不够用怎么办？

前面说的都是“全量加载”模式 —— 先把整个 JSON 读进内存，再统一解析。

但如果遇到以下情况怎么办？

• JSON 文件超过 10KB（比如固件描述清单）
• 设备没有开启 PSRAM
• 多个任务并发处理 JSON

这时你就需要 流式解析（Streaming Parsing） 。

遗憾的是，ArduinoJson v6 不原生支持流式解析。但它可以通过配合 Stream 接口实现部分能力。

替代方案：使用 cJSON 的流式特性

虽然 cJSON 比 ArduinoJson 更底层、API 更繁琐，但它有一个不可替代的优势： 增量解析 。

#include "cJSON.h"

bool streamParseLargeJson(Stream& input) {
    cJSON_stream stream;
    cJSON_InitStream(&stream, &input);  // 假设有适配层

    cJSON* item;
    while ((item = cJSON_ParseStream(&stream)) != NULL) {
        // 逐个处理对象
        processItem(item);
        cJSON_Delete(item);
    }

    return stream.eof;
}

这种方式适用于日志流、事件流等连续数据源。

不过对于大多数 ESP32 应用来说，99% 的场景都不需要走到这一步。 优先优化数据结构比换库更有意义。

比如：能不能把一个大 JSON 拆成多个小主题发布？能不能用二进制协议替代 JSON？这些都是更高层次的优化。

---

高阶技巧：提升效率与安全性的五把利器

🔧 1. 使用 PROGMEM 存储模板

如果你经常发送相同结构的 JSON（如心跳包），可以用 F() 或 PSTR 把模板放 Flash：

const char CONFIG_TEMPLATE[] PROGMEM = R"({
    "device_id": "%s",
    "fw_version": "%s",
    "uptime": %lu
})";

void sendHeartbeat(const char* id, const char* fw, unsigned long up) {
    char buffer[256];
    sprintf_P(buffer, PSTR(CONFIG_TEMPLATE), id, fw, up);

    DynamicJsonDocument doc(256);
    deserializeJson(doc, buffer);
    // ... 修改特定字段
    serializeJson(doc, Serial);
}

节省 RAM，还能加快启动速度。

🔧 2. 预计算序列化大小

避免缓冲区溢出的好办法是提前知道要多少空间：

size_t required = measureJson(doc);
char* buf = (char*)malloc(required + 1);
if (buf) {
    serializeJson(doc, buf, required + 1);
    client.print(buf);
    free(buf);
}

🔧 3. 使用命名空间隔离复杂结构

当 JSON 层级很深时，链式访问容易出错：

// 容易崩！
double lat = doc["data"]["location"]["coordinates"][0];

// 改成逐步判断
JsonObject data = doc["data"];
if (!data.success()) return;

JsonObject loc = data["location"];
if (!loc.success()) return;

JsonArray coords = loc["coordinates"];
if (coords.size() < 2) return;

double lat = coords[0];

虽然啰嗦，但胜在稳健。

🔧 4. 自动化测试你的解析器

别等到上线才发现问题。写几个单元测试：

TEST(ParseConfig, ValidInput) {
    DeviceConfig cfg;
    const char* json = R"({"cmd":"update_interval","params":{"sample_interval_sec":20}})";
    bool ok = parseConfigUpdate(json, strlen(json), cfg);
    REQUIRE(ok);
    REQUIRE(cfg.sample_interval_sec == 20);
}

TEST(ParseConfig, MissingParams) {
    DeviceConfig cfg{10,10,false};
    const char* json = R"({"cmd":"update_interval"})";
    bool ok = parseConfigUpdate(json, strlen(json), cfg);
    REQUIRE(ok); // 应该成功，使用默认值
    REQUIRE(cfg.sample_interval_sec == 10); // 保持原值
}

用 Unity + PlatformIO 就能跑起来。

🔧 5. 监控内存使用趋势

在生产环境中添加简单的内存监控：

void logMemoryUsage(const char* tag) {
    log_i("[%s] Heap: %d, PSRAM: %d", 
          tag,
          ESP.getFreeHeap(),
          ESP.getFreePsram());
}

每隔一段时间打一次日志，观察是否有缓慢泄漏。

---

常见陷阱与避坑指南

问题	原因	解法
NoMemory 错误	文档太小或字符串太多	用 Assistant 计算 + 开启 CopyString
解析成功但取不到值	键名拼写错误 / 类型不符	打印 .containsKey() 和 .is<T>() 调试
设备随机重启	栈溢出（StaticDoc太大）	改用 Dynamic + 检查任务栈大小
字符串乱码	输入缓冲区被复用	提前复制到稳定内存
解析耗时过长	JSON 过于复杂	简化结构 / 改用二进制协议

还有一个隐藏雷区： 中文或其他 UTF-8 字符 。

ArduinoJson 支持 UTF-8，但如果你的源字符串编码不对（比如 GBK），就会解析失败。建议始终确保传输层使用 UTF-8 编码。

---

写到最后：工具之外，思维更重要

你看，我们聊了这么多技术细节：内存模型、PSRAM 优化、错误处理、流式解析……

但真正决定一个系统是否可靠的，往往不是用了多高级的库，而是开发者有没有建立起 资源意识 和 防御性编程习惯 。

下次当你写下 DynamicJsonDocument doc(2048); 的时候，请多问自己一句：

“我真的需要这么大吗？”
“这个 JSON 最大可能是多少？”
“如果超了会怎样？”

这些问题的答案，才是真正区分普通开发者和高手的地方。

毕竟，在嵌入式世界里， 每一次内存分配，都是一次承诺；每一次指针使用，都是一次信任。

而我们的任务，就是不让它们落空。🛠️