Группы и версии API: e.Group, общие middleware и поддеревья v1/v2

Тема «echo группы» начинается с проблемы, которую вы уже могли нащупать в каноне десятого урока: маршрутов становится много, и у большинства из них общие свойства. Пять эндпоинтов задач хотят один и тот же bearerAuth, будущие /healthz и /metrics — ничего, а следующая мажорная версия API хочет всё то же самое, но с другими настройками. Размазывать эти решения по каждому вызову v1.GET("/tasks", listTasks, bearerAuth(...)) — значит копировать одну и ту же строку десятки раз и молиться, что при следующем изменении никто не забудет обновить половину копий. Echo решает это слоем организации: e.Group(prefix, m...) возвращает структуру Group — заготовку поддерева маршрутов с общим префиксом и общими middleware. Дальше вы регистрируете маршруты уже на ней, и оба свойства приклеиваются автоматически.

Ключевое слово здесь — поддерево: группа группирует не «все маршруты подряд», как e.Use, а конкретную ветку пути, скажем /api. Это среднее звено между двумя крайностями шестого урока: глобальные слои, которые достаются каждому запросу, и маршрутные слои, которые достаются ровно одному маршруту. Групповые слои достаются всей ветке — и это ровно та единица масштабирования, которую требуют реальные API: аутентификация на /api, лимиты на /v2, лог-формат на отдельном домене.

Открываем group.go. Док-комментарий формулирует контракт целиком: Group is a set of sub-routes for a specified route. It can be used for inner routes that share a common middleware or functionality that should be separate from the parent echo instance while still inheriting from it. Подмаршруты, разделяющие общие middleware, отделённые от родительского инстанса, но наследующие от него — каждое слово потом превратится в строку кода.

Сама структура крошечная: prefix string — клей для путей; echo *Echo — ссылка на родителя, через которую группа регистрирует маршруты; middleware []MiddlewareFunc — копилка слоёв; host string — для варианта с виртуальными хостами, который нам пока не нужен. Плюс встроенный пустой тип common — служебный носитель общих хелперов. И главное: никакого собственного роутера внутри нет. Конструктор в echo.go занимает три строки: g = &Group{prefix: prefix, echo: e}; g.Use(m...); return. Передали ли вы middleware вторым аргументом или нет — g.Use всё равно вызывается: с пустым вариадиком он станет точкой, где позже включится один важный трюк, о котором будет отдельный блок.

Каждый вызов v1.GET("/tasks", listTasks) превращается в g.Add(http.MethodGet, "/tasks", listTasks) — а его полная подпись из group.go выглядит так: func (g Group) Add(method, path string, handler HandlerFunc, middleware ...MiddlewareFunc) Route. Внутри слои сливаются в НОВЫЙ срез: сначала всё, что накопила группа, потом слои, переданные прямо при регистрации маршрута. Копия — не педантизм: комментарий в исходнике — Combine into a new slice to avoid accidentally passing the same slice for multiple routes, which would lead to later add() calls overwriting the middleware from earlier calls — объясняет, что иначе один и тот же срез мог бы случайно уехать в несколько маршрутов, и поздние регистрации перезаписали бы слои ранних. Затем маршрутизирующий вызов: g.echo.add(g.host, method, g.prefix+path, handler, m...) — путь склеен из префикса группы и пути маршрута, и дальше работает обычный e.Add из третьего урока.

Внутри e.add живёт уже знакомое вам по восьмому уроку: замыкание маршрута при каждом запросе вызывает applyMiddleware(handler, m...), который оборачивает обработчик с конца среза. Отсюда полный порядок слоёв для запроса к /api/v1/tasks: e.Pre срабатывают до роутера («run before router»), роутер находит маршрут, глобальные e.Use — «run after router» — идут снаружи, затем слои группы, затем маршрутные, и только потом обработчик. Родительские слои всегда снаружи дочерних, групповые — всегда снаружи маршрутных: срез сливается в порядке «группа → маршрут», а applyMiddleware делает первый элемент среза самым внешним звеном.

Теперь вторая половина контракта — g.Use(middleware ...MiddlewareFunc). Первая его строка скучна: g.middleware = append(g.middleware, middleware...) — та же копилка, что у e.Use из шестого урока. Но дальше — самый нетривиальный фрагмент group.go, и док-комментарий объясняет, зачем он нужен. Групповые слои — НЕ то же самое, что глобальные Pre и Use: те исполняются всегда, потому что стоят в стеке самого Echo; групповые же исполняются только если роутер нашёл маршрут, зарегистрированный вместе с ними. А что если путь под префиксом группы не совпал ни с одним маршрутом? Роутер просто не нашёл бы маршрут — и групповые слои бы молча пропустили.

