WebServer.h: маршруты, параметры и обработчики

Сервер из урока про WiFiServer у меня жил и работал: две кнопки на странице, светодиод слушается. А потом я захотел больше — яркость, режим, график показаний — и разбор запроса превратился в кашу. Все команды жили в одной indexOf-простыне: если путь /led — одно, если /mode — другое, если /bright — третье, и к каждому ещё параметр вытащи. Когда я вписал четвёртое действие, задел переменную соседнего if-а — и светодиод молча перестал слушаться, хотя страница открывалась как ни в чём не бывало. Полчаса я смотрел в код, не понимая, где сломался.

Сломалась архитектура, а не строка. Все запросы — в одной ветке кода, и каждое новое действие тащит за собой правку общего условия. Библиотека WebServer.h, которая ставится вместе с ядром ESP32, переворачивает подход: запросы раздаются по таблице маршрутов, у каждого пути — собственная функция-обработчик, а аргументы после вопросительного знака библиотека парсит сама. В этом уроке пересобираем тот сервер на новых рельсах: маршруты /led и /status, параметры вроде state=on, вежливый 404 и JSON-ответ для скриптов.

Идея та же, что в serial-командном парсере: каждая команда получает свою функцию, и общий цикл только разводит потоки. Только здесь команды приходят не из монитора, а по HTTP: браузер стучится на адрес платы, и первая строка запроса — GET /led?state=on HTTP/1.1 — это маршрут /led с аргументом state=on. Регистрация маршрута — одна строка: server.on("/led", handleLed). Столько раз, сколько маршрутов. Ни одного if на уровне «какой путь пришёл» — библиотека сравнит пути сама и вызовет нужную функцию.

Пара слов об именах и методах. WebServer.h понимает и фильтр метода: server.on("/led", HTTP_GET, handleLed) отвечает только на GET, а форма с POST уйдёт мимо — для форм регистрируйте отдельный маршрут с HTTP_POST. Обработчики я называю по шаблону «handle + путь»: handleLed, handleStatus, handleReset — через месяц в таблице из восьми маршрутов без подсказок видно, кто за что отвечает. Типичный набор моего домашнего проекта: / — страница, /led?state= — команда, /status — JSON, /reset — перезагрузка. Маршруты растут списком по одной строке, и код не превращается в ветвистый куст, который страшно трогать.

Три вызова держат весь сервер. server.on(путь, функция) — таблица маршрутов, записывается один раз в setup(). server.handleClient() в loop() — насос, который забирает из сети пришедший запрос, находит маршрут и запускает обработчик; вызывается на каждом обороте цикла. server.onNotFound(функция) — сачок для всего остального: путь, которого нет в таблице, попадает туда, и вы сами решаете, что ответить. Внутри обработчика вам доступны аргументы запроса, URI и метод — с ними и работаем дальше.

Аргументы — самая вкусная часть. Браузер шлёт /led?state=on&brightness=120, а WebServer.h уже разложил это на полки: server.arg("state") вернёт "on", server.arg("brightness") — "120", server.args() — количество аргументов, server.argName(0) — имя первого. Процент-кодирование библиотека тоже разворачивает: %20 из пробела превратится обратно в пробел до того, как вы увидите строку. Единственная ловушка — у server.arg("имя") нет встроенной проверки существования: нет такого аргумента — вернётся пустая строка. Поэтому рядом живёт server.hasArg("имя"), и моё правило — сначала hasArg, потом arg. Добытое число — уже топливо для периферии: brightness=120 на живой плате становится заполнением ШИМ. Ниже — интерактивная песочница: покрутите ползунок duty и посмотрите, как число 0-255 превращается в яркость светодиода и в прямоугольный сигнал на осциллограмме.

Разбор по строкам. Обработчик handleLed сначала проверяет server.hasArg("state") — если кто-то открыл голый /led без аргумента, состояние не трогается, а страница всё равно отдаётся. Значение достаётся server.arg("state") и сравнивается с "on"; светодиод переключается одним digitalWrite. Ответ — server.send(код, тип, тело): для людей text/html, для скриптов application/json. Разделение «людям HTML, программам JSON» я считаю главным правилом аккуратного сервера: страница /led для пальца, /status — для скрипта, который рисует табло.

