Мидлвари сервисов

Урок 03 подарил тебе первый декоратор — LoggingMiddleware вокруг StringService — и обещал «разложить по полочкам» в отдельном уроке. Полочки такие. Во-первых, паттерн: type ServiceMiddleware func(StringService) StringService — тип-псевдоним, конструктор с зависимостями, структура со встраиванием интерфейса и переопределением нужных методов; один лекал закрывает кэш, ретраи, бизнес-метрики и прокси. Во-вторых, композиция: декораторы навешиваются матрёшкой в main до создания endpoint'ов, и порядок этой матрёшки — самостоятельное инженерное решение со своими правилами. В-третьих, инъекция зависимостей: logger, хранилище, кэш входят через конструкторы, никакого глобального состояния — урок 03 это заложил, здесь доведём до среза обёрток и функции применения. В-четвёртых, граница: что уносится в декоратор, а что остаётся endpoint-обёртке из урока 14. Прокси из урока 11-lb-proxy — proxymw и proxyingMiddleware — окажется частным случаем того же паттерна, и после этого урока все обёртки курса встанут в единую систему из двух этажей. Ключ к слою один: go kit service middleware живёт над интерфейсом домена и не знает про транспорт ничего.

Начни с определения, которое нужно запомнить дословно: type ServiceMiddleware func(StringService) StringService. Декоратор — функция, принимающая сервис и возвращающая сервис; сигнатура не меняется, поэтому main может навесить хоть пять штук подряд, и тип останется StringService. Отсюда первое отличие от endpoint-этажа: там существовал универсальный endpoint.Middleware, пригодный к любому endpoint'у; здесь универсального типа в пакете нет — у каждого сервиса свой псевдоним со своим интерфейсом. Это не неудобство, а честность: декоратор сервиса связан с доменом сильнее, чем endpoint-обёртка с запросом, и компилятор обязан это видеть. Второе отличие — момент исполнения: endpoint-обёртка применялась к готовой функции; service-декоратор применяется к реализации интерфейса ДО построения endpoint'ов — makeUppercaseEndpoint из урока 02 получает уже декорированный svc и про обёртки не знает. Третье отличие — видимость: декоратор видит доменные аргументы и может принимать решения по их содержимому («пустая строка — не кэшировать»), endpoint-обёртка видит только ctx и interface{}. Именно поэтому кэш из этого урока невозможен наверху, а лимитер из урока 09 — невозможен внизу: у каждого этажа свои вопросы.

Пора за рукотворное. Кэш — хрестоматийный resident service-этажа: он знает, что ключ — это строка s из домена, и решает «отвечать или считать», меняя саму суть вызова; endpoint-обёртка на это не способна в принципе, ведь request-структуру ей трогать запрещено правилами урока 14. Реализация — тот же лекал: структура с встроенным StringService, картой и RWMutex, переопределённый Uppercase. Обрати внимание на два решения внутри. Первое: кэшируем только успешные вычисления — ошибка ErrEmpty не попадает в карту, иначе пустой ввод один раз закэшируется и сервис навсегда перестанет его валидировать. Второе: Count не кэшируется вообще — переопределений меньше, поведение прозрачнее; захочешь — допишешь по тому же лекалу. RWMutex вместо Mutex: чтения много, записи редки — read-блокировка параллелит читателей. Кэш здесь in-memory для простоты; продовый вариант прячет хранилище за интерфейсом из урока 03 и подставляет Redis-реализацию тем же конструктором — инъекция зависимостей в действии.

Декораторы навешиваются последовательно: svc = NewLoggingMiddleware(logger)(svc), затем svc = NewCachingMiddleware(m)(svc), и так далее. Читается сборка изнутри наружу: самый последний надетый декоратор стоит снаружи и встречает вызов первым — та же арифметика, что у ручной обёртки endpoint'ов из урока 02. Каноническое правило уроков 06-10 «кто внутри — тот пишет первым» работает и здесь: defer внутреннего декоратора сработает раньше defer внешнего. Как выбрать порядок? Задай вопрос, что должно быть видимым. Логи снаружи кэша видят и попадания, и промахи — дежурный видит полный трафик; логи внутри видят только реальные вычисления, зато took показывает чистую стоимость базы. Метрики бизнес-событий обычно ставят самым внешним слоем: счётчик должен считать каждый вызов, включая кэш-хиты. Кэш — самым внутренним, перед самой реализацией: его место — стереть вызов, а не пропустить его через все слои. Прокси из урока 11 в stringsvc3 стоит снаружи метрик — запрос сначала решает «я или сосед», и только потом уходит в подсчёты. Каждая перестановка — легальна и осмысленна; документируй выбор комментарием в main, как это делалось с порядком endpoint-цепочки.

Теперь у тебя есть карта, и proxymw из урока 11-lb-proxy встаёт на место без сюрпризов: proxyingMiddleware — это service-декоратор, структура с встроенным StringService, чей переопределённый Uppercase зовёт makeUppercaseProxy и иногда отвечает чужим ответом. Почему прокси — service-этаж, хотя он ходит в сеть? По двум нашим же проверочным вопросам: он знает домен (перенаправляет конкретный метод с конкретной строкой) и меняет семантику вызова (отвечает вместо локального вычисления) — оба ответа указывают на декоратор. При этом клиентская нога прокси — endpoint из kithttp.NewClient, — обёрнута в свой endpoint-цепочку с breaker'ом и метриками: этажи не смешиваются, каждый работает со своим слоем абстракции. Именно так канонический stringsvc3 собирает main: базовая реализация, поверх — прокси-декоратор, поверх — логи и метрики сервиса, затем endpoint'ы, затем endpoint-middleware из урока 14, затем транспорты из уроков 04 и 13. Двухэтажная система обёрток — главное архитектурное наследие курса; запомни порядок сборки, он понадобится в итоговом проекте урока 25.

