NestJS: полное пошаговое руководство от инициализации до production

NestJS стремительно завоевал сердца backend-разработчиков, работающих с TypeScript и Node.js. Он не просто еще один фреймворк, а полноценная архитектурная платформа, вдохновленная Angular и использующая мощь прогрессивного JavaScript. Его магия — в предоставлении готовой, хорошо структурированной архитектуры «из коробки», что позволяет сосредоточиться на бизнес-логике, а не на бесконечных boilerplate-решениях. Это пошаговое руководство проведет вас через весь путь создания приложения — от первой команды в терминале до развертывания в production.

Шаг 1: Основа основ — установка и создание проекта. Убедитесь, что у вас установлен Node.js (версии 16 и выше) и npm/yarn. Откройте терминал и выполните команду: `npm i -g @nestjs/cli`. Это установит глобально NestJS CLI — ваш главный инструмент для работы. Теперь создайте новый проект: `nest new my-first-nest-app`. CLI предложит выбрать пакетный менеджер (выберите npm или yarn). После завершения процесса перейдите в созданную директорию (`cd my-first-nest-app`) и запустите приложение командой `npm run start:dev`. Откройте браузер на `http://localhost:3000` — вы должны увидеть приветственное сообщение «Hello World!». Поздравляем, вы только что запустили свое первое NestJS-приложение в режиме разработки с hot-reload.

Шаг 2: Понимание структуры проекта. Остановите сервер (Ctrl+C) и изучите созданные файлы. Ключевые элементы: `src/main.ts` — точка входа, где создается и запускается экземпляр приложения. `src/app.module.ts` — корневой модуль (root module), который является отправной точкой для построения графа зависимостей. `src/app.controller.ts` и `src/app.service.ts` — примеры базовых строительных блоков: контроллера, обрабатывающего HTTP-запросы, и сервиса, содержащего бизнес-логику. NestJS построен на модульной архитектуре. Модули (`@Module()` декоратор) инкапсулируют связанную функциональность. Контроллеры (`@Controller()`) отвечают за обработку входящих запросов и возврат ответов. Провайдеры (`@Injectable()`, чаще всего сервисы) — это классы, которые могут быть внедрены как зависимости (Dependency Injection — краеугольный камень NestJS).

Шаг 3: Создание собственного функционального модуля. Давайте создадим простой модуль для управления статьями блога. CLI здесь наш лучший помощник. Выполните: `nest generate module articles` или короче `nest g mo articles`. Будет создана папка `articles` с файлом `articles.module.ts`. Теперь создадим ресурс: `nest generate resource articles`. CLI спросит, какой транспорт использовать — выберите `REST API`. Он также спросит, генерировать ли CRUD-эндпоинты — ответьте «Y» (да). Магия CLI создаст полный набор файлов: контроллер, сервис, модуль (обновленный), DTO (Data Transfer Object), сущность и даже unit-тесты. Изучите созданные файлы. Обратите внимание, как в `ArticlesService` инжектируется репозиторий (пока это массив в памяти), а в `ArticlesController` инжектируется сервис. Это и есть Dependency Injection в действии.

Шаг 4: Работа с данными — подключение реальной базы данных. Хранить данные в памяти недостаточно. Подключим PostgreSQL с использованием TypeORM — популярного ORM, который отлично интегрирован с NestJS. Установите пакеты: `npm install @nestjs/typeorm typeorm pg`. Далее, импортируйте `TypeOrmModule` в корневой `AppModule`. В `app.module.ts` добавьте в массив `imports`: `TypeOrmModule.forRoot({ type: 'postgres', host: 'localhost', port: 5432, username: 'your_user', password: 'your_pass', database: 'nest_db', autoLoadEntities: true, synchronize: true, // Только для разработки! })`. Теперь обновите сущность `Article` в папке `articles`. Используйте декораторы TypeORM (`@Entity()`, `@Column()` и т.д.), чтобы описать таблицу. Наконец, в `articles.module.ts` импортируйте `TypeOrmModule.forFeature([Article])`. Это зарегистрирует репозиторий для сущности `Article`, и его можно будет инжектировать в `ArticlesService`. Теперь ваш сервис может выполнять реальные запросы к БД.

Шаг 5: Валидация, аутентификация и документация. Без этих трех китов современное API неполноценно. Для валидации входящих данных (DTO) установите `class-validator` и `class-transformer` и подключите глобальный `ValidationPipe` в `main.ts`. Для аутентификации можно использовать Passport.js стратегии (`@nestjs/passport`). Самый распространенный сценарий — JWT (JSON Web Tokens). Установите `@nestjs/jwt` и `@nestjs/passport` и создайте модуль `auth`. Для автоматической генерации документации Swagger установите `@nestjs/swagger` и настройте его в `main.ts`. NestJS позволяет с помощью декораторов (`@ApiProperty()`, `@ApiTags()`) обогащать ваши DTO и контроллеры метаданными для создания исчерпывающей и актуальной API-документации.

Шаг 6: Подготовка к Production. Режим разработки с `synchronize: true` и хардкодом конфигурации должен уйти. Перенесите конфигурацию (параметры БД, JWT-секреты) в переменные окружения, используя, например, `@nestjs/config` (пакет `@nestjs/config` на основе dotenv). Отключите `synchronize` и используйте миграции TypeORM для управления схемой БД. Настройте разные конфигурационные файлы для `development`, `test` и `production`. Убедитесь, что все чувствительные данные вынесены. Создайте `Dockerfile` для контейнеризации вашего приложения. Напишите комплексные e2e-тесты, используя встроенную в NestJS утилиту `Test.createTestingModule`. Наконец, рассмотрите использование процесса менеджера вроде PM2 или развертывание в виде Docker-контейнера на облачной платформе (AWS ECS, Google Cloud Run).

NestJS — это фреймворк с глубокой философией. Он навязывает структуру, но эта структура освобождает от хаоса и масштабируется вместе с вашей командой и приложением. Следуя этому пошаговому руководству, вы не просто научитесь писать код на NestJS, а усвоите принципы построения чистых, тестируемых и поддерживаемых серверных приложений enterprise-уровня.