Свои middleware

В шестом уроке мы разобрали механику до последней строчки: Handler = func(Ctx) error, c.Next() и луковица, прерывание цепочки ошибкой, канонический порядок requestid → logger → recover. Встроенных пакетов хватает для наблюдения и защиты, но третий класс задач они не закрывают — бизнес-логика доступа к вашим данным. Логгер не знает, что ключ «s3cret» открывает заметки, а таймер не понимает, кому отдавать вычисленный пользователь. Это остаётся вам, и хорошая новость в том, что нового синтаксиса нет: свой middleware — это обычная функция или фабрика, возвращающая fiber.Handler.

Разберём три классические задачи, которые встречаются почти в каждом сервисе. Первая — аутентификация-заглушка: слой проверяет заголовок X-API-Key и не пускает чужих дальше, отвечая 401 с JSON-ошибкой. Вторая — таймер: замерить, сколько запрос провёл внутри цепочки, не потеряв ошибку. Третья — контекст запроса: передать вычисленное аутентификацией значение в хендлер через c.Locals. Сквозной пример курса — API заметок — продолжается: к концу урока всё API уедет под группу /api со стражем на входе. Все факты сверены с исходниками тега v3.5.0: app.go, router.go, req.go и каталог middleware.

Зачем вообще вторая форма? Слою часто нужен конфиг: ожидаемый ключ, имя заголовка, порог срабатывания, адрес получателя лога. Обычная функция может взять это только из глобальных переменных — и вот у вас уже два сервиса дерутся за одну переменную. Фабрика решает проблему чисто: requireAPIKey("s3cret") и requireAPIKey("other") вернут два независимых слоя, каждый со своим ключом внутри замыкания. Конфиг живёт ровно столько, сколько нужен, не торчит в пакете и не тянется через параметры каждого вызова.

Второй аргумент за фабрику — единообразие со штатными пакетами. Вы уже видели этот рисунок в шестом уроке: logger.New(logger.Config{...}) принимает конфиг и возвращает fiber.Handler, то же делает recover.New(), requestid.New() и любое стороннее middleware Fiber. Промышленная версия чуть развитее: конфиг оформляется структурой Config с полем ConfigDefault и вариадиком New(config ...Config), поэтому незаполненные поля добираются из дефолта. Мы приходим к тому же интерфейсу, только с простым аргументом-строкой. Последнее правило гигиены: фабрику зовут один раз при регистрации, а не в хендлере на каждый запрос. Слой, созданный в хендлере, работает, но бессмысленно тратит память на замыкания и прячет конфигурацию там, где её не найти при чтении кода приложения.

В шестом уроке прерывание делалось через fiber.NewError(fiber.StatusUnauthorized, ...): ошибка улетала в ErrorHandler приложения, и DefaultErrorHandler отвечал телом text/plain; charset=utf-8. Здесь мы выбрали другой путь — слой сам записал ответ через c.Status(...).JSON(...) и вернул результат как ошибку (а c.JSON возвращает error, которым обычно является nil). Для клиента разница материальная: JSON-тело удобно парсить фронтенду, text/plain — нет. Способов получить JSON-ошибку ровно два: писать ответ в самом middleware, как сейчас, или заменить ErrorHandler приложения — fiber.New(fiber.Config{ErrorHandler: ...}) — тогда и fiber.NewError начнёт отвечать JSON-ом по всему приложению. Первый способ дешевле для одного слоя, второй даёт единый формат ошибок сразу везде; к ErrorHandler мы вернёмся в уроке про обработку ошибок.

Раз строим аутентификацию, честно скажем: в комплекте Fiber есть и готовый fiber auth middleware — пакет github.com/gofiber/fiber/v3/middleware/keyauth. Его конфиг — зеркальное отражение того, что мы построили руками. Extractor достаёт ключ из запроса (дефолт — extractors.FromAuthHeader("Bearer"), для нашего случая подошёл бы extractors.FromHeader("X-API-Key")); Validator сверяет извлечённый ключ; SuccessHandler пускает дальше — дефолтно это return c.Next(); ErrorHandler отвечает при провале — дефолтно 401 и текст «missing or invalid API Key». Наша заглушка — не кустарщина, а упрощённая копия промышленного шаблона, и после этого урока чтение исходников keyauth не вызовет вопросов.

Самая частая ошибка при написании таймера — записать return c.Next() одной строкой и поставить печать «после»: return покидает функцию немедленно, и до Printf выполнение не доходит никогда, замер молча исчезает. Правильный рисунок — три шага: err := c.Next(), замер, return err. Вторая граблина — return nil после замера при непустой ошибке: если внутренние слои вернули ошибку, а таймер её отбросил, ErrorHandler никогда её не увидит, клиент получит пустой 200 (ответ ведь никто не записал), а вышестоящий логгер не покажет ${error}. Ошибка в луковице всплывает наверх через каждый слой: ваш слой обязан либо обработать её и записать ответ, либо передать как есть. «Перехватил и забыл» — не приём, а бага.

