Итоговый проект: REST API заметок на Fiber

Начнём с того, чем закончили: «двадцать пятый урок — финальный: итоговый проект «REST API заметок на Fiber»: CRUD, валидация, JWT, лимиты — готовое мини-приложение. Логика прямая: сегодня мы научились измерять и понимать движок, завтра соберём из двадцати четырёх уроков один проект, где слои, тесты, аутентификация и деплой-артефакты встретятся в одном main.go — и прогоним его от go mod init до curl через nginx». Сегодня — тот самый завтра. Инвентаризация перед сборкой: слои и DI — урок двадцать второй; тесты без сети — двадцать первый; валидация адаптером — десятый урок StructValidator; лимиты — семнадцатый; единый ErrorHandler — четырнадцатый; конфигурация и сигналы — двадцатый; артефакт и окружение — двадцать третий. Нового будет ровно один блок — JWT-аутентификация: честная замена заглушке седьмого урока, потому что итоговый проект без реального входа — не итоговый проект. Правило сборки прежнее: инварианты канона — :8080, json-конверты, фабрика buildApp — не ломаются; то, что менялось раньше слоями, теперь меняется проектом целиком.

Любой fiber проект начинается не с кода, а с контракта: какие эндпоинты существуют, кто их пускает и что они отвечают. Строим API заметок — сущность Note с полями id, title и body: задачи из канона выросли в заметки, добавилось тело, и это единственная вольность, зато она даст работе настоящую валидацию с двумя полями и лимитами. Схема авторизации: POST /api/v1/login выдаёт JWT-токен за пару логин-пароль (в упражнении учётка одна и хардкодится в конфиге), остальные маршруты под /api/v1 требуют токен в заголовке Authorization. CRUD: список, создание, чтение по id, обновление, удаление. Плюс /healthz — открытый пульс для деплой-обвязки двадцать третьего урока: health-чек прокси и оркестратора не должен требовать токен. Каждый маршрут в таблице ниже подписан кодами успеха и отказов — и это не бюрократия: именно эта таблица превращается в table-driven тесты двадцать первого урока почти механически. Заметьте и версию /v1 в путях — пятнадцатый урок настаивал, что версия API закладывается с первого дня, и итоговый проект слушается. Таков контракт; дальше — структура, которая его выдержит.

География проекта — прямое продолжение структурного урока: три слоя handlers → service → repository с внутренним пакетом internal, композиционный корень buildApp, конфиг в internal/config. Единственная новая папка — internal/auth: там живут выдача и проверка JWT, и она выделена не ради красоты, а по должностной инструкции — auth знает про токены, но не знает про HTTP-конверты, как сервис не знает про статусы. Стена internal работает как раньше: чужой модуль не импортирует myapi/internal/..., а направленность слоёв держим конструкторами — auth и repository не оглядываются вверх. Обратите внимание, что хендлеры остались тонкими: разбор fiber.Ctx на входе, вызов сервиса, конверт на выходе; вся аутентификация вынесена из хендлеров в middleware, как учил седьмой урок, — CRUD-хендлер вообще не подозревает о существовании токенов, он просто вызывается уже проверенным. Тестовая база тоже наследуется: buildApp остаётся фабрикой, каждый тест собирает свежий инстанс, и поэтому таблица эндпоинтов выше превращается в таблицу тестовых кейсов без переписывания архитектуры под тесты — признак того, что структура хорошая.

Слой service — то место, где REST API становится не генератором статусов, а приложением с правилами. Модель Note несёт три поля и json-теги при них: ID, Title, Body — форму ответа видно прямо в структуре, как учил девятый урок. Контракт хранения NoteRepo объявлен у потребителя — тот же шов двадцать второго урока: List, Create, Get, Update, Delete — пять методов, которых требует наша таблица эндпоинтов. Ошибки домена — именованные sentinel-ы: ErrNoteNotFound для чтения и удаления мимо существующих, ErrEmptyTitle для пустого названия на входе сервиса — хотя в проекте на входе стоит и валидатор, домен обязан защищаться сам: валидация — про форму запроса, инвариант — про правило. И вот правило соединения двух проверок, которое стоит проговорить раз и навсегда: validator проверяет, что title — строка длиной от 1 до 200, а body не длиннее 2000, ещё до входа в сервис; сервис дополнительно возвращает ErrEmptyTitle, если его вызвали напрямую — из другого сервиса, из воркера, из теста. Транспортный слой переводит доменные ошибки в статусы лестницей из четырнадцатого урока: ErrNoteNotFound → 404 через fiber.NewError, ошибки валидации → 422, битый JSON → 400. Никто не пересекает чужих этажей: сервис не знает про 404, хендлер не знает про мьютекс.

Страж седьмого урока проверял статический ключ: один секрет на всех, отозвать нельзя, узнать «кто» — тоже. JWT — JSON Web Token — решает обе проблемы без базы сессий. Токен — это три блока base64url через точку: заголовок с алгоритмом, набор claims — подтверждаемых полей вроде sub и exp — и подпись. Сервер выдаёт токен на /login, подписав его секретным ключом, дальше просто проверяет подпись и сроки: хранить выданные токены не нужно — подпись сама гарантирует, что токен выдавали мы и его никто не подменил. Это и называется stateless-аутентификацией: состояние — в самом токене, а не в памяти сервера, поэтому и масштабируется JWT на несколько инстансов без sticky-сессий. Проверка обязана включать три пункта, и пропуск любого — уязвимость: подпись верна (секрет совпадает), алгоритм именно тот, что мы выдаём (иначе атакующий подсунет алгоритм без подписи — классика jwt-атак), срок exp не вышел (иначе токен вечен). Библиотека — golang-jwt/jwt/v5, стандарт де-факто экосистемы; берём v5-модуль с jwt.NewWithClaims и jwt.ParseWithClaims. Секрет придёт из окружения в JWTSecret конфига — не в исходники: урок о деплое уже объяснил, где живут секреты, — файл 0600, --env-file, и никогда git.

