Чистый дизайн API в Node.js
Большинство Node.js API начинаются с одного файла server.js и нескольких маршрутов. Это работает, пока приложение небольшое.
Затем приложение растет.
Количество маршрутов множится. Бизнес-логика просачивается в обработчики маршрутов. Обработка ошибок превращается в мешанину из скопированного кода. Новым разработчикам трудно понять, где что находится. API всё еще работает, но его становится сложно поддерживать.
Чистый дизайн API предотвращает это. Вам нужна структура, которая разделяет зоны ответственности.
Вот как построить профессиональный API слой за слоем:
- Структура проекта: Используйте папки по фичам (feature folders). Каждый домен должен иметь свой роутер, контроллер, сервис и схему.
- Версионирование: Начинайте с
/api/v1/с первого же дня. Добавление v2 в будущем должно сводиться к перемещению папки, а не к полному рефакторингу. - Слой контроллеров: Контроллеры отвечают за HTTP. Они преобразуют запросы в вызовы сервисов и отправляют ответы. Они не содержат бизнес-логику.
- Слой сервисов: Здесь живет ваша бизнес-логика. Сервисы не должны знать об объектах
reqилиres. Их интересуют только данные и правила. - Валидация: Используйте Zod на границе приложения. Валидируйте входные данные до того, как они попадут в контроллеры. Это предотвратит поломку логики из-за некорректных данных.
- Централизованная обработка ошибок: Используйте один единый обработчик ошибок для всего приложения. Это гарантирует, что каждый ответ об ошибке будет иметь одинаковую структуру.
- Единообразные ответы: Используйте хелпер для формирования ответов об успехе и ошибках. Предсказуемый JSON облегчает жизнь фронтенд-разработчикам.
- Rate Limiting: Защитите свои эндпоинты от злоупотреблений с помощью middleware.
- Документация: Используйте Swagger для автоматической генерации интерактивной документации API.
Почему это важно:
Разделяя эти слои, вы получаете гибкость. Если вам нужно перейти с мок-базы данных на реальную, вы меняете только сервис. Контроллеры и роутеры остаются нетронутыми.
Если вам нужна лучшая производительность и встроенная поддержка TypeScript, рассмотрите Fastify. Принципы структуры остаются прежними, но фреймворк берет на себя больше задач.
Хватит сваливать всё в один файл «на время». Создание правильной структуры на ранних этапах — это не оверинжиниринг. Это минимальное требование для поддерживаемого бэкенда.
Как выглядит ваша текущая настройка Express? Используете ли вы многослойную архитектуру или «органическую»?
Источник: https://dev.to/gavincettolo/clean-api-design-in-nodejs-a-practical-guide-3a32