Middleware и цепочки в Echo: e.Use, next(c), порядок и прерывание

В конце прошлого урока в каждом обработчике появилась одна и та же церемония: c.Bind, нормализация, c.Validate. А теперь представьте, что к этому добавилось логирование каждого запроса, замер времени ответа и проверка авторизации. Три if-а и два лога в каждом из двадцати обработчиков — и вот уже половина кода API это копипаста, которая расходится между обработчиками по мере правок.

Механизм echo middleware решает это структурно: слой — функция, которая принимает следующий обработчик цепочки и возвращает новый. Вы пишете логику один раз и подключаете её к маршруту, группе или всему серверу — а Echo сама проводит каждый запрос через все слои по очереди. Такая конструкция называется цепочка middleware: запрос проходит через слои снаружи внутрь, обработчик формирует ответ, и ответ идёт обратно через те же слои. Роутинг мы собирали в уроке про маршрутизацию, конвейер bind-validate — в уроке про привязку и валидацию; middleware — это третий слой архитектуры Echo, который оборачивает их все.

В echo.go всё описано двумя строчками. type HandlerFunc func(c Context) error — так выглядят обработчики, к которым вы привыкли. А type MiddlewareFunc func(next HandlerFunc) HandlerFunc — middleware принимает следующий обработчик и возвращает новый. Смотрите, что здесь спрятано: в Echo следующий слой приходит вам аргументом next, и вы вызываете его как обычную функцию — next(c). Никакого метода c.Next() в Echo нет — ни в четвёртой версии, ни в пятой. c.Next() — это API Gin и Fiber, и его же пишут в старых постах про Echo по памяти о других фреймворках. Если такое встретите в рецепте про echo — рецепт либо устарел, либо скопирован из чужого фреймворка.

Второе, что стоит разглядеть в сигнатуре: MiddlewareFunc — это просто тип функции, и его удобно возвращать из фабрики. middleware.Logger() возвращает echo.MiddlewareFunc: сначала конфигурация, потом готовый слой. Ваши middleware будут строиться так же — либо голой функцией вида func(next echo.HandlerFunc) echo.HandlerFunc, либо фабрикой с настройками, которая возвращает такой же тип. Для совместимости с net/http-стеками в echo.go есть WrapMiddleware — он оборачивает классическую func(http.Handler) http.Handler в echo.MiddlewareFunc, но это уже мост в мир стандартной библиотеки, а не наш главный путь.

e.Use добавляет middleware в общий стек сервера. Сам метод тривиален: e.middleware = append(e.middleware, middleware...) — всё, что вы передали (а это variadic, можно перечислить несколько через запятую), дописывается в конец среза. Но интересное — в том, как Echo из этого среза собирает цепочку. Внутри ServeHTTP сработает applyMiddleware: цикл идёт с конца среза к началу, и каждый элемент оборачивает текущий обработчик. Результат: последний добавленный слой оказывается ближайшим к обработчику, а самый первый добавленный — самым внешним.

Поэтому порядок вызовов e.Use — это не декорация, а архитектурное решение. e.Use(loggerTimer), затем e.Use(authStub) означает: логгер видит запрос первым и провожает его последним, аутентификация — второй и её строка «после» сработает раньше логгеровой. Если поменять вызовы местами — изменится всё: кто первый поставил метку времени, кто последним видит статус ответа, кто обрабатывает ошибки соседей. Док-комментарий к e.Use в echo.go лаконичен: adds middleware to the chain which is run after router — после маршрутизатора. Это не про порядок соседей, а про то, что маршрутизация уже случилась, когда слои начинают работать. Про то, что бывает до маршрутизатора, — отдельная история ниже.

Картину из predict-а называют луковицей: запрос проходит сквозь слои снаружи внутрь, обработчик сидит в центре, ответ выходит обратно сквозь те же слои. У каждого middleware поэтому две половины жизни. Код до next(c) работает в фазе запроса: здесь можно померить start, проверить аутентификацию, дополнить запрос данными, отклонить его совсем. Код после next(c) работает в фазе ответа: здесь есть итоговый статус, время обработки, и здесь можно дописать заголовки — при условии, что ответ ещё не отправлен клиенту.

Именно на этой модели стоят почти все штатные middleware Echo: таймер и статус у Logger-а живут по обе стороны next(c), у Recover-а — отложенный recover(), который ловит панику из внутренних слоёв, пока кадры unwind-ятся назад через цепочку. Отсюда же практическое правило: тот, кто должен видеть всё, добавляется первым. Логгер, добавленный последним, увидит только то, что не съели соседние слои. А тот, кто отклоняет запросы, ставится после логгера — тогда каждый отказ тоже попадёт в лог. Порядок в e.Use читайте как маршрут запроса снаружи внутрь.

Аутентификация выяснила, кто стучится, — как об этом узнает обработчик? Для таких передач между звеньями у echo.Context есть пара c.Set(key string, val any) и c.Get(key string) any. Внутри — карта Map (в echo.go это type Map map[string]interface{}), которая создаётся лениво при первом c.Set и лежит прямо в контексте запроса. Больше того, Echo хранит контексты в пуле и переиспользует их между запросами — c.Reset чистит хранилище, поэтому данные, положенные в c.Set, живут ровно один запрос и никогда не перетекут в соседний.

