NestJS Backend: опыт, архитектура и лучшие практики для зрелых проектов

Вступление: зрелость как инженерный выбор

В мире разработки слишком часто побеждает спешка. Мы привыкли “делать MVP”, “выкатить как-нибудь”, “потом разберёмся”. Но любой, кто хоть раз сталкивался с поддержкой растущего продукта, знает: хаос не прощает легкомыслия.

Архитектура — это не набор функций, это инфраструктура доверия, ответственности и предсказуемости - фундамент, на котором строится бизнес, команда, будущее продукта.

В какой-то момент мы с командой осознали: если мы хотим не просто “выживать”, а развиваться, нам нужно не латать старое, а строить новое — осознанно, системно, с прицелом на годы вперёд.
Мы выбрали путь зрелой архитектуры, где каждый модуль, каждый слой, каждый паттерн — не случайность, а результат анализа, обсуждений и опыта.

NestJS стал для нас платформой для внедрения инженерной культуры: модульность, строгая типизация, прозрачность зависимостей, поддержка лучших практик из мира TypeScript и Node.js.

Для кого эта статья

`- от хаоса к гармонии`

Когда-то мы начинали с быстрых MVP: “главное, чтобы заработало”. Но время шло, проекты росли, а с ними росли и требования — к скорости, безопасности, масштабируемости. И вот мы оказались на распутье: либо продолжать латать дыры, либо построить что-то по-настоящему крутое. Мы выбрали второе.

NestJS стал нашим верным спутником в этом приключении. Этот фреймворк — как швейцарский нож для разработчика: модульный, строгий, с поддержкой TypeScript и кучей готовых инструментов. Но даже с таким помощником без правильного подхода можно заблудиться. Поэтому мы взялись за дело с умом: продумали архитектуру, внедрили лучшие практики и отточили процессы. И знаете что? Получилось нечто, чем хочется поделиться с вами.

Эта статья содержит опыт, выстраданный через десятки итераций, бессонные ночи и горячие споры в команде. Здесь вы найдёте всё: от структуры проекта до мелочей вроде логирования и тестов. А ещё — немного вдохновения, чтобы ваш следующий проект стал шедевром.

Эта статья пишется для тех, кто устал от хаоса и хочет порядка. Для тех, кто строит не “ещё один сервис”, а платформу, которую не стыдно показать коллегам, инвесторам, самому себе через год.

Здесь не будет банальных советов и поверхностных решений. Только проверенные подходы, реальные грабли, архитектурные решения, которые выдержали нагрузку и время. Это систематизация опыта: от структуры папок до CI/CD, от DTO-first API до Docker-окружения, от логирования до тестов.

Здесь вы найдёте не только “как”, но и “зачем” — мотивацию, причины, последствия каждого решения.

Если вы ищете не волшебную таблетку, а рабочую систему — добро пожаловать.
Пусть ваш backend станет надёжным и удобным для команды, прозрачным для бизнеса, готовым к росту и переменам.

Введение:

В современном мире backend-разработки требования к качеству, безопасности и поддерживаемости кода постоянно растут. Мы прошли путь от “быстрого MVP” до архитектуры, которая выдерживает нагрузку, легко расширяется и радует как разработчиков, так и бизнес. В этой статье я расскажу, как мы шаг за шагом строили современный backend на NestJS, довели его до уровня, соответствующего требованиям крупных production-проектов, и какие подходы, паттерны и инструменты мы внедрили для удобства, безопасности и масштабируемости.

Статья будет полезна: - начинающим и опытным backend-разработчикам,
- тимлидам и архитекторам,
- всем, кто хочет понять, как строить поддерживаемые и надёжные серверные приложения.

1. Архитектура проекта: фундамент для роста

1.1. Модули и слои: разделяй и властвуй

Всё начинается с архитектуры. Мы строим проект по принципу “один бизнес-домен — один модуль”. Это значит, что у нас есть отдельные модули для пользователей, проектов, аутентификации и т.д.

В каждом модуле:

- controllers/ — только маршрутизация и валидация входных данных. Здесь нет бизнес-логики!

- services/ — бизнес-логика, работа с БД, валидация бизнес-правил. Только здесь решается, “можно ли” и “как именно”.