Третье наблюдение тоньше: печать стоит после c.Next(), а не после проверки err != nil, поэтому длительность видна и для ошибочных ответов — в том числе для 401 из прошлого раздела. Слой-таймер честно меряет всё, что происходило внутри, независимо от исхода. Если хотите отдавать замер клиенту, добавьте c.Set("X-Response-Time", time.Since(start).String()) до return err — заголовок уедет с ответом; полный вариант с конфигурируемым именем заголовка — это responsetime.New() из комплекта, о котором сказано выше. И последнее: замер продолжит работать и на паникующих запросах, но только если recover-слой стоит ВНУТРИ таймера — об этом месте в порядке регистрации отдельно поговорим при сборке каркаса.

Слои часто обязаны передавать друг другу данные: аутентификация вычислила пользователя — хендлеру нужен логин; таймер посчитал длительность — логгеру пригодилось бы число. Заводить под это глобальную карту — гонки и утечки между запросами. В Fiber для этого служит c.Locals. Сигнатура из v3: func (c fiber.Ctx) Locals(key any, value ...any) any — метод-двуликость: один аргумент означает чтение, два — запись. Докомментарий к интерфейсу формулирует назначение: makes it possible to pass any values under keys scoped to the request — значения живут ровно один запрос; документация добавляет, что они удаляются после завершения запроса, а под капотом стоят UserValue и SetUserValue fasthttp.

Чтение возвращает any — без магии: доставайте type assertion в ok-форме: user, ok := c.Locals("user").(string). Если ключа нет, вернётся nil, ok будет false, а user — пустая строка; прямое приведение c.Locals("user").(string) без ok на отсутствующем ключе паникует. Для типизированных чтений есть дженерик-версия fiber.Locals[string](c, "user") — она вернёт zero value типа, если ключа нет или тип не совпал. Ключом может быть любое значение; документация советует заводить непроэкспортируемый тип для ключа, чтобы разные пакеты не столкнулись строками. Ещё две детали из исходников: значение, реализующее io.Closer, Fiber закроет при удалении; а StoreInContext(c, key, value) пишет и в locals, и в context.Context — правда, второе только при включённом конфиге PassLocalsToContext (по умолчанию false).

Вешать стража на каждый маршрут по отдельности — работа для робота, и она же порождает главный источник дыр: один новый маршрут забыли прикрыть. app.Group собирает маршруты с общим префиксом и вешает на них middleware одним движением. Сигнатура из app.go: func (app *App) Group(prefix string, handlers ...any) Router, а докомментарий звучит так: Group is used for Routes with common prefix to define a new sub-router with optional middleware. Возвращается Router — под-роутер с привычным набором методов: api.Get, api.Post, вложенные api.Group("/v1"). Слои из Group получают все маршруты, зарегистрированные на группе и на вложенных группах, — и только они: статика из урока 5 и корневые пути вроде health-check остаются без аутентификации, что обычно и требуется.

Две грабли из исходников. Первая: handlers — вариадик any, и незнакомый тип паникует в collectHandlers с контекстом «group»: сообщение вида group: invalid handler #0 (...тип...) — родственник «use: invalid handler» из шестого урока. Вторая — порядок регистрации: Group регистрирует свои слои в момент вызова, поэтому маршруты, объявленные РАНЬШЕ вызова app.Group, слоёв не получают. Это та же стековая механика, что у Use: слой, записанный в стек позже живого маршрута, не оборачивает его. Привычка, которая спасает: сначала все Use и Group, потом маршруты групп, Listen — последней строкой.

Соберите main.go из каркаса выше в один файл — timer и requireAPIKey лежат рядом с main, импорты уже перечислены — и прогоните сценарий curl-ом. Первый запрос: curl -H "X-API-Key: s3cret" /api/notes — в ответе JSON со списком, в консоли строка таймера с длительностью, в логе статус 200. Второй: тот же путь без заголовка — клиент получает 401 и {"error":"неверный API-ключ"}, лог пишет 401 при пустом ${error}: страж записал ответ сам и вернул nil. Третий: curl -i /healthz — 200 без всякого ключа, маршрут вне группы; заодно в заголовках видно X-Request-ID из шестого урока. Четвёртый, для любопытных: добавьте в таймер c.Set("X-Response-Time", time.Since(start).String()) и найдите этот заголовок в curl -i — у вас получился мини-клон responsetime.

Дальше по плану — восьмой урок: CORS и безопасность заголовков, как разрешить браузеру чужого origin дёргать ваше API и какие заголовки за это отвечают; таймер и страж из этого урока будут помогать его разбору. Освежить механику c.Next(), луковицы и ErrorHandler — в шестом уроке, параметры запроса — в четвёртом, полный план — на странице курса Fiber. В браузерной песочнице сайта сетевые приложения не запускаются — runner-ов в уроках Fiber нет, проверяйте примеры в терминале с локальным Go.