Теперь соединим защиту и маршруты, и здесь итоговый проект сводит два урока в одну боевую пару. Логин-эндпоинт — публичный, и именно поэтому он под лимитером семнадцатого урока: перебор паролей — первый сценарий, который rate limiting обязан закрыть, поэтому на /api/v1/login вешается limiter.New с Max 10 и Expiration в минуту, ключ — IP клиента: одиннадцатая попытка в окне получит 429 с Retry-After, о котором семнадцатый урок рассказывал. CRUD-ветка — под RequireJWT: группа r.Group("/api/v1", auth.RequireJWT(cfg.JWTSecret)) прячет проверку на входе группы, и все пять маршрутов заметок наследуют её автоматически — тот же рисунок общих слоёв, что в группах пятнадцатого урока. Отдельная тонкость: лимитер не стоит на всей группе /api/v1 — аутентифицированный CRUD не должен страдать от лимита логина, защита прикладывается точечно. /healthz регистрируется на корне приложения до всяких групп: пульс для nginx и docker не требует токен, иначе деплой-инфраструктура сочтёт живое приложение мёртвым. ErrorHandler в fiber.Config — единая точка отказов четырнадцатого урока: *fiber.Error отдаёт свой код, доменные sentinel-ы переводятся лестницей errors.Is/As, формат один для всего API. StructValidator в конфиге — адаптер десятого урока: без него Bind молча пропускал бы проверку, помните — слот пуст, вилка не воткнута.

Конфигурация проекта собирается по канону двадцатого урока без единого отклонения: os.Getenv вызывается один раз, в одном месте — internal/config.FromEnv, — и раздаёт значения вниз параметрами. Поля структуры Config пополнились четырьмя новыми: JWTSecret — секрет подписи, TokenTTL — срок жизни токена (дефолт — час: короткий срок и есть защита при утечке), User и Password — единственная учётка упражнения для /login. Переменные окружения канона: PORT и FIBER_READ_TIMEOUT из двадцатого урока плюс JWT_SECRET, JWT_TTL, LOGIN_USER, LOGIN_PASSWORD — ровно те, что деплой-урок подкладывает через --env-file или EnvironmentFile юнита. Каждый дефолт проверяется тестом t.Setenv из двадцать первого урока: подставили мусор — получили дефолт, а не тихо сломанный сервис. И главный гигиенический принцип: JWTSecret — не глобальная переменная и не константа в исходниках, а поле структуры, которое FromEnv наполнил, buildApp получила и раздала конструкторам — auth.RequireJWT(cfg.JWTSecret). Так проект читает окружение так же, как канон на :8080, — только переменных стало больше.

Самое приятное в финальном проекте — превращение контракта в проверку. Таблица эндпоинтов из начала урока почти дословно раскладывается на table-driven кейсы двадцать первого урока: строка «GET /api/v1/notes, отказ 401 без токена» — это тест-кейс с построением запроса без заголовка и утверждением StatusCode == 401. Полный набор проекта: без токена — 401 на всей ветке; с битым токеном — тоже 401; login с верной парой — 200 и токен в теле; login с неверной — 401; POST с битым JSON — 400; POST с пустым title — 422 от валидатора; POST корректный — 201; GET списка — 200 и конверт items; GET чужого id — 404; PUT и DELETE — по контракту, включая второй DELETE, который вернёт 404. Каждый кейс собирает свежий buildApp — состояние не течёт между тестами, и порядок их выполнения не важен. Валидация в тестах проверяется с двух сторон: статус 422 и тело с упоминанием поля — адаптер десятого урока возвращает fiber.NewError с текстом «поля заполнены неверно», и ErrorHandler проекта заворачивает его в наш формат. Токен в тестах получается честно: сначала POST /api/v1/login, из ответа берётся token, и он же идёт в заголовки — никаких магических констант, тест проходит тот же путь, что и клиент.

Оглянемся на маршрут, который прошли. Мы начали с вопроса «что такое Fiber и чем он отличается от Gin», подняли первый сервер на :8080, научились маршрутизировать и читать запрос, встраивали и писали middleware, закрыли JSON и валидацию, формы и cookie, шаблоны и ошибки, группы и WebSocket, лимиты и кэш, логи и конфигурацию, тесты и структуру, деплой и производительность — и сегодня собрали всё в rest api fiber с CRUD-заметками, JWT, лимитами и тестами. Если оглядеться по дереву проекта, каждый файл откликнется на урок: config.go — двадцатый, auth/jwt.go — седьмой, выросший, service/note.go — двадцать второй, handlers — четырнадцатый и десятый, тесты — двадцать первый, Dockerfile — двадцать третий, бенчмарки — двадцать четвёртый. Честное слово про песочницу: fiber-приложение в браузерном интерпретаторе сайта не запускается — runner-ов в уроках Fiber нет с первого урока, а интерактивы здесь quiz, predict, fill, order и флешкарты; финальный проект собирается локально, и в этом его честность: это настоящий fiber проект, который можно завернуть в контейнер и показать работодателю. Куда дальше: курс Gin покажет те же принципы на net/http-фундаменте — сравнение станет практикой, а не таблицей; курс go-advanced углубит Go вне HTTP — горутины, каналы, graceful shutdown в рабочем исполнении. Домашнее задание — это и есть выпускной экзамен.