- dto/ — только DTO, специфичные для этого модуля. DTO — это “контракт” между backend и frontend.

- entities/ — только TypeORM-сущности. Это “отражение” таблиц в базе.

Пример структуры:

src/ modules/ users/ controllers/ services/ dto/ entities/ projects/ auth/ shared/ dto/ common/ filters/ utils/ dto/

Почему это важно?

Такой подход позволяет легко масштабировать проект, добавлять новые фичи, не боясь “сломать всё”. Каждый модуль — как мини-приложение, но с едиными стандартами.

1.2. Shared и Common: не дублируй, а делись

В зрелом проекте архитектура должна не только обеспечивать масштабируемость, но и минимизировать дублирование кода, облегчать сопровождение и ускорять разработку новых фич. Для этого мы чётко разделяем два слоя: shared и common.

Shared/ — библиотека бизнес-логики

Папка `shared/` — это не “склад” общих файлов, а настоящая библиотека бизнес-типов и DTO, которые используются в нескольких модулях. Здесь живут те сущности, которые отражают бизнес-реальность и нужны сразу в нескольких частях приложения.

Что кладём в shared:

- DTO для пагинации (`PaginateDto`, `PaginatedResult<T>`)

- Общие идентификаторы (`IdentifierDto`)

- Базовые бизнес-ответы (например, `SuccessResponseDto`, `ErrorResponseDto`)

- Общие типы и интерфейсы, которые описывают бизнес-логику (например, `UserRole`, `StatusEnum`)

- DTO для фильтрации, сортировки, поиска, если эти механизмы повторяются в разных модулях

Зачем это нужно: Когда бизнес-логика повторяется в разных модулях (например, пагинация нужна и для пользователей, и для проектов, и для заказов), мы не копируем код, а используем единый контракт. Это гарантирует согласованность API, облегчает поддержку фронта и ускоряет внедрение новых сущностей.

Пример: // shared/dto/paginate.dto.ts export class PaginateDto { page?: number = 1; limit?: number = 10; }

// shared/dto/paginated-result.dto.ts export interface PaginatedResult<T> { items: T[]; total: number; page: number; limit: number; }

Common/ — инфраструктурный слой

Папка `common/` — это технический фундамент приложения. Здесь лежит всё то, что не связано напрямую с бизнес-логикой, но обеспечивает стабильную работу, безопасность и удобство разработки.

Что кладём в common:

- Глобальные фильтры ошибок (`HttpExceptionFilter`)

- Middleware (например, логирование, CORS, трекинг запросов)

- Глобальные константы (например, лимиты, дефолтные значения)

- Утилиты и хелперы (например, функции для работы с датами, генерация токенов, парсинг переменных окружения)

- Глобальные guards, interceptors, pipes

- Базовые технические DTO (например, для health-check)

Всё, что касается инфраструктуры, технических аспектов и “склеивания” приложения, должно быть централизовано. Это позволяет быстро вносить изменения, не затрагивая бизнес-логику, и обеспечивает единые стандарты по всему проекту.

Пример:
// common/filters/http-exception.filter.ts @Catch(HttpException) export class HttpExceptionFilter implements ExceptionFilter { // ...логика логирования и форматирования ошибок... }

// common/utils/get-env-var.ts export function getEnvVar(key: string, fallback?: string): string { // ...логика получения переменной окружения с учётом контура... }

Философия: “Не дублируй, а делись”

- Всё, что может понадобиться в нескольких местах — выносится в shared.
- Всё, что обеспечивает техническую инфраструктуру — в common.
- В модулях остаётся только то, что уникально для конкретного бизнес-домена.

Преимущества такого подхода:

- Единые стандарты: фронт и бэкенд всегда “говорят на одном языке”.

- Минимум дублирования: меньше багов, проще поддержка.

- Быстрый онбординг: новому разработчику легко понять, где искать нужный тип или утилиту.

- Гибкость: легко расширять проект, не боясь “сломать” что-то в другом модуле.

Чёткое разделение shared и common — это не формальность и не вопрос организации файловой системы. Это проявление зрелого инженерного мышления, осознанного подхода к переиспользованию и стратегической заботы о поддерживаемости и будущем продукта. Придерживаясь этого принципа, избавляетесь от хаоса и закладываете фундамент прозрачности кода — и ваш код станет чище, а команда — эффективнее.

