Middleware: встроенные

Отдельного типа «middleware» в Gin нет: любой разбор gin middleware начинается с HandlerFunc — func(gin.Context), того же типа, что и у обычного хендлера. Роль определяет позиция: звено стоит раньше финального обработчика и обычно зовёт c.Next(), чтобы пропустить ход дальше. Цепочка вызовов собирается при регистрации маршрута: r.GET("/todos", authGate, listTodos) — первый аргумент после пути, а дальше variadic, звеньев может быть сколько угодно. Глобальные звенья через r.Use(...) приклеиваются впереди: combineHandlers копирует накопленные звенья группы и звенья маршрута в один срез, и на каждый запрос этот срез исполняется слева направо по индексу внутри Context. У Use есть любопытное свойство: он глобален для движка — звено попадает и в 404, и в 405, и в отдачу статики, поэтому документация прямо называет Use правильным местом для Logger и Recovery. Любая ваша функция с сигнатурой func(gin.Context) может встать в цепочку: middleware — не магия, а обычный код с удачной позицией.

Механика в исходниках на удивление скромная: Next() увеличивает внутренний индекс и в цикле вызывает оставшиеся звенья среза до конца. Вся «магия порядка» — следствие одного цикла. Код до c.Next() выполняется на входе, до всех последующих звеньев; код после — на выходе, когда хендлер уже отработал и, возможно, что-то написал в ответ. Отсюда форма луковицы: звенья входят по очереди, а выходят в обратном порядке — и gin.Logger именно так замеряет латентность: старт таймера до c.Next(), снятие показаний после. Тот же эффект достижим через defer: отложенная функция сработает на выходе звена даже при панике ниже по цепочке — Recovery построен ровно на defer и recover. Есть тонкость, о которой редко пишут: если middleware не вызовет c.Next() вовсе, цепочка не оборвётся — gin вызовет оставшиеся звенья после возврата из вашего. Но «выход» вы потеряете: код после c.Next() — единственное место, откуда видно, что хендлер уже завершился, поэтому замеры и итоговые логи живут именно там.

Abort() — единственный способ остановить цепочку вызовов: он присваивает внутреннему индексу константу abortIndex (63), и ни один последующий вызов уже не находит звеньев. Документация подчёркивает неудобную деталь: Abort не останавливает текущее звено — строки после него в той же функции продолжат исполняться, поэтому после Abort почти всегда нужен return. Проверить состояние можно c.IsAborted(). Вокруг Abort собрано семейство помощников: AbortWithStatus пишет статус с заголовками, AbortWithStatusJSON — это Abort плюс c.JSON из прошлого урока, AbortWithError ещё и кладёт ошибку в c.Errors, откуда её потом подхватит Logger. У цепочки есть технический предел: суммарное число звеньев обязано быть меньше 63, иначе combineHandlers паникует с сообщением too many handlers — страховка от случайно зацикленного Use. И обратная ловушка: если в authGate просто вернуть return без Abort, цепочка продолжится — listTodos выполнится без авторизации, ведь gin вызовет его сразу после выхода из вашего звена. Отказ — это всегда Abort плюс return, а не только return.

Под капотом — карта Keys с мьютексом: Set лениво создаёт её и записывает пару ключ-значение, Get возвращает (value, exists). Ключ и значение имеют тип any: Gin не заставляет регистрировать типы, но и не проверяет их — вытащенное значение приводится через type assertion, и форма v, ok := c.Get(...) безопаснее голой. Для уверенных мест есть MustGet, паникующий на отсутствующем ключе, и типизированные помощники GetString, GetBool и другие — они тихо вернут нулевое значение, если ключа нет. Время жизни — ровно один запрос: Keys обнуляется при переиспользовании Context из пула, поэтому контекст — не кеш сессий и не хранилище конфига. Для передачи контекста в горутину берите c.Copy(): копия защищена от дальнейших изменений и уже «прервана» — из неё нельзя запустить цепочку. Соглашения о наборе ключей, кто пишет и кто читает, — тема урока 07-kastomnye-middleware; здесь важен сам механизм.