Решение Echo: после каждого g.Use с непустым списком группа регистрирует сама себе два перехватчика несуществующих путей — g.RouteNotFound("", NotFoundHandler) и g.RouteNotFound("/*", NotFoundHandler). Документация называет это «catch all route (404 is a safe way to emulate route match)»: несуществующий путь теперь совпадает с wildcard-маршрутом группы, и во время маршрутизации роутер гарантированно находит маршрут — а значит, исполняет и групповые слои. Цена трюка: 404 внутри группы с middleware начинает жить по особым правилам, и это отзовётся и в поведении с 405 — разберём после канона.

Group умеет порождать группы — и это то, из чего строятся версии api. Метод g.Group(prefix, middleware...) — подпись из group.go: func (g *Group) Group(prefix string, middleware ...MiddlewareFunc) — делает две склейки. Первая — путь: sg = g.echo.Group(g.prefix+prefix, m...), префиксы конкатенируются, /api плюс /v1 дают /api/v1; вложенность может быть глубже — дерево ответственности читается прямо в коде. Вторая — слои: новый срез наполняется сначала ВСЕМИ слоями родителя, потом новыми, и получившаяся подгруппа наследует их как свои собственные. Наследуется и поле host — у подгруппы того же виртуального домена.

Здесь спрятана вторая ловушка со срезами, зеркальная ловушка из predict-задания выше. Слои родителя копируются в подгруппу в момент её СОЗДАНИЯ: если после v1 := api.Group("/v1") написать api.Use(newLayer), то newLayer допишется в срез api и достанется маршрутам, зарегистрированным на api позже, — но в срез уже созданной v1 он не попадёт, её маршруты унаследуют только старый набор. Читаемость кода страдает сильнее корректности: дерево из трёх строк выше превращается в неявный график «кто что успел скопировать». Практическое правило: конструируйте дерево групп сверху вниз за один проход — все Use на каждом уровне до порождения следующего.

Слой bearerAuth на /api — не экономия строк, а смена точки принятия решения. Во-первых, невозможно забыть: новый маршрут, добавленный в v1 или v2, защищён ещё до того, как его написали — копия слоя прилетает из копилки группы при каждой регистрации. Во-вторых, пользователь доступен везде: bearerAuth кладёт имя пользователя под ключ ctxUserKey, и любой обработчик обеих версий достаёт его одинаково — контракт «всё под /api аутентифицировано» выполняется архитектурой, а не дисциплиной. В-третьих, изоляция: /healthz и /metrics, зарегистрированные прямо на e, в группу не входят и токена не требуют — глобальный e.Use(bearerAuth(...)) задел бы их все, и пришлось бы вырезать исключения скиппером, как в восьмом уроке.

Теперь эффект от трюка g.Use, который мы отложили. Catch-all-перехватчики зарегистрированы через g.Add — значит, несут групповые слои. Роутер гарантированно находит их для любого несовпавшего пути под префиксом — значит, слои исполняются. Практический вывод: 404 под /api идёт ЧЕРЕЗ bearerAuth. Запрос без токена на /api/v1/missing получит 401 Unauthorized от аутентификации, а не 404 Not Found от роутера: несуществующие маршруты вашего закрытого API не раскрываются неаутентифицированным клиентам. Многие команды считают это фичей, а не побочным эффектом — но знать о ней обязан каждый.

Схема «подгруппы над общим префиксом» — это и есть канонический способ строить версии api echo. Один обработчик listTasks регистрируется в v1 и в v2 — код домена не дублируется, багфикс доезжает до обеих версий одним коммитом. Вся разница версий живёт в слоях и перехватчиках уровня группы: v2 получила versionTag, v1 может получить свой слой-баннер с предупреждением об устаревании, у v2 может быть более строгий лимит запросов или другой сериализатор — каждая версия настраивает свой конфиг на своём уровне, не трогая соседей. Это и есть «изоляция конфигов между версиями», обещанная десятым уроком: различия собираются в слои на границе версии, а не размазываются if-ами по обработчикам.

У схемы есть и оборотная сторона — те самые ловушки сквозных зависимостей. Общий обработчик означает общий эволюционный груз: добавив поле в структуру задачи, вы измените ответ обеих версий сразу — если это недопустимо, различия придётся поднимать в слои раньше, чем хочется. Проверка версии внутри обработчика по c.Path() — запах: версия должна приходить слоем на границе, а не разбором пути в домене. И деприкация делайте честной: v1, помеченная устаревшей, — это всё та же подгруппа, которой добавили слой-баннер и дату заката, а не вторая копия всего дерева. Когда-нибудь v1 удалится — удалением двух строк регистрации.