2. DTO-first API: безопасность, прозрачность, удобство

2.1. Почему DTO-first?

- Безопасность: наружу никогда не уходит entity, только DTO. Даже если в entity появится новое поле (например, “isAdmin”), оно не “утечёт” наружу случайно.

- Явная структура: фронтенд и документация всегда знают, что вернёт API. Swagger всегда актуален.

- Гибкость: можно легко менять структуру ответа, не трогая базу. Например, добавить computed-поле или убрать лишнее.

2.2. Пример DTO для пользователя

// src/modules/users/dto/user-response.dto.ts import { ApiProperty } from '@nestjs/swagger';

export class UserResponseDto { @ApiProperty({ example: 1 }) id: number;

@ApiProperty({ example: 'user123' }) username: string; }

В сервисе:
async findAll(): Promise<UserResponseDto[]> { const users = await this.usersRepository.find(); return users.map(({ password, ...user }) => user as UserResponseDto); }

Примечание:

Пароль никогда не попадёт наружу, даже если кто-то забудет про exclude

DTO для параметров пагинации:

// src/shared/dto/paginate.dto.ts import { ApiPropertyOptional } from '@nestjs/swagger'; import { Type } from 'class-transformer'; import { IsPositive, Min } from 'class-validator';

export class PaginateDto { @ApiPropertyOptional({ example: 1, default: 1 }) @Type(() => Number) @IsPositive() page?: number = 1;

@ApiPropertyOptional({ example: 10, default: 10 }) @Type(() => Number) @Min(1) limit?: number = 10; }

DTO для результата пагинации:
// src/shared/dto/paginated-result.dto.ts export interface PaginatedResult<T> { items: T[]; total: number; page: number; limit: number; }

Использование в сервисе:
async findAllPaginated(page = 1, limit = 10): Promise<PaginatedResult<UserResponseDto>> { const [items, total] = await this.usersRepository.findAndCount({ skip: (page - 1) * limit, take: limit, order: { id: 'ASC' }, }); return { items: items.map(({ password, ...user }) => user as UserResponseDto), total, page, limit, }; }

Примечание: Пагинация становится стандартной и одинаковой для всех сущностей. Фронт всегда знает, что ожидать.

Вот расширенная и более глубокая версия главы о логировании, с примерами, практическими советами и акцентом на инженерную культуру:

---

3. Логирование: не только для дебага

Логирование — это не типа “выводить что-то в консоль”, чтобы отловить баг. Это полноценный инструмент управления проектом, который помогает видеть невидимое, анализировать поведение системы и принимать обоснованные решения.

Почему логирование — это важно

- Аудит: Логи фиксируют все значимые действия в системе — кто, когда и что сделал. Это важно для расследования инцидентов, анализа истории изменений и соответствия требованиям безопасности.

- Поиск и устранение ошибок: Хорошо структурированные логи позволяют быстро находить причину сбоя, даже если ошибка проявилась не сразу.

- Мониторинг и алерты: Логи — основа для систем мониторинга (например, Sentry, ELK, Prometheus), которые могут автоматически оповестить команду о критических ошибках или аномалиях.

- Аналитика и оптимизация: По логам можно анализировать производительность, выявлять узкие места, отслеживать частоту и причины ошибок, строить отчёты по бизнес-событиям.

Практика: как мы логируем

- Используем встроенный `Logger` из `@nestjs/common` — он интегрируется с экосистемой NestJS, поддерживает уровни логирования (log, error, warn, debug, verbose) и легко расширяется.

- Логируем не только ошибки, но и ключевые бизнес-события: создание пользователя, запуск важной задачи, смена статуса заказа и т.д.

- В фильтрах ошибок обязательно логируем stack trace — это ускоряет диагностику и помогает понять, где именно произошёл сбой.

- Для сложных сценариев используем контекст (context) — чтобы в логах всегда было понятно, из какого модуля или сервиса пришло сообщение.

Пример:
import { Logger } from '@nestjs/common';