JSON здесь собран вручную конкатенацией, потому что зависимостей меньше. Как только захотите вложенные объекты и массивы — переходите на ArduinoJson, у нас есть урок про сборку своего JSON: там serializeJson складывает документ в строку без ручных кавычек-лесенок, в которых я дважды терял экранирование. Обработчик 404 печатает server.uri() — путь, который запросили. Через неделю лог 404-х покажет вам и опечатки собственных закладок, и чужие сканеры, которые пробуют плату на известные дыры.

Строку в число превращайте честно: server.arg("brightness").toInt() даёт 120 из "120", и дальше можно рулить яркостью через ШИМ или позицией сервы. На примере — второй аргумент в строке запроса: /led?state=on&brightness=120 — библиотека разложит оба, и arg("brightness") вернёт именно "120", а не всю строку аргументов. Мой грех первых серверов — выписывать значения в Serial и вбивать их руками: toInt() есть прямо под рукой, и аргумент из URL становится числом за одну строку.

Число с условием, которое стоит помнить: пока выполняется обработчик, весь остальной скетч стоит. handleClient() — обычный вызов в loop(), он не умеет параллелить: один браузер ждёт — датчики, экран и кнопки ждут вместе с ним. Для страницы в 200 байт это миллисекунды, и я живу спокойно. Но если в обработчик появится delay() или цикл на пять секунд — сервер ослепнет на всё это время. Именно на этом я и обожёгся в первый вечер, а систематически лечится это асинхронным сервером — ему посвящён следующий урок про ESPAsyncWebServer.

Браузера в симуляторе нет, и роутинг WebServer.h движок не понимает — поэтому встанем на место браузера сами. Маршрут, который на живой плате присылает страница, вы печатаете в строку ввода монитора: /led?state=on, /status или любую окрошку — и «сервер» разбирает её тем же способом, что и библиотека: путь до вопросительного знака, аргументы после. На живой плате эту работу делает WebServer.h из скетча выше; логика разбора и ответы — один в один.

План на прогонку такой. Сначала /led?state=on — светодиод загорится, и сервер ответит строкой 200 OK led=on. Потом /led?state=off — погаснет. Затем /status — увидите JSON с текущим состоянием, ровно тот, который скрипт-табло разбирает на живой плате. И напоследок заведомо кривой путь вроде /nope — сервер честно ответит 404 Not Found и покажет путь, которого не понял. Если хотите потренировать разбор строк подробнее, у нас есть урок про команды из монитора порта — там тот же приём, только без сети.

Прежде чем писать маршруты на живой плате, я советую минуту бумаги: столбик путей, рядом аргументы, справа — что отвечает каждый. Для поливалки мой список выглядел так: / — страница с двумя ссылками, /pump?state=on и /pump?state=off — реле, /status — JSON с влажностью и состоянием реле, всё остальное — 404. Четыре строки таблицы маршрутов, и код пишется сам: каждый маршрут — короткая функция, в которой нет ни одного чужого дела. Бумага ещё и ловит лишнее: когда маршрут в списке нечем оправдать, его вычёркиваешь до того, как он съел вечер.

Теперь сервер выглядит как взрослая программа: маршруты — отдельные функции, неизвестное — в 404, данные — отдельным JSON-маршрутом. Предел этой архитектуры — один клиент за раз: пока обработчик отдаёт страницу, остальные ждут, и каждый delay() в любом месте цикла это усугубляет. Что меняется, когда обработчики переезжают в сетевую задачу чипа и loop() остаётся свободным при десяти открытых браузерах — разберём в уроке про асинхронный сервер. А если нужна сеть без роутера — плата сама раздаёт свою точку доступа, как в уроке про SoftAP: портал настройки на 192.168.4.1 собирается из этих же маршрутов.