Соберём связку с шестым и десятым уроками. 404 и 405 в Echo — не магия, а обработчики: NotFoundHandler возвращает ErrNotFound, MethodNotAllowedHandler — ErrMethodNotAllowed со списком методов в заголовке Allow из контекста (ContextKeyHeaderAllow). Роутер решает, какой из них отдать, в методе Find — и вот его точное правило из комментария router.go: user provided not found (404) handler has priority over generic method not found (405) handler or global 404 handler. Перехватчик 404, зарегистрированный на узле дерева, СТАВИТСЯ ВЫШЕ проверки методов: если поиск привёл в узел с notFoundHandler, вы получите 404, даже когда путь совпал, а метод нет.

Теперь соедините это с трюком g.Use — и станет ясно, почему curl-матрица вернула 404 на POST к GET-маршруту. Любая группа с middleware зарегистрировала себе catch-all — а значит, для каждого пути под префиксом существует узел с notFoundHandler, и приоритет 404 над 405 срабатывает прежде, чем роутер доберётся до MethodNotAllowedHandler. Группового аналога NoMethod у Echo нет — его место занял именно этот приоритет. Вне групп с middleware (или там, где перехватчик переопределён по-своему через g.RouteNotFound(path, h)) всё работает по правилам десятого урока: 405, Allow, и обе ошибки едут в ваш ErrorHandler тем же общим потоком — конверт {error, code} применяется и к ним.

У каждого маршрута в Echo есть имя, и берётся оно автоматически: при регистрации e.add вычисляет handlerName(handler) — через runtime.FuncForPC это полное имя функции-обработчика вроде main.getTask. Отдельного метода «переименовать маршрут» в v4.15 нет: имя — это название вашей функции, и это честно фиксирует, что реверс работает по обработчикам, а не по строковым ярлыкам. Реверс выполняет e.URI(handler, params...) — «URI generates an URI from handler»: имя обработчика превращается в e.Reverse(name, params...), который ищет маршрут по имени в списке и подставляет параметры вместо :id-заглушек. e.URL — просто алиас того же метода.

При чём здесь группы при прямом отношении к путям: маршрут хранится УЖЕ с полным префиксом (вспомните g.prefix+path из g.Add), поэтому реверс вернёт /api/v1/tasks/42 без единой конкатенации с вашей стороны. Для версий это особенно ценно: e.URI(getTask, "42") внутри логики v2 вернёт адрес версии v2 — ссылки собираются из факта регистрации, а не склеиваются руками, и переезд обработчика между поддеревьями не ломает заголовки Location. Это базовое имя-неймспейс курса: достаточно, чтобы перестать строить URL строковой конкатенацией, а тонкости шаблонов путей вернутся в двенадцатом уроке вместе со статикой.

Идея «ветка пути с общими слоями» универсальна, но реализуется по-разному, и контраст полезнее копирования. В Echo группа — тонкий регистратор: собственного хранилища маршрутов у неё нет, каждый g.Add немедленно кладёт маршрут с полным путём и склеенными слоями в общий роутер, а сама Group остаётся копилкой префикса и слоёв. В fiber мы собирали те же деревья через app.Group и сталкивались с Router-интерфейсом третьей версии — урок fiber про группы маршрутов покажет этот контраст с другой стороны, повторять его факты здесь не буду. Gin разбирает RouterGroup с BasePath и отдельными NoRoute/NoMethod в своём уроке про группы маршрутов — а вот у Echo группового NoMethod нет вовсе: как вы только что видели, его место в группах с middleware занял приоритет 404-перехватчика из router.Find. Если читали тот урок gin — обратите внимание на это различие, оно самое заметное в тройке.

Слой организации маршрутов собран. e.Group — трёхстрочный конструктор над копилкой слоёв и префиксом; g.Add склеивает путь и свежий срез слоёв, applyMiddleware оборачивает их вокруг обработчика на каждый запрос; g.Use гарантирует исполнение слоёв catch-all-ом и меняет правила 404/405 внутри поддерева; вложенные группы строят дерево /api → /v1 → /v2 над одной базой обработчиков; реверс через e.URI возвращает полные адреса версий по имени функции. Канон на :1323 теперь выглядит как настоящий API: защищённое поддерево /api, две версии рядом, свой 404 на v1 и конверт ошибок из десятого урока поверх всего.

Двенадцатый урок уводит курс от JSON к HTML: статика и шаблоны — e.Static для файловых деревьев, Renderer и Template-интерфейс, html/template с автограничением. Группы и там пригодятся: /assets и страницы сайта удобно держать отдельными поддеревьями, а ErrorHandler из десятого урока уже умеет рисовать HTML-ветку по префиксу пути. Пока проверьте себя карточками, пересоберите fill и order и прогоните curl-матрицу канона. Навигация по курсу — на странице курса Echo; порядок цепочек и звенья — в уроке про middleware и цепочки; ErrorHandler и конверт {error, code} — в уроке про HTTPError; а bearerAuth и фабрики слоёв, которыми кормится весь канон, родились в восьмом уроке про кастомные middleware — загляните в него перед домашним заданием.