Группы маршрутов

Пока приложение маленькое, пути пишут руками: r.GET("/ping"), r.POST("/todos"). Как только эндпоинов становится больше десяти, начинается ерунда: префикс /api повторяется в каждом маршруте, переименовать его — значит пройтись поиском по всему проекту, а общий для половины путей middleware приходится дублировать аргументами. В gin группы маршрутов закрывают все три проблемы разом: r.Group("/api") возвращает значение типа *gin.RouterGroup, у которого есть те же методы GET, POST, PUT, DELETE и Use, что и у движка, — только пути внутри пишутся относительно префикса группы. Мы уже трогали тему дважды: во втором уроке мелькнула заготовка api := r.Group("/api/v1") с фигурными скобками — они, как тогда говорилось, чисто визуальный контейнер, Go их игнорирует; в седьмом уроке на группу вешали requireAPIKey. Важная деталь, которую легко упустить: Group ничего не регистрирует. Вызов r.Group("/api") не добавляет в дерево маршрутов ни одной записи — это лишь заготовка со склеенным basePath и пустым списком звеньев; пока вы не вызвали api.GET(...), группе неоткуда отвечать на запросы. Поэтому группы можно создавать впрок, пустая группа безвредна — она просто не участвует в обработке, — а комментарии к каждой ветке дерева пишут прямо рядом с объявлением. Фигурные скобки после Group — по желанию: они визуально ограничивают «зону» группы в файле, компилятору на них всё равно.

Откройте в исходниках файл routergroup.go: тип RouterGroup — это четыре поля. Handlers HandlersChain — список middleware, приклеенных к группе; basePath string — уже вычисленный префикс; engine Engine — указатель на движок, чтобы группа могла регистрировать маршруты в общем дереве; root bool — флаг «я корневая группа». На этом держится трюк, из-за которого у движка есть методы групп: структура Engine первым полем встраивает RouterGroup, и конструктор New() инициализирует это поле со basePath "/" и root: true. Поэтому r := gin.Default() — это gin.Engine, но r.GET и r.Group работают: методы встроенной группы поднимаются на поверхность. Создание вложенной группы — это создание новой структуры: сигнатура Group(relativePath string, handlers ...HandlerFunc) *RouterGroup, а Group() возвращает &RouterGroup{Handlers: group.combineHandlers(handlers), basePath: group.calculateAbsolutePath(relativePath), engine: group.engine} — механику склейки звеньев мы разобрали в седьмом уроке, здесь важен basePath: он вычисляется сразу, при создании, функцией joinPaths — это path.Join плюс сохранение хвостового слэша, если относительный путь кончался слэшем. path.Join чистит двойные слэши и точечные сегменты, поэтому "/api/" и "/v1" склеятся в аккуратное /api/v1. Итоговый префикс можно распечатать: метод BasePath() возвращает group.basePath — удобно для стартового лога «зарегистрированы маршруты: …» и для проверок в тестах. Сами группы — маленькие дешёвые структуры: смело заводите по одной на смысловую зону, никакой платы за лишний уровень вложенности нет.

Сила групп — в композиции. api := r.Group("/api") — корень; v1 := api.Group("/v1") — версия; admin := v1.Group("/admin", checkAPIKey("…")) — защищённая ветка. basePath каждого следующего уровня приклеивается к basePath родителя: /api, /api/v1, /api/v1/admin. Вложенные группы наследуют и звенья: маршруты admin несут всё, что объявлено на api, на v1 и в аргументах собственной Group, — общий срез склеивается в момент регистрации маршрута, поэтому порядок «звенья до маршрутов» важен, и мы проверим это предсказанием ниже. Практика больших проектов: дерево собирается в одной функции buildAPI, каждая версия — в своей функции-регистраторе, тогда границы версий видны одним взглядом, а git-история не перемешивает правки разных зон. Глубина вложенности ничем не ограничена — /api/v1/admin/reports/weekly это четыре законных уровня; но каждый уровень должен иметь право на собственный middleware или собственный смысл, иначе это просто лишний отступ. Типичная ошибка новичка — забыть про относительность: v1.GET("/api/v1/todos", …) внутри группы даст путь /api/v1/api/v1/todos. gin не ругается — двойной префикс регистрируется как обычный маршрут и молча ловит запросы. И последнее: префикс можно и «перепрыгнуть», потому что joinPaths исполняет path.Join, а тот понимает «..» — v1.Group("../admin") даст /api/admin. Работает, но читается ужасно: в продакшене так делать не стоит.

