Итоговый проект: микросервис на go-kit

Спецификация короткая, чтобы хватило места на сборку, а не на бизнес-логику. Shortener — сокращатель ссылок: метод Encode принимает длинный URL и возвращает короткий код из шести символов, метод Decode принимает код и возвращает исходный URL. Коды живут в памяти под мьютексом — так же, как задачи в каноне уроков 02-04: проект этого урока о архитектуре, а не о хранении, и замена памяти на базу данных должна занимать один файл. Один из методов — административный: Delete запрещает дальнейшее использование кода и доступен только владельцу токена, поэтому проект заодно демонстрирует авторизацию из урока 23. Каждый успешный Encode публикует событие shortener.url.created в шину из урока 22 — аудит желает знать, что появилось новое сокращение. Сервис слушает HTTP на 8080 и gRPC на 8081 — двуязычность из урока 13. Health-check из урока 20 отвечает на /healthz, метрики из урока 07 — на /metrics. Всё остальное — точки, в которых уроки курса встают друг на друга: ниже разберём каждую.

Структура проекта — расширенная карта из урока 17, и её стоит рассмотреть до кода, потому что в ней видно всё обучение. В корне — main.go, композиционный корень: единственное место, где создаются конкретные реализации и связываются интерфейсы. В internal/service — бизнес-логика: интерфейс StringService-стиля с методами Encode, Decode, Delete и его memory-реализация под мьютексом; никакой HTTP, никакого JSON — чистый Go. В internal/endpoint — endpoint'ы: по одному на метод, request/response-структуры рядом, плюс auth-middleware из урока 23, который вешается не на все, а на адресный endpoint. В internal/transport — два транспорта: HTTP с декодерами и энкодерами из урока 04 и gRPC-биндинг из урока 13. В internal/middleware — стек endpoint-обёрток: логирование, метрики, лимит, предохранитель — ровно в том порядке, который обосновали в уроке 09. В internal/events — шина и издатель из урока 22. В internal/config — конфигурация из урока 18: адреса, таймауты, секрет JWT. Тесты лежат рядом с кодом — правило из урока 16. Раскладка скучная — и это комплимент: скучная раскладка читается без карты.

Каждый метод сервиса превращается в endpoint — функцию из request в response, как в уроке 02. Структуры запросов плоские и без тегов: теги живут в транспорте. EncodeEndpoint достаёт longURL из request, зовёт сервис, упаковывает code. DecodeEndpoint — то же для кода. DeleteEndpoint — самый интересный: перед вызовом сервиса он обязан знать, кто звонит, и имя владельца кладёт в request из контекста — туда его положит auth-middleware из урока 23. Над всеми тремя — стек middleware из уроков 06, 07, 09 и 10, и порядок имеет значение: логирование — снаружи, чтобы видеть результат после всех оборотов; метрики — следующими, чтобы замерять латентность целиком; предохранитель — до лимита, чтобы отказы разомкнутой цепи не съедали токены лимитера; лимит — последним перед endpoint'ом, чтобы отсекать непосредственно перед бизнес-логикой. Этот порядок был обоснован в уроке 09 — в проекте он виден одной строкой цепочки, и читатель проекта понимает его без комментария.

Транспорт — переводчик: декодер превращает HTTP-тело в request, endpoint выполняется, энкодер превращает response в ответ. Декодер Encode принимает JSON {"url": "..."} и валидирует: пустая строка — badRequestError из урока 05, который энкодер превратит в 400 с телом ошибки, не пачкая лог серверным стеком. Декодер Delete читает код из пути и требует заголовок Authorization — его отсутствие auth-middleware превратит в 401. Энкодеры пишут JSON и ставят статус: 201 для созданного кода, 200 для найденного, 404 на service.ErrNotFound — маппинг сентинелов на коды ответа живёт в одном месте, как учил урок 05. gRPC-транспорт из урока 13 биндит те же endpoint'ы к proto-сервису: ни строки бизнес-логики, только перекладывание между proto-сообщениями и request-структурами. Один сервер имплементации — два транспорта — ноль дублирования логики: это главный дивиденд слоистой архитектуры, и в проекте он проверяется тестом, который гоняет один и тот же сценарий через оба транспорта.

