Кастомные middleware в Echo: фабрика, Bearer-аутентификация и метрики

Каталог встроенных слоёв закрывает то, что одинаково у всех проектов: логи, recovery, сжатие, идентификатор запроса. Собственный слой нужен там, где логика привязана к вашему домену: проверка токена по таблице сессий в базе, лимиты на пользователя из вашего хранилища, счётчики с бизнес-размерностью вроде «запросов на тенианта», сквозные правила API. Три надёжных признака того, что код пора оформить звеном. Первый: один и тот же фрагмент повторяется в трёх и более обработчиках — и уже начал расходиться между копиями. Второй: правило должно исполняться ДО обработчика — отказ на границе дешевле, чем отказ посреди транзакции. Третий: данные, посчитанные один раз на запрос, нужны нескольким звеньям сразу — классический пример это пользователь, выясненный аутентификацией.

Свой echo кастомный middleware проходит ту же анатомию, что loggerTimer из урока про цепочки: внешняя функция принимает следующий обработчик и возвращает замыкание, замыкание исполняется на каждый запрос, вызов следующего звена — next(c). Напомним одной строкой и миф из того же урока: метода c.Next() в Echo не существует — это API Gin и Fiber, и в рецептах про echo он всегда признак скопированного кода. План урока такой: сначала фабрика с конфигом — почему без неё не обойтись и где в ней жить состоянию; затем Bearer-аутентификация с отказом 401, передача пользователя через c.Set/c.Get, сквозная валидация, снятая с домашнего задания, и скипер по стандартам каталога.

Голую функцию func(next echo.HandlerFunc) echo.HandlerFunc вы уже писали: loggerTimer в уроке про цепочки был именно ей. Для звена с настройками и состоянием оформляйте фабрику — функцию, которая принимает конфиг и возвращает echo.MiddlewareFunc, ровно как штатные фабрики каталога: Logger() и LoggerWithConfig(config) из урока про встроенные слои. Структура повторяет XConfig-паттерн: своя структура конфига, резолв дефолтов, возврат слоя.

Смотрите внимательно: у фабрики три ступени, и живут они по-разному. Первая ступень — тело самой фабрики: она исполняется один раз, в момент e.Use(metricsTimer(...)), потому что вызываете её вы сами. Здесь резолвятся дефолты, проверяется конфиг и объявляется состояние. Вторая ступень — возвращённый слой func(next echo.HandlerFunc) echo.HandlerFunc: его на каждый запрос вызывает applyMiddleware из echo.go, оборачивая найденный обработчик, — там нельзя заводить переменные, которыми хочет жить слой между запросами. Третья ступень — замыкание func(c echo.Context) error: само звено, тело которого исполняется один раз на запрос. Это важный контраст с Gin, где цепочка склеивается в момент регистрации маршрута: в Echo обёртка строится на каждый запрос — цена копеечная, пара замыканий, но правило размещения состояния другое. Свежая деталь из исходников v4: часть фабрик каталога на невалидном конфиге паникует прямо на старте — KeyAuth без Validator падает с текстом echo: key-auth middleware requires a validator function. Берите приём на вооружение: ошибка конфигурации должна стрелять при подключении, а не на первом запросе.

Метрики живут по обе стороны next(c), и у каждой стороны свои возможности. До next(c) доступна фаза запроса: метод, путь, заголовки — можно поставить метку start := time.Now(). После next(c) наступает фаза ответа: время считается time.Since(start), ошибка внутренних слоёв лежит в err, а c.Response().Status содержит статус ответа — но только если ответ к этому моменту оформлен. Вот тонкость, на которой ломаются самодельные метрики. Когда нижнее звено, например аутентификация, возвращает echo.NewHTTPError и не вызывает next(c), ответа ещё нет: файл response.go при сбросе контекста ставит Status в http.StatusOK, и до оформления ответа там будет дефолтный 200. Оформлением занимается глобальный HTTPErrorHandler — строка if err := h(c); err != nil { e.HTTPErrorHandler(err, c) } из ServeHTTP, — но она срабатывает ПОСЛЕ выхода из вашего слоя. Поэтому loggerTimer из урока про цепочки и штатный Logger зовут c.Error(err) до печати: этот вызов тут же проводит ошибку через обработчик, ответ фиксируется, и статус в c.Response().Status становится настоящим — 401, 400, 500. Пропустите c.Error — и метрика молча запишет отказ аутентификации как двухсотый ответ.

Запрос «echo auth middleware» в поиске — это почти всегда Bearer-схема: заголовок Authorization вида Bearer <token>, стандарт RFC 6750, так ходят токены OAuth 2.0 и JWT. Соберём заглушку своими руками — а заменой настоящей проверке она станет после того, как сравнение токена подменится походом в базу сессий. Механика фазы запроса: достать заголовок через c.Request().Header.Get(echo.HeaderAuthorization) — Echo не нужна своя обёртка, заголовок живёт в обычном *http.Request; проверить префикс strings.HasPrefix(auth, "Bearer ") и срезать его strings.TrimPrefix-ом; сравнить токен с ожидаемым. Отказ — return echo.NewHTTPError(http.StatusUnauthorized, ...): ошибка без вызова next(c), клиент получает 401 с телом {"message":...} от глобального обработчика. Подробная анатомия HTTPError — Message как interface{}, поле Internal, собственный ErrorHandler с единым форматом — тема десятого урока, там и продолжим. Две честные оговорки наперёд. Первая: RFC 6750 советует при отказе ставить заголовок WWW-Authenticate: Bearer — штатный KeyAuth этого не делает, а ваша фабрика может, это одна строка перед return. Вторая: у каталога есть готовый middleware.KeyAuth с AuthScheme "Bearer" по умолчанию — своё звено оправдано, когда проверка ходит в вашу базу или кладёт в контекст больше одного значения.