Как вешать звенья на группу, мы отработали в уроке про кастомные middleware: два способа — аргументы Group и вызовы g.Use, а порядок в цепочке задаёт combineHandlers, склеивающий срезы при регистрации маршрута. Здесь добавим только два следствия, которые в прошлый раз остались за кадром. Следствие первое: снимок звеньев делается в момент вызова api.GET — всё, что добавлено в группу после регистрации маршрута, на него не влияет; api.Use не пересчитывает существующие маршруты. Отсюда правило из предсказания выше: сначала Use, потом маршруты — и держите их в коде именно в таком порядке. Следствие второе: групповые звенья не действуют на 404. Запрос к несуществующему пути /api/v1/nowhere обслуживается цепочкой движка, в которой групповых звеньев нет вовсе — только глобальные и NoRoute-хендлер, о котором речь впереди. Поэтому глобальный Use из урока про встроенные middleware видит вообще всё, а групповой — только свои маршруты: requireAPIKey на группе admin не защищает «ничего» — несуществующий путь под /admin получит 404 мимо ключа, и это корректное поведение, а не дыра.

Версионирование путями — самый простой и самый gin-идиоматичный способ эволюции API: префиксы v1 и v2 живут в одном дереве маршрутов, одном процессе и одном порту, а группы делают разводку бесплатной. Сценарий: формат ответа Todo поменялся — добавилось поле priority и дата в RFC 3339 вместо строки. Клиентов на старом формате ломать нельзя: v1 замораживается — в неё летят только багфиксы, — а v2 получает собственные хендлеры с новой структурой ответа. Когда логика общая, а отличается только сериализация, выручает функция-регистратор с параметром *gin.RouterGroup: registerTodoRoutes(v1) и registerTodoRoutes(v2) ставят одни и те же хендлеры под оба префикса; когда расходится сам контракт, у версии свои хендлеры, но общий сервис-слой. Чего делать не стоит: ветвиться по версии внутри одного хендлера, выдирая v2 из пути через c.Param — контракт размазывается по коду, и через год никто не скажет, что вообще умеет v1. План вывода версии тоже прописывается маршрутизацией: логируйте трафик по префиксам (BasePath в помощь), отвечайте на v1 заголовком Sunset с датой отключения из звена версии, потом отключайте — дерево маршрутов честно покажет, кто ещё ходит на старую версию. В трекере мы разводим версии так: v1 — стабильная, v2 — с историей изменений задачи; общие хендлеры зарегистрированы обеим версиям, специфичный /todos/:id/history — только второй.

