ArduinoJson 7.0版本中JsonDocument重用问题的分析与解决方案

问题背景

在使用ArduinoJson库进行JSON文档处理时，从6.x版本升级到7.x版本后，用户遇到了一个运行时断言错误。错误发生在尝试重用已清除的JsonDocument对象时，具体表现为const VariantPoolList.hpp:98 (poolIndex < count_)的断言失败。

问题现象

当开发者尝试以下操作序列时会出现问题：

1. 创建一个JsonDocument对象
2. 填充数据并发送
3. 调用clear()方法清除文档
4. 再次尝试重用该文档填充新数据

在ArduinoJson 7.0.1及之前版本中，这种重用模式会导致内存池索引越界的运行时错误。

技术分析

根本原因

该问题的根源在于ArduinoJson 7.0.1版本中VariantPoolList的实现存在缺陷。当JsonDocument被清除后，其内部的内存池管理没有正确重置状态，导致后续重用文档时内存池索引计算错误。

重现步骤

通过以下简化代码可以稳定重现该问题：

#include <ArduinoJson.h>

void fill(JsonObject &obj) {
  obj["foo-bar-baz"] = "foo-bar-baz-foo-bar-baz";
}

void send(JsonObject &obj) {
  serializeJson(obj, Serial);
  Serial.println("");
  obj.clear();  // 问题出在这里
}

void setup() {
  Serial.begin(115200);
  JsonDocument doc;

  {
    JsonObject obj = doc.to<JsonObject>();
    obj["command"] = "update:components";
    obj["tabs"][0]["id"] = "0";
    send(obj);
  }

  {
    JsonObject obj = doc.to<JsonObject>();
    obj["command"] = "update:components";
    JsonObject card = doc["cards"].add<JsonObject>();
    fill(card);
    send(obj);  // 这里会触发断言失败
  }
}

void loop() { }

临时解决方案

在ArduinoJson 7.0.2修复发布前，开发者可以采用以下两种临时解决方案：

1. 避免重用JsonDocument，每次创建新实例
2. 注释掉clear()调用（不推荐，会导致内存泄漏）

官方修复

ArduinoJson作者在7.0.2版本中修复了这个问题。修复主要针对VariantPoolList的内存池管理逻辑，确保在文档清除后能正确重置内部状态。

最佳实践建议

即使问题已修复，作者仍建议开发者遵循以下JSON文档使用原则：

1. 短生命周期原则：尽量缩短JsonDocument的生命周期，使用完毕后立即释放
2. 避免重用：为每个JSON操作创建新的文档实例，而非重用已清除的实例
3. 作用域控制：使用大括号{}限制变量作用域，确保资源及时释放

性能考量

开发者常有的一个误区是认为重用JsonDocument比创建新实例性能更好。实际上：

• clear()和析构的开销基本相同
• 新创建实例的代码更易于理解和维护
• 短生命周期有助于减少内存占用

结论

ArduinoJson 7.0.2已彻底解决JsonDocument重用问题。开发者应升级到最新版本，并遵循短生命周期的最佳实践来使用JSON文档。对于需要分批发送数据的场景，建议为每批数据创建独立的JsonDocument实例，而非尝试重用同一个文档。