Важно читать контракт типов: c.Get возвращает any, а не строку. Доставать значение надо type assertion-ом, лучше ok-формой: name, ok := c.Get("username").(string). Без неё assert на неожиданном типе роняет программу паникой. Ключи — строки, и на реальном проекте их держат в константах (ctxUsername = "username"), чтобы опечатка в двух местах не превратилась в баг, который молча отдаст пустую строку. Примеры из самих исходников Echo: CSRF-middleware кладёт токен через c.Set("csrf", token), а роутер при 405 через c.Get достаёт заголовок Allow. Это штатный способ нести данные между звеньями, а не хак.

e.Use-слои начинают работу после того, как роутер нашёл маршрут: в ServeHTTP сначала вызывается Find по дереву маршрутов, и только потом обработчик оборачивается стеком e.middleware. Значит, повлиять на сам выбор маршрута из них уже нельзя. Для этого есть e.Pre — premiddleware. Тот же тип MiddlewareFunc, та же луковица, но вставлена она раньше: premiddleware обёртывает не найденный обработчик, а замыкание, внутри которого происходит маршрутизация. Док-комментарий: adds middleware to the chain which is run before router.

Практическое применение у Pre узкое и честное: всё, что должно случиться до выбора маршрута. Штатные примеры — middleware.Rewrite, AddTrailingSlash и RemoveTrailingSlash: они правят r.URL.Path до того, как роутер сверится с таблицей, поэтому /admin/users/ и /admin/users попадают на один маршрут вместо 404 у одного из них. Всё остальное — логи, таймеры, аутентификация — живёт в e.Use: там уже известно, какой маршрут выбран, есть c.Path() и есть доступ к данным маршрута. Забавное следствие устройства: при несуществующем пути premiddleware и e.Use-слои всё равно исполнятся — 404 в Echo это тоже обработчик, просто штатный, а не ваш.

Пока каждый слой зовёт next(c), запрос движется вглубь. Но middleware имеет полное право этого не делать — и это главный рычаг контроля в echo middleware. Прерывание выглядит как обычный return. Вариант первый: return err — вернуть ошибку, не дойдя до обработчика. Ошибка начинает раскручивать цепочку обратно: каждый внешний слой получает её как результат next(c), может что-то сделать (залогировать, обернуть) и возвращает дальше. В самом конце ServeHTTP видит err != nil и зовёт глобальный HTTPErrorHandler: для *echo.HTTPError клиент получит её код и message в JSON, для любой другой ошибки — 500 Internal Server Error.

Вариант второй: написать ответ самому и вернуть nil. c.JSON(http.StatusUnauthorized, ...) прямо в middleware, return nil — клиент получит ровно ваш ответ, глобальный обработчик не вызовется, потому что ошибка не родилась. Оба варианта легальны, но первый лучше сочетается с остальной системой: HTTPError несёт статус и сообщение, обработчик оформит ответ единообразно, а логгер снаружи увидит ошибку в возвращаемом значении. Общее у обоих вариантов одно: звенья ниже не исполняются. Обработчик даже не узнает, что к нему кто-то стучался.

Луковица делает некоторые порядки принципиально неправильными. Возьмём recovery — middleware с отложенным recover(), превращающий панику в ошибку 500. Паника раскручивает стек кадров по одному, и в каждом middleware код после next(c) просто не исполняется — кадр убит. Если recovery добавить раньше логгера (то есть recovery окажется снаружи), то паника из обработчика пролетит сквозь логгер, не дав ему напечатать строку, и остановится на recovery. Запрос уйдёт с 500, а в логе — ничего.

Именно поэтому в примере из доккомментария самого пакета echo порядок такой: e.Use(middleware.Logger()), затем e.Use(middleware.Recover()) — логгер снаружи, recovery внутри. Логгер печатает строку на каждый запрос, включая паникующий; recovery конвертирует панику в ошибку и возвращает её, логгер фиксирует статус 500. Тот же принцип для ваших слоёв: сначала то, что должно видеть всё, потом то, что может отклонить или уронить. И ещё один порядок в голове: c.Error(err) внутри middleware уже фиксирует ответ — после него писать в ответ поздно, Response становится committed, и любая следующая попытка WriteHeader даст в логе net/http предупреждение о superfluous WriteHeader.

Мы собрали руками то, что Echo даёт готовым: у пакета middleware есть Logger с конфигурируемым форматом, Recover с печатью стека, RequestID, Timeout, Gzip и ещё дюжина слоёв на все случаи — от CORS до rate limit; их разбор — тема следующего урока про встроенные middleware. Ваша связка логгер-таймер плюс authStub — не учебная игрушка: замена fmt.Printf на структурный логгер и заглушки на настоящую проверку паролей превращает её в боевой каркас.

И вернёмся к конвейеру из прошлого урока: bind → normalize → validate — три одинаковые строки в каждом обработчике. Это классический кандидат на обёртку: middleware, который прогоняет валидацию до того, как обработчик получит управление, — с Skipper-ом и передачей результата через c.Set. Попробуйте сделать это домашним упражнением — в задании ниже есть каркас. Навигация по курсу — на странице курса Echo; устройство ответов и статусов, вокруг которых всё это крутится, разобрано в уроке про запросы и ответы, а конвейер валидации, который теперь можно обернуть, — в уроке про привязку и валидацию.