@Injectable() export class UsersService { private readonly logger = new Logger(UsersService.name);

async create(username: string, password: string): Promise<UserResponseDto> { this.logger.log(`Создание пользователя: ${username}`); try { // ... логика создания пользователя ... this.logger.log(`Пользователь успешно создан: ${username}`); } catch (error) { this.logger.error(`Ошибка при создании пользователя: ${username}`, error.stack); throw error; } } }

Советы и best practices

- Стандартизируйте формат логов: Используйте единый стиль сообщений, чтобы их было легко парсить и анализировать.

- Не логируйте чувствительные данные: Никогда не пишите в логи пароли, токены, персональные данные пользователей.

- Используйте уровни логирования: Для обычных событий — `log`, для подозрительных — `warn`, для ошибок — `error`, для отладки — `debug`.

- Интегрируйте логи с внешними системами: Используйте централизованные системы сбора логов (например, ELK, Graylog, Sentry), чтобы не терять важную информацию и быстро реагировать на инциденты.

- Добавляйте контекст: Указывайте, из какого модуля, сервиса или запроса пришёл лог — это ускоряет поиск нужной информации.

Логирование — не “дополнительная опция”, а неотъемлемая часть зрелого backend-проекта. Грамотно выстроенная система логов превращает хаос в управляемую систему, помогает команде быстрее реагировать на проблемы, анализировать поведение пользователей и строить действительно надёжные сервисы.

Инвестируйте время в логи — и они не раз спасут ваш проект.

Вот более развернутая, строгая и профессионально оформленная версия раздела о валидации и обработке ошибок, с акцентом на инженерную культуру и безопасность:

---

4. Валидация и обработка ошибок: доверяй, но проверяй

В современных backend-системах нет места случайностям: каждый входящий запрос проходит строгую валидацию, а любая ошибка обрабатывается так, чтобы обеспечить безопасность пользователя и стабильность всей платформы.

- Валидация данных: Для всех входных DTO мы используем возможности `class-validator`. Это гарантирует, что на уровень бизнес-логики никогда не попадут “грязные” или некорректные данные. Валидация происходит автоматически, а правила описываются декларативно прямо в классах DTO.

Пример DTO с валидацией:
import { IsString, MinLength } from 'class-validator';

export class CreateUserDto { @IsString() username: string;

@IsString() @MinLength(8) password: string; }

Такой подход устраняет ошибки на входе и превращает API в динамично проверяемый и самоописательный интерфейс, правила валидации становятся частью кода и документации одновременно. Это позволяет команде быстро внедрять изменения, интегрироваться без лишних согласований и строить надёжные сервисы с минимальными коммуникационными издержками.

Обработка ошибок: Все ошибки, возникающие в приложении, перехватываются глобальным фильтром.

Мы реализуем собственный фильтр (`HttpExceptionFilter`), который:

- Логирует ошибку и stack trace для последующего анализа.

- Формирует структурированный и предсказуемый ответ для клиента.

- Никогда не раскрывает внутренние детали реализации, стек вызовов или чувствительную информацию наружу.

Пример глобального фильтра ошибок:

@Catch(HttpException) export class HttpExceptionFilter implements ExceptionFilter { private readonly logger = new Logger(HttpExceptionFilter.name);

catch(exception: HttpException, host: ArgumentsHost) { // Логируем ошибку для внутреннего аудита this.logger.error(exception.message, exception.stack);

// Формируем безопасный и понятный ответ для клиента const ctx = host.switchToHttp(); const response = ctx.getResponse<Response>(); const status = exception.getStatus();

response.status(status).json({ statusCode: status, message: exception.message, // Можно добавить поле errors для передачи детальной информации о валидации }); } }

Почему это важно:
Пользователь всегда получает информативный, но безопасный ответ — без “500 Internal Server Error” и загадочных сообщений. Внутри команды мы сохраняем всю необходимую информацию для диагностики и исправления ошибок, не подвергая риску безопасность или приватность данных.

Жёсткая валидация и централизованная обработка ошибок — это не просто “best practice”, а фундамент надёжности, безопасности и предсказуемости вашего backend-приложения.

5. Swagger-документация: всегда актуальна

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

Представьте: новый разработчик приходит в команду и ему нужно разобраться с API. Или клиент хочет интегрироваться с вашим сервисом. Что они видят? Если это куча непонятных эндпоинтов без объяснений - это путь к бесконечным вопросам и ошибкам.

Swagger - это не документация, это ваш способ общения с внешним миром. И как любое общение, оно должно быть понятным и приятным.

Основные принципы

Полная документация: Каждый эндпоинт, DTO и модель должны быть полностью документированы с помощью Swagger-аннотаций
Автоматическая валидация: Документация проверяется автоматически при сборке проекта
Интерактивность: Swagger UI предоставляет возможность тестирования API прямо из браузера
Версионирование: Поддержка версионирования API с отдельной документацией для каждой версии

Как мы это делаем?

1. Пишем документацию как код

Каждый DTO - не просто класс, это история о том, что он делает:

@ApiProperty({ description: 'Идентификатор пользователя в системе', example: '507f1f77bcf86cd799439011', required: true }) userId: string;

Каждый эндпоинт - не просто метод, это инструкция:

@ApiOperation({ summary: 'Создание нового пользователя', description: 'Регистрирует нового пользователя в системе. Требуется подтверждение email.' }) @ApiResponse({ status: 201, description: 'Пользователь успешно создан', type: UserResponseDto })

2. Делаем документацию живой

- Примеры из реальной жизни: вместо абстрактных значений показываем реальные данные

- Ошибки и их решения: описываем успешные сценарии и что делать, если что-то пошло не так

- Секьюрность: объясняем, как работать с авторизацией, какие токены нужны и где их брать

3. Организуем информацию

Представьте, что вы заходите в библиотеку. Книги разложены по полкам, есть указатели, каталоги. Так же и с API:

- Группируем эндпоинты по смыслу (пользователи, платежи, отчеты)
- Добавляем теги для быстрой навигации
- Создаем иерархию: от общего к частному

4. Автоматизируем процесс

Документация - это не разовая акция, а постоянный процесс:

- В CI/CD проверяем, что документация соответствует коду
- При мердж-реквесте автоматически проверяем наличие описаний
- Генерируем клиентские SDK на основе документации

Что получаем в итоге?

1. Для команды:
- Меньше вопросов "а как это работает?"
- Быстрее ввод новых разработчиков
- Меньше ошибок при интеграции
- Понятный интерфейс для тестирования API
- Готовые примеры кода
- Четкое понимание ограничений и возможностей

2. Для бизнеса:
- Меньше времени на поддержку
- Более быстрая интеграция партнеров
- Профессиональный имидж

Советы из практики

1. Пишите для людей:
- Используйте простой язык
- Добавляйте примеры из реальной жизни
- Объясняйте неочевидные моменты

2. Держите в актуальном состоянии:
- Сделайте обновление документации частью процесса разработки
- Проверяйте актуальность при каждом изменении API
- Собирайте обратную связь от пользователей

3. Делайте красиво:
- Добавьте логотип и фирменные цвета
- Структурируйте информацию логично
- Используйте форматирование для лучшей читаемости

Важный совет:

Хорошая документация - это как хороший гид в незнакомом городе. Каждый перекресток (интеграция) снабжен понятными указателями, а все подводные камни (ограничения и особенности) заранее отмечены на карте. Хотите превратить вашу документацию из скучного справочника в увлекательный путеводитель? Стремитесь создавать документацию, которая не просто объясняет, а вдохновляет разработчиков на использование вашего API!

6. Безопасность: не доверяй даже себе

В современной разработке безопасность - это философия, которая должна пронизывать каждый аспект разработки. Давайте поговорим о том, как мы подходим к этому вопросу в нашем проекте.

Основной принцип, которым мы руководствуемся - это принцип минимальных привилегий. Каждый компонент системы должен иметь доступ только к тем ресурсам, которые ему действительно необходимы для работы. Это касается как кода, так и инфраструктуры.

Имея дело с аутентификацией, используй JWT с умом. Токены имеют ограниченное время жизни, регулярно обновляются, а их секреты хранятся в защищённом окружении. Но самое главное - мы никогда не доверяем клиенту полностью. Каждый запрос проходит через строгую валидацию и проверку прав доступа. Работа с паролями - это отдельная история. Мы хешируем их перед сохранением и используем современные алгоритмы с солью и итерациями.

Все секреты, ключи и конфигурации живут только в .env файлах, которые никогда не попадают в репозиторий. Для разработчиков мы предоставляем .env.example с безопасными тестовыми значениями.

Но безопасность - это не только про код. Это про процессы и культуру разработки. Каждый пулл-реквест проходит проверку на безопасность, мы регулярно обновляем зависимости и проводим аудиты. Наши разработчики обучены распознавать потенциальные уязвимости и знают, как их избежать.

Хранение паролей: только хеши, никогда исходные значения

Давайте разберем, как это работает на практике:

@Injectable() export class PasswordService { private readonly SALT_ROUNDS = 12;

async hashPassword(password: string): Promise<string> { // Генерируем уникальную соль для каждого пароля const salt = await bcrypt.genSalt(this.SALT_ROUNDS); // Хешируем пароль с солью return bcrypt.hash(password, salt); }

async verifyPassword(password: string, hash: string): Promise<boolean> { // Сравниваем введенный пароль с хешем из базы return bcrypt.compare(password, hash); } }

Когда пользователь регистрируется, мы сразу хешируем его пароль:

@Injectable() export class AuthService { async register(createUserDto: CreateUserDto) { const hashedPassword = await this.passwordService.hashPassword(createUserDto.password); const user = await this.userRepository.create({ ...createUserDto, password: hashedPassword // Сохраняем только хеш });

// Никогда не возвращаем пароль, даже хешированный const { password, ...safeUser } = user; return safeUser; } }

Этот подход обеспечивает несколько уровней защиты:

1. Даже если злоумышленник получит доступ к базе данных, он не сможет восстановить исходные пароли

2. Использование соли предотвращает атаки с использованием радужных таблиц

3. Современные алгоритмы хеширования:

Argon2 - победитель Password Hashing Competition 2015, предлагающий три варианта:

Argon2d - максимизирует устойчивость к GPU-атакам
Argon2i - оптимизирован для защиты от side-channel атак
Argon2id - гибридный подход, сочетающий преимущества обоих вариантов

scrypt - алгоритм, специально разработанный для противодействия аппаратным атакам, требующий большого объема памяти для вычислений.

PBKDF2 (Password-Based Key Derivation Function 2) - широко используемый стандарт, поддерживающий различные хеш-функции и итерации.

Balloon Hashing - современный алгоритм, использующий псевдослучайные перестановки памяти для создания "вычислительного барьера".

Важно отметить, что мы не только не храним пароли, но и не логируем их ни в каком виде. Даже в случае ошибок аутентификации мы записываем только факт попытки, без каких-либо деталей о введенных данных.

При аутентификации мы сравниваем хеш введенного пароля с хешем в базе:

@Injectable() export class AuthService { async hashPassword(password: string): Promise<string> { const salt = await bcrypt.genSalt(12); return bcrypt.hash(password, salt); }

async validateUser(email: string, password: string) { const user = await this.usersService.findByEmail(email); if (!user) return null; const isValid = await Argon2.verify(user.password, pass); if (!isValid) return null; // Никогда не возвращаем пароль const { password: _, ...safeUser } = user; return safeUser; } }

Этот подход к хранению паролей является отраслевым стандартом и обеспечивает надежную защиту данных пользователей даже в случае компрометации базы данных.

## Защита эндпоинтов

Защищенные маршруты используют кастомные guards и декораторы:

@UseGuards(JwtAuthGuard, RolesGuard) @Roles(UserRole.ADMIN) @Controller('admin') export class AdminController { @Get('users') async getUsers() { // Только админы могут получить доступ } }

Практические рекомендации:

1. Работа с секретами
- Используйте `.env` для всех конфиденциальных данных
- Регулярно ротируйте ключи и пароли
- Храните разные секреты для разных окружений

2. Защита от атак
- Внедрите rate limiting
- Настройте CORS политики
- Используйте helmet для HTTP-заголовков

3. Процессы разработки
- Включайте проверку безопасности в CI/CD
- Проводите регулярные аудиты кода
- Обучайте команду основам безопасностиё

Реальный пример защиты API:

@Controller('api/v1') export class SecureController { @UseGuards(JwtAuthGuard) @UseInterceptors(ClassSerializerInterceptor) @Get('user/profile') async getProfile(@CurrentUser() user: User) { // Сериализуем только безопасные поля return new UserResponseDto(user); }

@UseGuards(RolesGuard) @Roles(UserRole.ADMIN) @Post('admin/users') async createUser(@Body() createUserDto: CreateUserDto) { // Проверяем права и валидируем данные return this.userService.create(createUserDto); } }

Безопасность - это постоянный процесс улучшения и адаптации. не достаточно просто следовать лучшим практикам, следует развивать их и адаптировать под реальные нужды. Каждый день мы учимся чему-то новому и применяем эти знания для защиты наших систем и данных пользователей.

7. Тесты: не только для CI

В современной разработке тестирование эволюционировало из простой проверки кода в мощный инструмент обеспечения качества и надежности системы. Давайте посмотрим, как мы реализуем современный подход к тестированию.

- Для всех сервисов и контроллеров пишем unit- и e2e-тесты.
- Тесты проверяют не только happy path, но и ошибки, edge cases.
- Покрытие тестами — не самоцель, а инструмент уверенности в коде.

Пример современного подхода к написанию тестов:

import { Test, TestingModule } from '@nestjs/testing'; import { faker } from '@faker-js/faker'; import { PrismaService } from '@prisma/client'; import { UserService } from './user.service'; import { createMock } from '@golevelup/ts-jest'; import { mockDeep } from 'jest-mock-extended';

describe('UserService', () => { let service: UserService; let prisma: DeepMockProxy<PrismaService>;

beforeEach(async () => { prisma = mockDeep<PrismaService>(); const module: TestingModule = await Test.createTestingModule({ providers: [ UserService, { provide: PrismaService, useValue: prisma, }, ], }).compile();

service = module.get(UserService); });

it('should create user with valid data', async () => { const userData = { email: faker.internet.email(), password: faker.internet.password({ length: 12 }), };

prisma.user.create.mockResolvedValue({ id: faker.string.uuid(), ...userData, createdAt: faker.date.past(), updatedAt: faker.date.recent(), });

const result = await service.create(userData); expect(result).toMatchObject({ email: userData.email, }); expect(result.password).toBeUndefined(); }); });

Интеграция с CI/CD

# .github/workflows/test.yml name: Modern Test Pipeline on: [push, pull_request]

jobs: test: runs-on: ubuntu-latest strategy: matrix: node-version: [18.x, 20.x] steps: - uses: actions/checkout@v3 - name: Use Node.js ${{ matrix.node-version }} uses: actions/setup-node@v3 with: node-version: ${{ matrix.node-version }} cache: 'npm' - name: Install dependencies run: npm ci - name: Run unit tests run: npm run test:unit env: NODE_ENV: test - name: Run e2e tests run: npm run test:e2e env: NODE_ENV: test TEST_DATABASE_URL: ${{ secrets.TEST_DATABASE_URL }} - name: Run mutation tests run: npm run test:mutation - name: Upload coverage uses: codecov/codecov-action@v3 with: token: ${{ secrets.CODECOV_TOKEN }} - name: Performance test run: npm run test:performance

Современное тестирование - это комплексный подход к обеспечению качества, включающий:
- Автоматизированное тестирование на разных уровнях
- Мониторинг производительности
- Проверку контрактов API
- Тестиование мутаций
- Интеграцию с современными инструментами CI/CD

Это позволяет находить ошибки и предотвращать их появление, обеспечивая высокое качество кода и надежность системы.

8. Docker и окружение: dev ≠ prod

8.1. Три контура — dev, stage, prod

Используем default + три docker-compose файла:

docker-compose.yml — базовый, описывает сервисы.

docker-compose.dev.yml — dev-override: монтирует исходники, пробрасывает порты, использует dev-окружение.

docker-compose.stage.yml и `docker-compose.prod.yml` — для stage и prod, с разными портами, переменными, настройками безопасности.

Пример:
# docker-compose.yml services: app: build: context: . dockerfile: Dockerfile depends_on: - db networks: - gprod-network db: image: postgres:13 volumes: - pgdata:/var/lib/postgresql/data networks: - gprod-network

volumes: pgdata:

networks: gprod-network: driver: bridge

# docker-compose.dev.yml services: app: env_file: - .env environment: - NODE_ENV=development - DATABASE_HOST=db - DATABASE_PORT=5432 - DATABASE_USER=${DEV_DATABASE_USER} - DATABASE_PASSWORD=${DEV_DATABASE_PASSWORD} - DATABASE_NAME=${DEV_DATABASE_NAME} - JWT_SECRET=${DEV_JWT_SECRET} ports: - "3000:3000" volumes: - .:/app - /app/node_modules depends_on: - db networks: - gprod-network

db: image: postgres:13 environment: - POSTGRES_USER=${DEV_DATABASE_USER} - POSTGRES_PASSWORD=${DEV_DATABASE_PASSWORD} - POSTGRES_DB=${DEV_DATABASE_NAME} ports: - "5432:5432" networks: - gprod-network

Пояснение: - Для каждого окружения свои переменные, свои порты, свои тома.
- В dev-контуре код монтируется внутрь контейнера для hot-reload.
- В prod — только собранный dist, никакого доступа к исходникам.

8.2. Работа с переменными окружения

- Используем утилиту getEnvVar для гибкой работы с переменными окружения с учётом контура (dev, stage, prod).

- Все секреты и ключи — только в .env, не коммитим в репозиторий.

Пример:

export function getEnvVar(configService: ConfigService, key: string, fallback?: string) { let env = (configService.get<string>('NODE_ENV') || process.env.NODE_ENV || 'development').toLowerCase(); if (env.startsWith('dev')) env = 'dev'; else if (env.startsWith('prod')) env = 'prod'; else if (env.startsWith('stag')) env = 'stage'; env = env.toUpperCase(); return ( configService.get<string>(`${env}_${key}`) || configService.get<string>(key) || fallback ); }

Это позволяет легко деплоить один и тот же код в разные окружения без правок.

Health-check и базовые контроллеры

- В проекте реализованы базовые контроллеры (например, app.controller.ts) для проверки работоспособности сервиса.

- DTO даже для простых ответов (например, HelloResponse) — это удобно для автотестов, мониторинга и Swagger.

9. Пошаговый чек-лист для внедрения best practices

1. Везде используем DTO, entity наружу не возвращаем.** 2. Пагинация и идентификаторы — только через shared/dto.** 3. Логирование — через Logger, логируем всё важное.** 4. Валидация — через class-validator, ошибки — через фильтр.** 5. Swagger — для всех DTO и эндпоинтов.** 6. Безопасность — не возвращаем пароли, используем guards.** 7. Тесты — для всего, что может сломаться.** 8. Docker — для всех окружений, переменные — через .env.** 9. Рефакторинг — всё общее в shared, всё техническое в common.** 10. Проверяем, что проект собирается, тесты проходят, Swagger актуален.** 11. Health-check эндпоинты — для мониторинга и CI/CD.** 12. Паттерн “конструктор с partial” — для entity.** 13. Гибкая работа с конфигами через ConfigService и утилиты.**

---

Бонус: советы из реального опыта

- Не бойтесь удалять и переписывать код. Лучший код — тот, который легко удалить или заменить.

- Документируйте не только API, но и архитектурные решения. Почему выбрали именно такой подход? Это поможет новичкам и будущим вам.

- Внедряйте CI/CD с самого начала. Даже простая проверка тестов и линтера в pull request спасёт от многих багов.

- Общайтесь с командой. Лучшие архитектурные решения рождаются в диалоге.

- Не забывайте про мониторинг и алерты. Логирование — это хорошо, но оповещения о сбоях — ещё лучше.

Финал

Мы построили backend, который:
- легко поддерживать и расширять,
- безопасен и прозрачен для команды,
- удобен для фронта и мобильных приложений,
- легко масштабируется и деплоится в любое окружение.

Этот опыт — результат десятков итераций, исправления ошибок, внедрения best practices и постоянного рефакторинга. Следуйте этим принципам — и ваш проект будет радовать и команду, и бизнес!

Добро пожаловать в будущее !