Архитектурная доктрина для NestJS-проектов: разбор типовых сценариев деградации кодовой базы и структурные ограничения, обеспечивающие её отсутствие при росте функционала. Навигация по серии:
Часть 1. Эволюция NestJS-приложения в неподдерживаемое состояние
Часть 2. Декомпозиция на сервисы: анализ ограниченности подхода
Часть 3. Архитектурный риск циклов в NestJS: ROI решений на горизонте пяти лет
Часть 4. FBCA: формализация границ ответственности в NestJS-модуле
Часть 5. Масштабирование FBCA и теоретико-графовый анализ зависимостей
Эта статья — разбор того, как типичный бэкенд на NestJS деградирует с ростом функционала и как идеи Clean Architecture позволяют этого избежать. Я пройду по полному циклу: покажу на примере «до и после», как feature-based-структура, которую сегодня продвигают как стандарт, теряет управляемость с масштабом; разберу типичные сценарии деградации; оценю в деньгах и человеко-часах, во что они обходятся бизнесу; объясню, почему именно такая кодовая база заставляет команды дробить монолит на микросервисы задолго до того, как это оправдано. После этого я предложу подход, направленный против деградации, — и приведу для него формальное математическое обоснование. К концу статьи у вас будет и аргументация, и инструменты, чтобы применить этот подход к своим системам.
В качестве сквозного примера возьмём задачу, которую разбирают на System Design-собеседованиях из раза в раз: бэкенд для сервиса класса Twitter. Минимальный набор инструментов очевиден — база данных и приложение. Вопросы предельной производительности, шардирования и горизонтального масштабирования мы сознательно вынесем за скобки: статья про структуру кода, а не про пропускную способность. Стек зафиксируем сразу — Node.js и фреймворк NestJS. Начнём с того, что выпишем функциональные требования к системе.
Регистрация и авторизация
Создание твита
Лента (feed)
Подписки (follow / unfollow)
Профиль пользователя
Лайки
Ретвиты
Комментарии (replies)
Поиск (пользователей, твитов, хэштегов)
Уведомления (лайки, подписки, ответы)
Медиа (изображения / видео)
Очевидно, что реальный Twitter устроен на порядок сложнее и строился годами командой в сотни инженеров — но цель статьи не в том, чтобы воспроизвести продукт, а в том, чтобы рассмотреть архитектурную эволюцию на знакомой предметной области. Список фич зафиксирован, схема базы и набор эндпоинтов на этом этапе вырисовываются практически без раздумий, стек выбран. Открываем документацию NestJS — и с первой же страницы документация предлагает нам опорную структуру проекта.
src/
├── main.ts
├── app.module.ts
│
├── modules/
│ ├── auth/
│ ├── users/
│ ├── tweets/
│ ├── feed/
│ ├── likes/
│ ├── comments/
│ ├── retweets/
│ ├── follows/
│ ├── notifications/
│ ├── search/
│ └── media/
│
├── common/
│ ├── guards/
│ ├── interceptors/
│ ├── filters/
│ ├── decorators/
│ └── utils/
│
├── database/
│ ├── prisma/ или typeorm/
│ └── migrations/
│
├── config/
│ └── configuration.ts
Помимо структуры верхнего уровня, документация описывает и рекомендованный состав одного модуля — какие файлы и в каком порядке имеет смысл создавать. Эта рекомендация одинакова для модулей с разной природой: и auth, и tweets, и search собираются по одному и тому же шаблону. Покажу на примере модуля tweets:
src/modules/tweets/
├── tweets.module.ts
├── tweets.controller.ts
├── tweets.service.ts
├── dto/
│ └── create-tweet.dto.ts
├── entities/
│ └── tweet.entity.ts
На первый взгляд схема выглядит аккуратно: ясное разделение, очевидные правила размещения, низкий порог входа для нового разработчика. На практике же — без дополнительной архитектурной дисциплины — она через полгода превращается в трудно поддерживаемый код. Дальше мы увидим, как именно: шаг за шагом, через последовательность локально разумных решений. Начнём с модуля, который есть почти в любом продукте — пользователи и авторизация.
Минимально необходимый функционал: две ручки — регистрация и вход.
@Controller("auth")
export class AuthController {
constructor(private readonly authService: AuthService) {}
@Post("sign-up")
async signUp(@Body() dto: SignUpDto): Promise<SignUpResponse> {
return this.authService.signUp(dto.email, dto.password);
}
@Post("sign-in")
async signIn(@Body() dto: SignInDto): Promise<SignInResponse> {
return this.authService.signIn(dto.email, dto.password);
}
}
В качестве ORM по ходу статьи будем использовать TypeORM — выбор не принципиален для разговора об архитектуре, и всё, что ниже, легко переносится на Prisma, MikroORM или Drizzle. Просто нужен инструмент, на котором удобно показывать запросы. Сначала опишем сущность пользователя.
@Entity("users")
export class User {
@PrimaryGeneratedColumn("uuid")
id: string;
@Column({ unique: true })
email: string;
@Column()
password: string;
@CreateDateColumn()
createdAt: Date;
}
Согласно принятой структуре, код, относящийся к работе с пользователями, должен жить в src/modules/users. Значит, и логика создания записи о пользователе в базе данных формально принадлежит этому модулю. Это уже неплохая дисциплина — лучше, чем вставлять SQL-запросы прямо в AuthService. Но в этой точке у разработчика реально два варианта: обращаться к репозиторию пользователей напрямую из AuthService или ходить через UsersService. На маленьком масштабе оба варианта работают и оба проходят ревью — поэтому сначала рассмотрим их рядом.
@Injectable()
export class AuthService {
constructor(
@InjectRepository(User)
private readonly usersRepository: Repository<User>,
) {}
async signUp(email: string, password: string) {
const existing = await this.usersRepository.findOne({
where: { email },
});
if (existing) {
throw new Error("User already exists");
}
const user = this.usersRepository.create({
email,
password,
});
await this.usersRepository.save(user);
return {
id: user.id,
email: user.email,
};
}
async signIn(email: string, password: string) {
const user = await this.usersRepository.findOne({
where: { email },
});
if (!user) {
throw new UnauthorizedException("Invalid credentials");
}
if (user.password !== password) {
throw new UnauthorizedException("Invalid credentials");
}
return {
id: user.id,
email: user.email,
};
}
}
Обращаемся через сервис
import { Injectable, UnauthorizedException } from "@nestjs/common";
import { UsersService } from "../users/users.service";
@Injectable()
export class AuthService {
constructor(private readonly usersService: UsersService) {}
async signUp(email: string, password: string) {
const existing = await this.usersService.findByEmail(email);
if (existing) {
throw new Error("User already exists");
}
const user = await this.usersService.create({
email,
password,
});
return {
id: user.id,
email: user.email,
};
}
async signIn(email: string, password: string) {
const user = await this.usersService.findByEmail(email);
if (!user) {
throw new UnauthorizedException("Invalid credentials");
}
if (user.password !== password) {
throw new UnauthorizedException("Invalid credentials");
}
return {
id: user.id,
email: user.email,
};
}
}
На текущем масштабе оба подхода выглядят равноправными, и в этом и состоит главная ловушка: правильный выбор сейчас определяется не тем, как код смотрится в момент написания, а тем, что произойдёт с ним через год. Поэтому давайте сразу промотаем время вперёд — представим, что прошло около года активной разработки. Продукт нашёл аудиторию, пользователей стало много, а вместе с ними пришли и те, кто пытается абьюзить регистрацию. Маркетинг требует фиксировать источники трафика и проводить A/B-тесты на пользователях. Появилась многоуровневая реферальная система с бонусами и лимитами. Модуль users оброс собственными эндпоинтами и новыми полями — словом, всё то, что в любом продукте происходит ровно тогда, когда он начинает приносить деньги.
Зафиксируем конкретно, к какому списку требований нужно теперь адаптировать AuthService:
Реферальная система с проверками и ограничениями: лимиты на приглашения, защита от self-referral, защита от повторных приглашений того же email
Усложнившаяся регистрация с анти-абьюз-проверками — по IP, по
deviceId, по факту повторной регистрации с того же устройстваРасширившийся модуль
users— новые поля (источник трафика,deviceId, флаги верификации), отдельные эндпоинты, собственные сценарииТребования маркетинга — аналитика регистраций, A/B-тесты, фиксация источников трафика, экспорт событий
Оговорка о транзакциях. В продакшене регистрация требует идемпотентности, защиты от гонок и аккуратной транзакционной разбивки. В примерах статьи всё это сознательно опущено — речь о декомпозиции, а не транзакционности. И сразу оговорим, чтобы не ловить вопрос: «считать всё это одной большой транзакцией» — тоже неверный default. Длинный транзакционный блок с походом во внешнюю аналитику, бонусами и пересчётом счётчиков будет держать строки заблокированными секундами и под нагрузкой роняет базу. Корректная транзакционная разбивка — это отдельная задача, выходящая за рамки статьи.
AuthService.signUp V2
async signUp(
email: string,
password: string,
referralCode?: string,
adSourceCode?: string,
ip?: string,
deviceId?: string,
): Promise<SignUpResponse> {
const existingUserByEmail = await this.usersRepository.findOne({
where: { email },
});
if (existingUserByEmail) {
throw new BadRequestException("User already exists");
}
const registrationsFromIp = await this.usersRepository.count({
where: { registrationIp: ip },
});
if (registrationsFromIp > 5) {
throw new BadRequestException("Too many registrations from this IP");
}
const existingUserByDevice = await this.usersRepository.findOne({
where: { deviceId },
});
if (existingUserByDevice) {
throw new BadRequestException("Device already used");
}
const adSource = adSourceCode
? await this.adSourceRepository.findOne({ where: { code: adSourceCode } })
: null;
if (adSourceCode && !adSource) {
throw new BadRequestException("Invalid ad source");
}
if (adSource) {
const experimentGroup = Math.random() > 0.5 ? "A" : "B";
await this.adSourceRepository.increment(
{ id: adSource.id },
"registrationsCount",
1,
);
await this.analyticsRepository.save({
type: "experiment_assignment",
group: experimentGroup,
source: adSource.code,
});
}
const referral = referralCode
? await this.referralsRepository.findOne({
where: { code: referralCode },
relations: ["owner"],
})
: null;
if (referralCode && !referral) {
throw new BadRequestException("Invalid referral code");
}
const referredByUser = referral?.owner ?? null;
if (referredByUser) {
const referralsByOwnerCount = await this.referralsRepository.count({
where: { owner: { id: referredByUser.id } },
});
if (referralsByOwnerCount > 10) {
throw new BadRequestException("Referral limit exceeded");
}
const existingReferralForEmail = await this.referralsRepository.findOne({
where: {
owner: { id: referredByUser.id },
invitedUser: { email },
},
relations: ["invitedUser"],
});
if (existingReferralForEmail) {
throw new BadRequestException("Referral abuse detected");
}
if (referredByUser.email === email) {
throw new BadRequestException("Self-referral not allowed");
}
}
const newUser = this.usersRepository.create({
email,
password,
adSource,
registrationIp: ip,
deviceId,
isVerified: false,
});
await this.usersRepository.save(newUser);
if (referredByUser) {
await this.bonusRepository.save({
userId: referredByUser.id,
amount: 100,
type: "referral_reward",
});
const parentReferral = await this.referralsRepository.findOne({
where: { invitedUser: { id: referredByUser.id } },
relations: ["owner"],
});
if (parentReferral) {
await this.bonusRepository.save({
userId: parentReferral.owner.id,
amount: 50,
type: "second_level_referral",
});
}
await this.referralsRepository.save({
owner: referredByUser,
invitedUser: newUser,
});
}
await this.analyticsRepository.save({
type: "user_registered",
userId: newUser.id,
source: adSource?.code,
ip,
});
return {
id: newUser.id,
email: newUser.email,
};
}
На этом месте сторонник такого кода скажет: «Ну и что? Всё работает, бизнес-сценарий покрыт целиком, один метод честно проводит регистрацию от начала и до конца». И формально это правда. Но если присмотреться к тому, что именно лежит внутри signUp, картина другая: одна функция теперь одновременно занимается аутентификацией, анти-фрод-логикой, маркетинговыми экспериментами, реферальной механикой и аналитикой. Она зависит от пяти разных репозиториев и от четырёх независимых доменов бизнеса. И вот это — а не количество строк — настоящая проблема. Через ещё один продуктовый квартал любая новая фича — антибот, гео-таргетинг, верификация email — будет шиться в это же место, потому что «все требования к регистрации живут в signUp».
V2 пошла в прод и сделала то, что V1 не могла. Рефералка начала приводить трафик дешевле платной рекламы, инфлюенсеры это заметили и сами начали стучаться с предложениями. В дашбордах продакта и финансов цифры впервые за долгое время оказались зелёными в одном и том же квартале. Проект жив, проект растёт, проект зарабатывает.
Продакты ловят волну и начинают подгонять: «парни, рынок открылся, давайте быстрее, конкуренты не спят». В этот момент в команде находится тот, кто эту волну ловит ещё и лично. Складывает у себя в голове: фича большая, заметная, как раз перед performance review; если выкатить первым и без багов — можно идти к менеджеру и просить тимлид-грейд, можно начать ходить на бизнес-встречи, стать тем самым инженером, к которому продакт сначала идёт спросить, а уже потом пишет пользовательскую историю. Стимул понятный, человеческий — не плохой и не хороший, просто реальный.
На стол лёг следующий пакет «давно собирались». Партнёрская программа с блогерами и стримерами. Разные модели монетизации — revenue share, бонусы, уровни. Анти-фрод посерьёзнее, с несколькими сценариями и скорингом. Расширенная аналитика по маркетингу, продукту и финансам. И ещё дополнительные проверки и ограничения для рефералок. Каждый пункт сам по себе нормальный — ровно та же логика, только чуть больше сценариев.
Наш герой открывает auth.service.ts и продумывает самый быстрый путь — всё в один сервис, без лишних рефакторингов, без споров на ревью, к пятнице деплой. И вот ровно эта комбинация — успех продукта, давление продактов, личная мотивация одного инженера и пятничный дедлайн — раз за разом производит на свет один и тот же класс кода. Если вы работали в продукте, который перешёл из MVP в рост, вы эту сцену видели хотя бы раз. Сейчас увидите её ещё раз — и в подробностях.
Прежде чем смотреть, что в итоге окажется в auth.service.ts, зафиксируем, что формально лежит в ТЗ к этому этапу:
Партнёрская программа с блогерами и стримерами — отдельные категории партнёров, верификация, отдельные статусы и переходы между ними
Расширенная модель монетизации — revenue share, многоуровневые бонусы, уровни партнёрства, разные правила начисления для разных категорий
Усложнённый анти-фрод — несколько сценариев (новый пользователь, рефералка, партнёрский клик), скоринговая модель, ручные блокировки
Расширенная аналитика — отдельные слои данных для маркетинга, продукта и финансов; экспорт событий во внешние системы
Дополнительные проверки и ограничения для рефералок — лимиты по времени, по сегментам пользователей, по источникам трафика
Каждый пункт — обычный продуктовый запрос: ничего экзотического, ничего архитектурно-провокационного. Их и реализуют как обычные продуктовые запросы.
AuthService.signUp V3
async signUp(
email: string,
password: string,
referralCode?: string,
adSourceCode?: string,
ip?: string,
deviceId?: string,
): Promise<SignUpResponse> {
const existingUserByEmail = await this.usersRepository.findOne({
where: { email },
});
if (existingUserByEmail) {
throw new BadRequestException("User already exists");
}
const registrationsFromIp = await this.usersRepository.count({
where: { registrationIp: ip },
});
if (registrationsFromIp > 5) {
throw new BadRequestException("Too many registrations from this IP");
}
const existingUserByDevice = await this.usersRepository.findOne({
where: { deviceId },
});
if (existingUserByDevice) {
throw new BadRequestException("Device already used");
}
const fraudScore =
(registrationsFromIp ?? 0) * 10 +
(existingUserByDevice ? 50 : 0) +
(ip?.startsWith("192.") ? 20 : 0);
if (fraudScore > 70) {
throw new BadRequestException("Fraud detected");
}
const adSource = adSourceCode
? await this.adSourceRepository.findOne({ where: { code: adSourceCode } })
: null;
if (adSourceCode && !adSource) {
throw new BadRequestException("Invalid ad source");
}
if (adSource) {
const experimentGroup = Math.random() > 0.5 ? "A" : "B";
await this.adSourceRepository.increment(
{ id: adSource.id },
"registrationsCount",
1,
);
await this.analyticsRepository.save({
type: "experiment_assignment",
group: experimentGroup,
source: adSource.code,
});
}
const referral = referralCode
? await this.referralsRepository.findOne({
where: { code: referralCode },
relations: ["owner", "influencerPartner"],
})
: null;
if (referralCode && !referral) {
throw new BadRequestException("Invalid referral code");
}
const influencerPartner = referral?.influencerPartner ?? null;
const referredByUser =
referral && !influencerPartner ? referral.owner : null;
let calculatedReward = 0;
if (influencerPartner) {
await this.partnerRepository.increment(
{ id: influencerPartner.id },
"registrationsCount",
1,
);
if (influencerPartner.type === "blogger") {
const audienceSize = influencerPartner.audienceSize ?? 1000;
const ctr = influencerPartner.ctr ?? 0.02;
const engagementScore = audienceSize * ctr;
calculatedReward =
20 + engagementScore * 0.01 + (engagementScore > 1000 ? 50 : 0);
if (engagementScore > 5000) {
calculatedReward *= 1.5;
}
} else if (influencerPartner.type === "streamer") {
const avgViewers = influencerPartner.avgViewers ?? 100;
const streamHours = influencerPartner.streamHours ?? 2;
const retentionFactor = Math.min(streamHours / 4, 1);
calculatedReward =
avgViewers * 0.5 * retentionFactor + (avgViewers > 1000 ? 100 : 0);
if (streamHours > 6) {
calculatedReward *= 1.2;
}
} else if (influencerPartner.type === "partner") {
const revenueShare = influencerPartner.revenueShare ?? 0.1;
const baseValue = influencerPartner.baseValue ?? 200;
const tierMultiplier =
influencerPartner.tier === "gold"
? 2
: influencerPartner.tier === "silver"
? 1.5
: 1;
calculatedReward = baseValue * revenueShare * tierMultiplier;
if (influencerPartner.kpiAchieved) {
calculatedReward += 300;
}
}
await this.analyticsRepository.save({
type: "marketing_conversion",
source: influencerPartner.type,
reward: calculatedReward,
});
await this.analyticsRepository.save({
type: "revenue_projection",
expectedRevenue: calculatedReward * 10,
});
await this.analyticsRepository.save({
type: "user_segment",
segment:
influencerPartner.type === "streamer" ? "gamers" : "general",
});
}
if (referredByUser) {
const referralsByOwnerCount = await this.referralsRepository.count({
where: { owner: { id: referredByUser.id } },
});
if (referralsByOwnerCount > 10) {
throw new BadRequestException("Referral limit exceeded");
}
const existingReferralForEmail = await this.referralsRepository.findOne({
where: {
owner: { id: referredByUser.id },
invitedUser: { email },
},
relations: ["invitedUser"],
});
if (existingReferralForEmail) {
throw new BadRequestException("Referral abuse detected");
}
if (referredByUser.email === email) {
throw new BadRequestException("Self-referral not allowed");
}
}
const newUser = this.usersRepository.create({
email,
password,
adSource,
registrationIp: ip,
deviceId,
isVerified: false,
});
await this.usersRepository.save(newUser);
if (referredByUser) {
await this.bonusRepository.save({
userId: referredByUser.id,
amount: 100,
type: "referral_reward",
});
const parentReferral = await this.referralsRepository.findOne({
where: { invitedUser: { id: referredByUser.id } },
relations: ["owner"],
});
if (parentReferral) {
await this.bonusRepository.save({
userId: parentReferral.owner.id,
amount: 50,
type: "second_level_referral",
});
}
await this.referralsRepository.save({
owner: referredByUser,
invitedUser: newUser,
});
}
if (influencerPartner) {
const partnerOwner = await this.usersRepository.findOne({
where: { id: influencerPartner.ownerUserId },
});
if (partnerOwner) {
await this.bonusRepository.save({
userId: partnerOwner.id,
amount: calculatedReward,
type: "influencer_reward",
});
await this.analyticsRepository.save({
type: "influencer_reward_paid",
partnerId: influencerPartner.id,
amount: calculatedReward,
});
}
}
await this.analyticsRepository.save({
type: "user_registered",
userId: newUser.id,
source: adSource?.code,
ip,
});
return {
id: newUser.id,
email: newUser.email,
};
}
Это случай, в котором не требуется отдельной аргументации, чтобы признать качество кода неудовлетворительным — структурные проблемы видны невооружённым глазом. Двести строк в одной функции, шесть параметров на входе, три ветки реферальной логики, три модели вознаграждения партнёров; за каждой условной строкой — отдельный бизнес-сценарий, и совокупно держать их в голове не способен ни один разработчик, кроме автора. Стоит подчеркнуть, что в этом коде намеренно опущены транзакционность, идемпотентность, валидация инвариантов, единая обработка ошибок и согласованные коды ответа: их добавление сделало бы пример нечитаемым, а ситуацию — только более характерной.
На этом месте у читателя возникает естественная мысль: «Хорошо, причина понятна — AuthService держит логику нескольких независимых доменов в одном методе. Значит, нужно завести UsersService, ReferralsService, MarketingService, FraudService, PartnerService и разнести по ним всю логику signUp по принципу один сервис — один домен; AuthService останется только оркестратором». Этот ответ — стандартная рекомендация NestJS-сообщества и буквально первый совет на любом ревью такого кода. Он звучит правильно, выглядит правильно и в моменте действительно даёт видимое улучшение.
Только проблему он не решает. И в следующей части мы пройдём по такому рефакторингу шаг за шагом и увидим, почему правильно разнести по сервисам — это не просто переложить вызовы из одного места в другое, и любой проект, в котором за «декомпозицией на сервисы» нет архитектурного правила, через тот же год снова окажется ровно в той же точке, только с другим набором имён файлов.