Дефолтные ответы движка на промах — тела «404 page not found» и «405 method not allowed» с Content-Type text/plain. Для JSON-API это брак: фронтенд ждёт конверт. Замена — два метода движка, и важно, что именно движка: func (engine Engine) NoRoute(handlers ...HandlerFunc) и func (engine Engine) NoMethod(handlers ...HandlerFunc) — у RouterGroup таких методов нет, r в r.NoRoute — это всегда корневой движок. Док-комментарий NoRoute честен: «It returns a 404 code by default» — хендлеры вы подставляете свои, статус остаётся 404. Первое правило: NoRoute заменяет предыдущий набор, а не дополняет — в исходниках присваивание engine.noRoute = handlers, поэтому звенья передавайте одним вызовом (r.NoRoute(jsonNotFound, extra)) или собирайте цепочку заранее; это отличие от Use, который дописывает. Второе: движок пересобирает итоговую цепочку промаха — allNoRoute = combineHandlers(noRoute) — при каждом вызове NoRoute и глобальном Use, поэтому глобальные звенья (Logger, Recovery, requestID) исполняются и на 404: строка [GIN] в логе появится и для промаха. Групповых звеньев там нет — см. прошлый блок. Третье: NoMethod бездействует, пока не включён флаг r.HandleMethodNotAllowed = true — мы упоминали его во втором уроке; без флага запрос с чужим методом валится в NoRoute как обычный 404. С флагом gin ищет путь в деревьях других методов: нашёл — отвечает 405 с заголовком Allow со списком допустимых (требование RFC 7231) и вашим хендлером; не нашёл ни в одном дереве — это уже не «не тот метод», а «нет пути», и правильный ответ — 404 через NoRoute. Дефолтные тела пишутся только если ваш хендлер не записал ничего: статус движок ставит заранее.

Названия вокруг групп — постоянный источник путаницы, разберём раз и навсегда. Тип в исходниках называется RouterGroup — файл routergroup.go; варианта RouteGroup в gin нет, это популярная описка из статей. По-русски говорят и «группы роутов gin», и «роутер-группы» — имеется в виду один и тот же gin.RouterGroup. Отдельного типа «роутер» не существует: gin.Router не скомпилируется. Роутер в разговорной речи — это gin.Engine, который, как мы выяснили, встраивает RouterGroup со basePath "/" и root: true. Компилятор следит за этим хозяйством через два интерфейса, объявленных в начале routergroup.go. IRoutes — «что умеет любой маршрутный узел»: Use, Handle, Any, GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, Match и статические помощники Static, StaticFS, StaticFile. IRouter — это IRoutes плюс Group: право создавать подгруппы есть только у того, что может быть родителем. Строки var _ IRouter = (RouterGroup)(nil) и var _ IRouter = (Engine)(nil) — проверки компиляции: и движок, и группа обязаны удовлетворять интерфейсу. Любопытен Any: он регистрирует путь сразу на девять методов — GET, POST, PUT, PATCH, HEAD, OPTIONS, DELETE, CONNECT, TRACE, — а Match берёт список методов срезом: rg.Match([]string{"GET", "POST"}, "/todos", h). Практический вывод для своего кода: функции-регистраторы принимайте как *gin.RouterGroup — тогда их можно звать и на v1, и на v2, а при необходимости и на корень.

Три бытовые мелочи, на которых спотыкаются. Первая: ведущий слэш в относительном пути можно не писать — joinPaths исполняет path.Join, и api.Group("v1") даст тот же /api/v1. Вторая: хвостовой слэш. RedirectTrailingSlash включён по умолчанию: если маршрут зарегистрирован как /api/v1/todos, а запрос пришёл на /api/v1/todos/, движок не даст 404, а ответит редиректом — 301 для GET, 307 для остальных методов, сохраняя метод. Удобно, но клиенты ведут себя с редиректами POST по-разному: некоторые библиотеки не follow 307 без явной настройки — лучше не полагаться и держать пути в одном виде. Третья: пути групп и маршрутов именно склеиваются — двойного слэша не будет никогда, path.Join съест и его; а вот «..» в относительном пути реально поднимает ветку выше, что мы уже отмечали как анти-паттерн. Статические файлы — соседняя тема, и её хелперы живут прямо здесь же, в интерфейсе IRoutes: Static, StaticFS, StaticFile, — но это материал урока 11-statika, там и продолжим. А пока зафиксируем скелет, который вы унесёте из урока: buildAPI собирает дерево /api → /v1 и /v2 → /admin с ключом-заглушкой; registerTodoRoutes переиспользует хендлеры между версиями; NoRoute и NoMethod отвечают конвертом; и ни одна строка бизнес-логики при переезде в группы не изменилась.