Фильтры ArduinoJson: разбираем только нужное

На настенной панели погоды — Uno, LCD 16×2, кнопка смены экрана — я однажды решил посчитать свободную память классическим freeRam(). Панель жила сама: раз в десять минут ходила в погодный сервис, брала температуру и влажность, рисовала их на экране. Ответ сервиса был подробный: город, часовой пояс, почасовой прогноз на десять значений, восход, закат, ультрафиолет, видимость. Мне из всего ответа нужны были два числа — а в документе после разбора лежало всё.

Разница оказалась не косметической. Из восьми полей ответа на экран попадали два; остальное документ держал в ОЗУ просто потому, что так работает deserializeJson без фильтра: разбор кладёт в документ всё, что пришло. На ESP32 с её сотнями килобайт это была бы безделица, на Uno с двумя килобайтами SRAM — заметная строка в бюджете, который мы считали ещё в первом уроке раздела. А по смыслу мне нужен был документ фиксированного состава: два ключа, ни больше ни меньше.

Такой документ ArduinoJson умеет делать из коробки: к deserializeJson добавляется третий аргумент — фильтр, второй документ-образец, в котором вы перечисляете, что брать. Приём появился в версии 6.15 весной 2020 года и с тех пор стал штатным способом разбирать подробные ответы на маленьких платах. В этом уроке разберём механику: как описать фильтр, что попадает в документ, а что нет, как отфильтровать вложенность и массив. Про ответы, которые сами не влезают в ОЗУ, — отдельный урок дальше по разделу; здесь — базовый случай, когда места хватает, но жалко.

Фильтр описывается тем же документом, что и результат: завели JsonDocument filter, записали в него ключи — filter["temp"] = true; filter["humi"] = true; — и передали в разбор третьим аргументом: deserializeJson(doc, packet, DeserializationOption::Filter(filter)). Читается так: из packet в doc возьми то, что перечислено в filter. Ключ со значением true — брать; ключа нет в фильтре или он false — пропустить. В шестой версии фильтр заводят как StaticJsonDocument<192> с явной ёмкостью, в седьмой — обычным JsonDocument, он растёт сам; отличие версий мы разбирали в уроке про JsonDocument в седьмой версии. Сам вызов разбора и его коды — тема урока про deserializeJson; здесь считаем, что строка доходит целой и корректной.

Главное свойство: в doc после такого разбора лежат только выбранные поля. Не «лежат все, но лишние помечены» — именно только выбранные. containsKey("wind") после разбора с фильтром без ветра честно ответит «нет» — и это не сбой, а результат: состав документа повторяет состав фильтра, как списку и положено. С фиксированным составом удобнее проверять данные после разбора: приёмы из урока про чтение полей и оператор | перестают ловить сюрпризы, которых вы сами не заказывали.

Фильтр умеет работать и глубже корня. Хотите ветку целиком — вложите объект: filter["forecast"]["day"] = true заберёт поле day из вложенного объекта forecast. Пустой фильтр {} разберёт строку в пустой документ — так дёшево проверяют, что источник вообще JSON, не тратя места под значения. Рабочий скетч для настоящей платы — ниже, а шпаргалка по вариантам — таблицей под конец урока.

Фильтр удобно настроить один раз и не трогать: заводите filter глобально, заполняете в setup() — и дальше каждый разбор в loop() идёт с одним и тем же списком желаний. Мой панельный скетч после переделки стал короче на пару строк и потерял одну сущность: раньше после разбора я мысленно игнорировал поля, которые не собирался показывать, теперь их в документе просто нет. Проверка containsKey для ветра возвращает ноль — и это не отсутствие данных, а осознанное решение, принятое на уровне фильтра.

Разберёмся с ценой честно. Фильтр экономит память под документ: значения неперечисленных полей не копируются в doc, на них не уходит ни байта ёмкости. Время разбора тоже падает — библиотека пропускает размещение значений, — но не до нуля: по строке парсер всё равно идёт целиком, от первой скобки до последней, чтобы не потерять структуру. И канал фильтр не ужимает: ответ приходит по сети полностью, два килобайта останутся двумя килобайтами в проводе.

Поэтому моя связка такая: фильтр плюс приём по возможности без промежуточной String. На ESP32 мы разбирали связку HTTPClient и ArduinoJson: deserializeJson умеет читать прямо из потока http.getStream(), и опция Filter передаётся туда же третьим аргументом — тогда ни полная строка, ни полный документ память не занимают. Если приём идёт в String, а на Uno часто иначе не выходит, выигрыш от фильтра всё равно есть: строка одна, а документ — половинный или четвертной. Приём строки по кускам, если сервис шлёт пакеты порциями, — приёмы из урока про Serial.available: собрали полный пакет, потом один deserializeJson с фильтром.

Второй эффект я заметил позже и ценю не меньше памяти: документ фиксированного состава упрощает отладку. Когда в doc лежит всё подряд, ветка «ключа нет» означает сбой сервиса. Когда в doc только отфильтрованное, «ключа нет» почти всегда означает, что фильтр описан не так, как ответ. Круг подозреваемых сужается до одной строки — той, где заполняется filter.

Практическая деталь: фильтр живёт в памяти постоянно, как и основной документ, — под него тоже выделяется ёмкость. Поэтому фанатизм тут вреден: фильтр на сорок ключей ради двух полей удержит больше места, чем сам выигрыш. Мой ориентир: фильтр в десять-двадцать раз меньше ожидаемого полного ответа — тогда он окупается с первого же разбора. Заполняется он теми же присваиваниями, что и обычный документ: true под ключом — то же присваивание, только семантика другая.

Движок книги опцию DeserializationOption::Filter не поддерживает — говорю честно заранее — и вместо неё показывает эффект: урезанная строка перед разбором. То, что на плате отобрал бы фильтр, здесь вырезано из строки руками: на вход подаются два пакета, полный и отобранный, и оба разбираются в свои документы. Урезанная строка — это ровно результат работы фильтра, только выполненный заранее.

Размер показывает measureJson: он считает длину печати документа, и разница между полной и отобранной версией видна в байтах: в скетче ниже полный документ печатается на 70 символов, отобранный — на 23, меньше трети. На настоящей плате разница в ОЗУ ещё заметнее: под каждый ключ и значение в документе тратится место сверх самой печати, поэтому экономия фильтра там растёт, а не падает. Чтение полей в сим-скетче — точечной формой doc.temp: на плате она равнозначна doc["temp"], а движок понимает только точку.

Проверьте сами: добавьте в отобранную строку поле press — и measureJson подрастёт ровно на его длину; уберите humi — упадёт. На плате ту же работу делает filter-документ: добавили строку filter["press"] = true; — поле поехало в результат.

Дальше — вторая половина темы: ответы, которые сами не влезают в ОЗУ. Фильтр на два поля с письма на два килобайта снимает сотни байт, но если строка занимает всю SRAM ещё при приёме, нужна более грубая артиллерия: разбор из потока, фильтр с лимитом на массивы и честный подсчёт байтов. Об этом — урок про большие ответы. Домашнее задание: возьмите свой любимый API, посчитайте глазами, сколько полей вам реально нужно, напишите filter-документ и сравните на плате длину печати полного и отобранного документа через measureJson — разница обычно отрезвляет. И когда вернётесь к панели с экраном — попробуйте добавить третий отобранный показатель: фильтр расширится одной строкой, а документ останется фиксированным.