js-fastify-rest-api-example

REST API на Fastify, собранный «по-взрослому»: схема API описана отдельно от кода, база через ORM, валидация по схеме.

Зачем это нужно

Пример того, как выглядит API-проект, когда он перерастает один файл с маршрутами. Отличия от учебной заглушки видны сразу:

• Контракт первичен. API описан на TypeSpec в main.tsp, из него генерируется OpenAPI, а из OpenAPI — типы для кода. Документация не расходится с реализацией, потому что порождена из одного источника.
• Одна спека проверяет код дважды. Из OpenAPI генерируются типы обработчиков и zod-схемы (hey-api): первое проверяет tsc статически, второе — валидаторы в рантайме. Сами маршруты по этой же спеке регистрирует fastify-openapi-glue, поэтому таблица маршрутов и проверка запросов тоже не пишутся руками. make generate-check в CI не даёт сгенерированному разойтись со спекой.
• База через Drizzle: схема в src/db/schema.ts, миграции генерируются по ней.
• Валидация входа отдельным слоем в src/validators/, а не внутри обработчика.
• Авторизация тоже из спеки. @useAuth в контракте применяет fastify-openapi-glue через securityHandlers, а не jwtVerify() в каждом обработчике — забыть его негде.
• Спека проверяется снаружи. make contract-test натравливает schemathesis на поднятое приложение: тот генерирует запросы из OpenAPI и ловит то, что не видят ни tsc, ни валидаторы — незадокументированные статусы, 5xx на краевых входах и неприменённую авторизацию.

Запуск

make setup
make dev
make test

Документация — на http://localhost:3000/docs, сама спека — на /openapi.json.

Полезное:

make routes             # список маршрутов
make migration-generate # миграция по изменённой схеме
make migration-check    # схема не менялась без миграции
make generate-types     # OpenAPI и типы из TypeSpec
make generate-check     # проверить, что сгенерированное закоммичено
make lint-openapi       # линт контракта
make contract-test      # schemathesis по спеке (нужен uv)
make test-coverage      # тесты с порогами покрытия
make mock               # поднять мок-сервер по OpenAPI

---

This repository is created and maintained by the team and the community of Hexlet, an educational project. Read more about Hexlet.

See most active contributors on hexlet-friends.