Логирование из урока 06: JSON-логгер, поля endpoint, method, took, err на каждом запросе; уровни фильтруются env-переменной LOG_LEVEL, чтобы в проде не тащить дебаг. Метрики из урока 07: счётчик запросов с метками endpoint и status, гистограмма латентности с buckets по экспоненте, gauge глубины шины событий — на дашборде сразу видно, копятся ли факты. Health-check из урока 20: /healthz отвечает 200 всегда, когда процесс жив, — это liveness; readiness-файл не нужен сервису без внешних зависимостей, но hook для него оставлен — при замене памяти на базу он заполнится проверкой соединения. События из урока 22: сервисный middleware издателя оборачивает только Encode — успешное сокращение публикует факт shortener.url.created с payload из кода и длинного URL; ошибка шины не роняет запрос, она пишет лог и поднимает счётчик дропов. Каждый из этих слоёв настраивается независимо — и все они вместе добавили меньше ста строк к проекту.

Пирамида тестов проекта собрана из готовых блоков. Основание — юнит-тесты сервиса: memory-реализация проверяется таблицей кейсов на Encode-Decode-Delete, включая коллизию кодов и чужого владельца; мьютекс проверяется гонкой — go test -race с сотней параллельных Encode. Средний уровень — endpoint-тесты: каждый endpoint вызывается как функция без транспорта, auth-middleware тестируется отдельно — валидный, просроченный, чужой токен; тот самый predict-сценарий 401-403-200 живёт здесь как table-driven тест. Вершина — транспортные тесты через httptest из урока 16: полный стек от HTTP-запроса до ответа, включая проверку, что badRequestError приходит 400 с телом, а не роняет сервер. Интеграционный тест собирает весь main.go: поднимает оба транспорта, гоняет сценарий сокращения через HTTP, проверяет событие в шине, гасит graceful'ом и требует exit 0. И финальный аккорд — тест обоих транспортов на одной имплементации: сценарий прогоняется дважды, через HTTP и через gRPC, результаты обязаны совпасть байт в байт.

Собранный проект проверяется сценарием из пяти команд, и это одновременно приёмочный тест. Первая — старт: docker run -p 8080:8080 -p 8081:8081 -e JWT_SECRET=dev-secret shortener && curl -s localhost:8080/healthz — жив. Вторая — сокращение: curl -X POST localhost:8080/urls -d '{"url":"https://go.dev"}' — в ответе код из шести символов. Третья — обратный путь: curl localhost:8080/urls/{код} — исходный URL. Четвёртая — наблюдаемость: curl -s localhost:8080/metrics | grep shortener_requests_total — счётчики дышат, гистограмма наполнилась. Пятая — дренаж: docker stop с SIGTERM, в логах — порядок остановки из урока 19 и exit 0. Пять команд покрывают все слои, потому что каждый слой проекта обязан быть видимым снаружи: либо ответом, либо метрикой, либо строкой лога. Невидимый слой — неисправный слой, это правило стоит поместить на первый экран внутренней вики команды.

Курс собран, проект собран — осталось только твоё. Карта всех двадцати пяти уроков лежит на странице курса; если какой-то слой коротает ночь в голове непонятой, вернитесь к первоисточнику: endpoint'ы — в уроке 02, стек обёрток — в уроках 09 и 10, gRPC — в уроке 13, остановка — в уроке 19, события — в уроке 22. Микросервис go kit из этого урока — не конечная точка, а стартовая площадка: подменяйте реализации, наращивайте стек, выпускайте модули. И помните правило курса: сначала контракт, потом реализация, потом обвязка — в этом порядке код не гниёт.