В исходниках gin.Default() — две строки: gin.New(), затем engine.Use(Logger(), Recovery()). Встроенных middleware в ядре ровно два: если где-то видели RequestID, CORS или gzip «из коробки», это gin-contrib и сторонние пакеты, а не gin.New. Чистый движок New не содержит ни одного звена, но при этом у него уже выставлены настройки по умолчанию — редиректы trailing slash, доверие к X-Forwarded-For, буфер для multipart. Default при старте печатает предупреждение [GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached — то самое, что мелькало в логах ещё на первом сервере. Порядок аргументов Use(Logger(), Recovery()) не случайность: Logger ставится первым, Recovery вторым, и к концу урока станет ясно, что поменять их местами — значит потерять логи паник.

Строка вида [GIN] 2025/06/01 - 15:04:05 | 200 | 341µs | 127.0.0.1 | GET "/todos" печатается звеном gin.Logger — это и есть тот самый gin logger, который виден в каждом туториале. Работает он через луковицу: запоминает time.Now() до c.Next(), а после собирает структуру LogFormatterParams и печатает её в gin.DefaultWriter — по умолчанию os.Stdout. StatusCode берётся из c.Writer.Status() — то есть уже финальный, каким его сделал любой ответ, включая AbortWithStatusJSON; Latency — разница таймеров; ClientIP — c.ClientIP() с учётом доверенных прокси; ErrorMessage — строка из c.Errors приватного типа; BodySize — сколько байт ушло клиенту. Если в URL была query-строка, она дописывается к пути — и токен из ?token= оседает в логах. Латентность перед печатью аккуратно обрезается: больше минуты — до десятков секунд, больше секунды — до десятков миллисекунд, больше миллисекунды — до десятков микросекунд. Цвета: 2xx зелёным, 4xx жёлтым, 5xx красным; GET синим, POST бирюзовым, DELETE красным — но только в терминале: при выводе в файл проверка isatty выключает ANSI-коды, и лог остаётся плоским текстом.

Документация Recovery звучит буднично: middleware, который восстанавливается после любых паник и пишет 500, если паника была. Устройство — ровно то, что мы разобрали на луковице: звено регистрирует defer с recover() и лишь затем зовёт c.Next(). Паника в любом более глубоком звене раскручивает стек ровно до этого defer. Дальше два пути. Обычный: в DefaultErrorWriter (по умолчанию os.Stderr) уходит строка [Recovery] <время> panic recovered: с дампом запроса, значением паники и стеком, где видны файл, строка и даже исходный код; после этого Recovery вызывает defaultHandleRecovery — ошибка через c.Error оседает в c.Errors, а клиент получает AbortWithStatus(http.StatusInternalServerError): только статус, тело пустое. Отдельная ветка — обрыв соединения (EPIPE, ECONNRESET): писать 500 в мёртвый сокет бессмысленно, Recovery лишь кладёт ошибку в c.Errors и делает Abort. Дамп запроса при этом аккуратен: заголовок Authorization маскируется звёздочкой, чтобы токен не уехал в логи.

combineHandlers склеивает цепочку в момент регистрации маршрута: всё, что добавлено через Use до r.GET, войдёт в его срез звеньев; middleware, объявленное после, маршрут не увидит. Правило простое — сначала Use, потом маршруты; для групп то же самое: g.Use(...) до g.GET(...). Внутри цепочки порядок не декорация. Default ставит Logger перед Recovery не случайно: паникует хендлер — Recovery, звено ниже, ловит её defer'ом, ставит 500 — и когда исполнение возвращается в Logger, тот логирует уже финальный статус и сообщение ошибки из c.Errors. Переверните порядок: Recovery окажется выше, Logger ниже, паника пролетит сквозь кадр Logger'а, не дав выполниться коду после c.Next(), — строка лога на этот запрос не появится вовсе. Запрос восстановит всё тот же Recovery, но след в журнале потерян. Держите Logger первым: он обязан видеть всё, включая 500.