Урок 03 сформулировал правило: зависимости входят через конструкторы, глобальное состояние запрещено. Service-middleware — главный потребитель этого правила: logger, карта кэша, репозиторий, лимит хранилища — всё приходит параметрами конструктора, и декоратор не имеет права заводить свои пакеты-глобалы. Что это даёт на практике. Тестируемость: в тесте подставляется fake-логгер или пустая карта, и декоратор тестируется изоляционно — это будет кодом урока 16. Конфигурируемость: одна и та же матрёшка собирается с Redis-кэшем или с in-memory по флагу запуска. Явность: по сигнатуре NewCachingMiddleware видно, что обёртке нужен кэш, — ничего не прячется в пакетных переменных. Когда декораторов становится больше пяти, сборка в main превращается в лестницу из одинаковых строк; на этот случай держи функцию применения среза — applyMiddleware из следующего блока. Она — единственное место, где список декораторов и порядок их применения живут вместе, и её же удобно передавать в тесты: тест собирает матрёшку из своих стабов той же функцией, что и прод-код.

Границу урока 14 теперь можно расписать по списку. В service-декораторы уносится всё, что понимает домен: кэш по ключу, ретраи к хранилищу, метрики бизнес-событий («сколько строк посчитано»), логи уровня операций с доменными полями, лимиты на доменные сущности, прокси к другим инстансам. В endpoint-обёртках остаются путь запроса и наблюдаемость: логи method/err/took, request_count, спаны, токен-бакет, предохранитель, дедлайн, recovery. Есть серые зоны — проговори их честно. Ретраи: к внешнему хранилищу — декоратор (он знает операцию и её идемпотентность); к балансированным инстансам — lb.Retry на endpoint-этаже из урока 11, потому что это вопрос пути запроса. Метрики: транспортные (латентность запроса) — endpoint; бизнес-события (посчитано строк) — декоратор. Логи: на каждый вызов с method/err/took — endpoint; с input/output домена — декоратор. Третий критерий для сомнительных случаев: попробуй протестировать обёртку без транспорта и без endpoint'а, только с fake-сервисом; если тест выразился естественно — место декоратора верное, если потребовался ctx с request-структурой — это endpoint-этаж.

Второй хрестоматийный декоратор — ретраи — требует одной оговорки, которой не было у кэша. Повтор вызова Uppercase безопасен: операция чистая, строку в uppercase можно переводить сколько угодно раз. Но декоратор, повторяющий произвольные операции, — мина: если метод списывает деньги или публикует событие, повтор после частичного сбоя удвоит эффект. Правило то же, что и в lb.Retry из урока 11: ретраи только идемпотентных операций, и знание об идемпотентности живёт в домене — значит, и ретраи к хранилищу пишутся декоратором, который переопределяет только безопасные методы. Реализация — лекал, знакомый по кэшу: структура со встроенным интерфейсом, переопределённый метод, цикл из трёх попыток с паузой. Дополнение из урока 10: ретраи поверх breaker'а не ставятся никогда — обёртка не знает, где живёт предохранитель, и повтор может добить полуживую цепь; на нижнем этаже лимитер и breaker уже решают, кому идти, а декоратор получает только доброкачественный трафик. Если операция не идемпотентна — добавь ей идемпотентность (idempotency key в аргументах) или оставь единственную попытку.

Пройди глазами всю систему: stringService{} реализует Uppercase и Count — и не импортирует ничего из go-kit, кроме контекста; декораторы реализуют тот же интерфейс поверх, ничего не добавляя к контракту; endpoint'ы из урока 02 адаптируют методы к универсальной сигнатуре; endpoint-обёртки из уроков 06-14 обвешивают функции; транспорты из уроков 04 и 13 сериализуют. Каждый слой знает только соседей, и контракт между слоями — интерфейс сервиса и тип Endpoint. Именно это имел в виду урок 01-filosofiya, обещая «инструменты, а не каркас»: ни один слой не придётся переписать при смене соседа — смена транспорта не трогает декораторы, добавление кэша не трогает endpoint'ы, новый декоратор не трогает домен. Проверка на чистоту проста и красива: pkg-каталог сервиса собирается без единого импорта go-kit — если grep находит в домене kitlog или kitratelimit, слой протёк. Чек-лист декоратора из следующего блока — финальная полировка перед тестами урока 16, где вся эта матрёшка будет проверена изоляционно.

Система обёрток курса собрана полностью: endpoint-этаж из урока 14 и service-этаж этого урока закрывают все сквозные задачи stringsvc, а домен остался чистым — как обещал урок 03. Осталось научиться всё это проверять. Урок 16-testirovanie — про тестирование go kit: unit-тесты endpoint'ов прямыми вызовами, fake-next для endpoint-обёрток, fake-сервис для декораторов, кодеки через httptest.NewRecorder и интеграционные тесты транспорта. После него карта курса ведёт в сборку большого сервиса — уроки 17-18 про структуру и конфигурацию; путь до туда — на странице курса.