Пользователь выяснен — как о нём узнают звенья ниже? Канал тот же, что в уроке про цепочки: c.Set(key, val) и c.Get(key) any поверх ленивой карты Map в контексте запроса, создание при первом c.Set. Там же разобрана и ok-форма чтения — v, ok := c.Get(key).(string), — повторять её не будем, но закрепим дисциплину, которая в файле с тремя и более звеньями становится обязательной. Ключи — только константы: const ctxUserKey = "auth.user" объявлен рядом с bearerAuth, и опечатка теперь ловится компилятором, а не молчаливой пустой строкой в обработчике. Префикс auth. — не магия, а способ видеть в автодополнении все ключи одного звена; validateCreate ниже добавит свой ctxTodoInputKey.

Два нюанса из актуальных исходников v4.15, которых не было в прошлом разговоре. Первый: доступ к store обёрнут в sync.RWMutex — c.Set берёт блокировку на запись, c.Get на чтение, так что чтение пользователя из параллельных запросов безопасно само по себе. Второй: store — поле контекста, а контексты Echo переиспользует через пул; Reset обнуляет store в nil, поэтому данные живут ровно один запрос и не перетекают в следующий. Читают положенное три потребителя: обработчик, сквозная валидация ниже по цепочке и — если вы помните урок про встроенные слои — CustomTagFunc штатного Logger, умеющая докинуть имя пользователя в строку лога.

В домашнем задании урока про цепочки был каркас: middleware, который прогоняет структуру через c.Validate и на ошибку возвращает 400, не доходя до обработчика. Развернём его в законченный сквозной конвейер привязки и проверки — тот самый bind → normalize → validate, который собирался в уроке про привязку и валидацию, переезжает из каждого обработчика в одно звено. Идея: звено привязывает тело запроса в TodoInput, нормализует и проверяет, кладёт готовую структуру в контекст и лишь потом зовёт next(c); обработчик достаёт результат через c.Get и занимается единственным своим делом — хранилищем и ответом. Три обработчика создания сущностей — и три копии конвейера превращаются в один e.POST(path, handler, validateCreate).

У дизайна есть цена, и о ней честно. Звено, которое делает c.Bind, обязано знать структуру — значит, оно прикрепляется к конкретным маршрутам (route-level, самый близкий к обработчику уровень из таблицы урока 06), а не вешается глобально. Маршрут перестаёт нести знание о теле запроса — это плюс к единообразию и минус к локальности: читая main, вы видите validateCreate в списке middleware, а не в теле обработчика. И помните правило урока 04: c.Bind читает тело для POST/PUT/PATCH, а для GET/DELETE — query; сквозное звено валидации создания живёт только на создающих маршрутах, оставляя query-разбор обработчикам чтения.

У каждого штатного конфига из урока про встроенные слои первое поле — Skipper: func(c echo.Context) bool, true — слой молча делает return next(c). Дефолт DefaultSkipper всегда возвращает false. Ваше звено обязано уметь то же самое: слой, который нельзя выключить, быстро начинают обходить стороной — health-чеки не должны требовать токен, метрики не должны попадать в свои же счётчики, публичные маршруты не должны знать про аутентификацию.

Интеграция в три действия. Первое: поле Skipper middleware.Skipper в своей структуре конфига — тип переиспользуем из пакета middleware, свой не заводим. Второе: резолв nil-а в теле фабрики — если скипер не задан, ставим middleware.DefaultSkipper; это та же ступень «один раз при подключении», что и для дефолтов конфига. Третье: первая строка замыкания — if cfg.Skipper(c) { return next(c) }: проверка дешёвая, выполняется на каждый запрос, и при true звено исчезает из цепочки, не потратив ни одной операции на разбор заголовков. Для сравнения путей берите c.Path() — шаблон маршрута вида /api/public/*, тот же, что у тега ${route} в штатном Logger, — либо c.Request().URL.Path с реальным путём запроса; разница проявляется на path-параметрах, где шаблон стабильнее.

Мы собрали три своих звена и ни разу не вышли за пределы модели «до next(c) — после»: фабрика с конфигом и состоянием на первой ступени, Bearer-аутентификация с отказом 401 и кладкой в контекст, сквозная валидация, снявшая конвейер с обработчиков. Порядок сборки из order-задания — репетиция реального main: сначала то, что видит всё, потом то, что отклоняет, потом то, что готовит данные. Единственный шаг от заглушек к бою — подмена сравнения токена походом в базу и fmt.Printf на настоящий логгер: куда именно вести строки метрик и как переходить на структурные логи со slog — тема следующего, девятого урока про логирование.

Вторая линия на вырост — ошибки. Все отказы урока построены на echo.NewHTTPError, но у HTTPError есть поле Internal для исходной причины, Message принимает не только строки, а собственный ErrorHandler собирает единый формат для всего API — разбор ошибок целиком занимает десятый урок. Пока же проверьте себя карточками, пройдите fill и order ещё раз с закрытыми глазами и перенесите звенья в свой учебный сервер из прошлых уроков: метрики, аутентификация и валидация собираются в один файл без единой правки обработчиков. Навигация по курсу — на странице курса Echo, анатомия цепочки — в уроке про middleware и цепочки, каталог штатных слоёв — в уроке про встроенные middleware.