Node.js & NestJS

Если вы пришли из PHP, самое важное отличие Node не в синтаксисе и не в пакетах. Оно в том, кто живёт между запросами. В привычной связке Nginx и PHP-FPM на каждый запрос берётся отдельный процесс-воркер: он поднимает фреймворк, собирает ответ, отдаёт его и умирает. Всё, что он успел положить в переменные, исчезает вместе с ним — именно поэтому в Laravel вы не задумываетесь, не утечёт ли память и не увидит ли следующий посетитель чужие данные. Каждый запрос начинается с чистого листа.

Node устроен наоборот. Процесс запускается один раз и дальше работает неделями, обслуживая все запросы подряд. Ваш файл выполняется не на каждый запрос, а однократно при старте — он лишь расставляет обработчики и говорит: «вот что делать, когда придёт событие». После этого управление уходит в бесконечный цикл, который принимает события и вызывает ваши функции. Код внутри этих функций выполняется в одном-единственном потоке.

Из этих двух абзацев вырастает всё остальное в разделе, поэтому к ним стоит возвращаться. Разберём, что именно следует.

Команда node app.js запускает процесс операционной системы, внутри которого поднимаются две части рантайма: V8 — тот самый движок из Chrome, он исполняет ваш JavaScript, и libuv — библиотека на C, которая умеет работать с сетью, файлами и таймерами, не блокируя поток. Дальше Node выполняет служебную подготовку, загружает ваш файл и проходит его сверху вниз ровно один раз.

Вот место, где у людей из мира PHP чаще всего ломается модель. Строка app.listen(3000) не начинает обрабатывать запросы и не блокирует программу — она лишь регистрирует намерение и немедленно возвращает управление. Когда ваш файл дочитан до конца, Node переходит в цикл ожидания событий, и только там начинается настоящая работа. Поэтому код, написанный «после сервера», выполнится сразу же, а не после первого запроса.

Отсюда же ответ на вопрос «почему мой скрипт не завершается». Пока у libuv есть хотя бы одно незакрытое дело — слушающий сокет, живой интервал, незавершённый запрос — цикл продолжает работать. Как только их не остаётся, процесс выходит самостоятельно, без всякого exit.

В Laravel путь запроса понятен и неизменен: public/index.php поднимает приложение через bootstrap/app.php, создаётся ядро, и Kernel::handle($request) прогоняет запрос через конвейер middleware к контроллеру. Этот путь повторяется для каждого запроса с самого начала.

В Node ядра в этом смысле нет. Роль диспетчера играет цикл ожидания событий: он получает событие «пришёл HTTP-запрос» и вызывает ту функцию, которую вы зарегистрировали при старте. Разница в том, что конвейер Laravel собирается заново на каждый запрос, а цикл поднимается однажды и живёт, пока жив процесс.

Node.js — это среда выполнения (runtime) для JavaScript вне браузера. Язык остался тот же самый — JavaScript. Изменилось окружение: вместо DOM, window и запросов к серверу появились файловая система, сеть, процессы и всё, что нужно серверной программе.

# macOS — через Homebrew, стандартный путь
brew install node              # последняя версия
brew install node@22           # конкретная major-версия

# Windows
winget install OpenJS.NodeJS.LTS
# либо .msi-установщик с nodejs.org

# Ubuntu/Debian — в репозитории обычно устаревшая версия,
# поэтому ставят из NodeSource
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Проверка — npm ставится вместе с Node
node --version
npm --version

На разных проектах нужны разные версии Node. Менеджер версий держит их рядом и переключает одной командой — примерно как brew link для PHP.

# nvm — самый распространённый (macOS, Linux)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

nvm install --lts      # поставить последнюю LTS
nvm install 22         # конкретную major
nvm use 22             # переключиться
nvm ls                 # что установлено
nvm alias default 22   # версия по умолчанию в новых сессиях

# Посмотреть, что внутри именно твоей сборки
node -p "process.versions"

# Пример вывода (Node 25):
# node: '25.2.1', v8: '14.1.146', uv: '1.51.0',
# openssl: '3.6.2', undici: '7.16.0', zlib: '1.2.12', ...

// В PHP безобидно, в Node — утечка и протекание данных
let currentUser;                  // модульная переменная, одна на весь процесс
const cache = new Map();          // растёт бесконечно

export function handler(req, res) {
  currentUser = req.user;          // параллельный запрос перетрёт
  cache.set(req.id, req.body);     // никто никогда не чистит
}

// Состояние запроса живёт в самом запросе
export function handler(req, res) {
  const user = req.user;           // локально, умрёт с вызовом
}

// server.js — всё из коробки, npm install не нужен
import { createServer } from 'node:http';

const server = createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({ ok: true, url: req.url }));
});

server.listen(3000, () => console.log('http://localhost:3000'));

node server.js

В Node 58 встроенных модулей. Подключаются без установки, с префиксом node:.

// Посмотреть полный список
node -p "require('module').builtinModules.join('\n')"

// Маршрут — это URL-шаблон, path тут ни при чём
app.get('/users/:id', (req, res) => {
  res.json({ id: req.params.id });   // '123' из /users/123
});

// Разбор URL — третья вещь, тоже не path
const u = new URL('https://site.com/users/123?tab=posts');
u.pathname;                   // '/users/123' — URL-путь, не файловый
u.searchParams.get('tab');   // 'posts'

Главная задача — кроссплатформенность. В Windows разделитель \, в Linux и macOS — /. Склеивание строк через '/' вручную ломается на Windows.

import path from 'node:path';

path.join('users', 'data', 'file.txt');
// POSIX:   'users/data/file.txt'
// Windows: 'users\data\file.txt'

path.resolve('file.txt');       // абсолютный путь от текущей папки
path.extname('index.html');      // '.html'
path.basename('/foo/baz.txt');   // 'baz.txt'
path.dirname('/foo/baz.txt');    // '/foo'
path.sep;                        // '/' или '\' в зависимости от ОС

path.parse('/home/user/file.txt');
// { root: '/', dir: '/home/user', base: 'file.txt',
//   ext: '.txt', name: 'file' }

import path from 'node:path';

const uploadDir = path.resolve('/var/www/uploads');
const target    = path.resolve(uploadDir, req.query.name);

// так нельзя: '/var/www/uploads-secret/key' тоже начинается с uploadDir
if (target.startsWith(uploadDir)) { /* ... */ }

// правильно: добавляем разделитель, тогда совпадёт только вложенное
if (target.startsWith(uploadDir + path.sep)) {
  // путь точно внутри uploadDir
}

{
  "name": "my-api",
  "type": "module",          // ESM: import/export. Без этого — CommonJS
  "engines": { "node": ">=22" },
  "scripts": {
    "dev":   "node --watch src/main.js",
    "start": "node src/main.js",
    "test":  "node --test"
  },
  "dependencies":    { "@nestjs/core": "^11.0.0" },
  "devDependencies": { "typescript": "^5.7.0" }
}

npm init -y                  # создать package.json
npm install express          # поставить в dependencies
npm install -D typescript    # -D → devDependencies
npm uninstall express        # удалить
npm ci                       # установка по lock — прод и CI
npm run dev                  # запустить скрипт из "scripts"
npm outdated                 # что устарело
npm audit                    # известные уязвимости
npx tsc --init               # выполнить пакет без установки

I/O (input/output) — любой обмен данными с внешним миром относительно процесса: чтение и запись файлов, сетевые запросы, сокеты, работа с базой, stdin/stdout, DNS-запросы. Общее у них одно: нужно ждать ответа от диска, сети или другого процесса, и это ожидание программа не контролирует.

Процессор работает на порядки быстрее внешних устройств. Отсюда и вся асинхронная модель:

Если программа «встаёт и ждёт» диск или сеть — процессор простаивает. Классический сервер на потоках решает это так: на каждый запрос отдельный поток, и потоки просто спят в ожидании I/O. При тысячах соединений это дорого и по памяти, и по переключениям контекста.

Одно и то же чтение файла двумя способами:

// Блокирующий: поток Node замирает, пока файл читается
const fs = require('node:fs');
const data = fs.readFileSync('big.txt', 'utf8');
console.log('прочитано', data.length);
// следующие строки не выполнятся, пока чтение не закончится

// Неблокирующий: Node работает дальше, результат придёт позже
const fs = require('node:fs');
fs.readFile('big.txt', 'utf8', (err, data) => {
  if (err) throw err;
  console.log('прочитано', data.length);
});
console.log('эта строка выполнится сразу, не дожидаясь файла');

В асинхронном варианте Node отдаёт чтение системе через libuv, а сам возвращается в event loop и обслуживает другие запросы. Когда данные готовы — вызывается колбэк или резолвится промис.

async/await — тот же механизм, просто записанный линейно:

const fs = require('node:fs/promises');

async function main() {
  const data = await fs.readFile('big.txt', 'utf8'); // event loop не блокируется
  console.log('прочитано', data.length);
}
main();

libuv — C-библиотека, дающая Node кроссплатформенный неблокирующий I/O. В ней две ключевые части.

1. Event loop — диспетчер. Бесконечный цикл, который забирает у ОС готовые события («пришли данные по сокету», «сработал таймер», «файл прочитан»), вызывает соответствующие JS-колбэки, проверяет отложенные задачи, а если делать нечего — засыпает и просыпается на новом событии. Именно поэтому один поток JS обслуживает тысячи соединений: он не ждёт каждое, а реагирует на события. Подробный разбор фаз — в разделе Event loop и фазы.

2. Пул потоков. Некоторые операции ОС не умеет делать асинхронно — например, чтение файлов на Linux. Для них libuv держит пул фоновых потоков (по умолчанию 4, меняется через UV_THREADPOOL_SIZE): они выполняют блокирующую работу, а event loop получает только результат. Что именно уходит в пул, а что операционная система умеет делать сама — разобрано в разделе Thread pool и блокировка.

Как части схемы из раздела «Из чего состоит» работают вместе:

Нижние слои схемы — конкретные C-библиотеки, на которых стоят встроенные модули: OpenSSL (node:crypto, HTTPS/TLS), zlib (сжатие, gzip в HTTP), c-ares (асинхронный DNS в dns.resolve*), llhttp (парсер HTTP), undici (HTTP-клиент, на котором работает глобальный fetch).

Node оптимизирован под I/O-bound задачи — где время уходит на ожидание сети и диска, а не на вычисления: API-серверы, прокси, real-time, чаты, стриминг. Здесь он силён.

Но JS исполняется в одном потоке V8. Тяжёлые вычисления — сортировка гигантского массива, обработка изображений, криптография на чистом JS — останавливают event loop, и все соединения ждут, хотя никакого I/O нет:

// Блокирует event loop на секунды — все запросы повиснут
function heavyCpu() {
  let sum = 0;
  for (let i = 0; i < 1e10; i++) sum += i;
  return sum;
}

// Уводим в worker thread — event loop свободен
const { Worker } = require('node:worker_threads');
new Worker('./heavy-worker.js');

Короткая иерархия, к которой можно возвращаться при чтении дальнейших разделов:

Цикл работает, пока у libuv есть незакрытые дела: открытый сокет сервера, живой таймер, незавершённая операция с файлом. Как только счётчик таких дел обнуляется, цикл выходит и процесс завершается сам.

// Скрипт завершится сразу: дел не осталось
console.log('привет');

// А этот будет жить: открытый сервер — незакрытое дело
http.createServer(handler).listen(3000);

// И этот: интервал держит цикл вечно
setInterval(() => {}, 1000);

// unref() снимает удержание: таймер сработает, но держать цикл не будет
const t = setInterval(tick, 1000);
t.unref();

JS-код выполняется в одном потоке. Ввод-вывод — сеть, сокеты — отдаётся операционной системе через libuv неблокирующе. Когда операция завершается, её колбэк ставится в очередь, и event loop его подбирает.

console.log('1');
setTimeout(() => console.log('2'), 0);
setImmediate(() => console.log('3'));
Promise.resolve().then(() => console.log('4'));
process.nextTick(() => console.log('5'));
console.log('6');

Event loop — не одна общая очередь колбэков, а цикл из нескольких фаз. Каждая фаза держит собственную очередь задач своего типа. Node проходит фазы по кругу и на каждой обрабатывает только свою очередь. Смысл разделения — предсказуемость порядка и возможность дать разным видам работы разный приоритет.

Фаза idle/prepare — внутренняя, она нужна самому Node, и в прикладном коде вы с ней не сталкиваетесь. Остальные разбираем по порядку.

Фаз на самом деле семь или восемь; в документации разбирают те, которые реально использует Node — они перечислены выше.

Как фаза poll решает, ждать ли. У неё две работы: посчитать, сколько времени блокироваться на ожидании ввода-вывода, и обработать события из своей очереди. Дальше поведение зависит от того, что её ждёт:

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

const fs = require('node:fs');

fs.readFile(__filename, () => {
  setTimeout(() => console.log('timeout'), 0);
  setImmediate(() => console.log('immediate'));
});
// Всегда: immediate → timeout
// Мы внутри poll, а check идёт сразу за ней;
// timers наступит только на следующем проходе цикла.

// А на верхнем уровне гарантии нет — зависит от того, успел ли
// истечь таймер к моменту первого захода в фазу timers
setTimeout(() => console.log('timeout'), 0);
setImmediate(() => console.log('immediate'));
// Порядок может отличаться от запуска к запуску

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

console.log('1 — синхронно');

setTimeout(() => console.log('5 — timers'), 0);

Promise.resolve().then(() => console.log('3 — promise'));

process.nextTick(() => console.log('2 — nextTick'));

queueMicrotask(() => console.log('4 — queueMicrotask'));

console.log('1.5 — синхронно');

// Вывод:
// 1 — синхронно
// 1.5 — синхронно
// 2 — nextTick
// 3 — promise
// 4 — queueMicrotask
// 5 — timers

Сначала до конца отрабатывает синхронный код, затем вся очередь nextTick, затем все промисы — и только потом цикл уходит в следующую фазу.

Почему nextTick раньше промисов. Исторически: он появился в Node задолго до промисов, и внутренний код платформы опирался на него для гарантий согласованности — например, чтобы событие 'close' точно возникало после завершения текущей операции. Когда добавили промисы, их поставили после, чтобы не сломать существующее поведение.

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

function starve() {
  process.nextTick(starve);   // добавляет новый nextTick прямо во время слива
}
starve();
// Очередь nextTick никогда не опустеет →
// ни ввод-вывод, ни таймеры, ни setImmediate больше не выполнятся.

function loop() {
  Promise.resolve().then(loop);   // то же самое с промисами
}
loop();   // сервер встанет: до фазы poll дело не дойдёт

Поэтому nextTick и промисы хороши для «сразу после текущей операции», но не годятся для длинных циклов обработки. Чтобы отдавать управление циклу между итерациями, берут setImmediate:

// Правильно: между порциями работы цикл успевает обслужить ввод-вывод
function processChunk() {
  // ...немного работы...
  setImmediate(processChunk);   // уходим в фазу check, даём шанс poll
}

Сеть в пул не идёт. TCP, HTTP и сокеты операционная система умеет обслуживать сама: она сообщает процессу, когда на сокете появились данные, и отдельный поток для ожидания не нужен. Поэтому тысячи открытых соединений не стоят Node почти ничего, а вот сотня одновременных чтений файлов упирается в четыре потока пула.
Механизмы, которыми это сделано, называются epoll в Linux, kqueue в macOS и IOCP в Windows — знать их названия для работы не нужно.

По умолчанию в пуле 4 потока, меняется переменной окружения UV_THREADPOOL_SIZE.

# так — работает
UV_THREADPOOL_SIZE=8 node app.js

• JSON.parse огромных тел запроса
• Тяжёлые регулярные выражения (катастрофический бэктрекинг)
• Синхронные вызовы fs: readFileSync в обработчике
• Циклы на миллионы итераций
• Синхронный bcrypt

// Основной способ — try/catch вокруг await
try {
  const user = await fetchUser(id);
} catch (e) {
  // обработка
}

Поток отдаёт данные кусками и не держит всё в памяти. Отдать CSV-отчёт на гигабайт без потоков — значит сначала собрать этот гигабайт в память процесса.

import { pipeline } from 'node:stream/promises';

// pipeline сам обрабатывает backpressure, ошибки и закрытие потоков
await pipeline(
  source,
  transform,
  destination,
);

# Запуск с инспектором
node --inspect app.js

# Дальше: Chrome DevTools → Memory → два heap snapshot с интервалом,
# сравнить и посмотреть, что выросло

// Быстрая проверка в рантайме
setInterval(() => console.log(process.memoryUsage()), 10_000);

1. Поймать SIGTERM
2. Перестать принимать новые запросы — server.close()
3. Дать текущим запросам завершиться
4. Закрыть пул БД и подключения к очередям
5. Выйти

// NestJS
app.enableShutdownHooks();

// И хуки в провайдерах:
async onModuleDestroy() { /* закрыть ресурсы */ }
async beforeApplicationShutdown(signal?: string) { /* ... */ }

Соединение начинается как обычный HTTP-запрос с просьбой сменить протокол, после чего тот же TCP-сокет работает уже по WebSocket.

// Запрос клиента
GET /ws HTTP/1.1
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==

// Ответ сервера
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade

import { WebSocketServer, WebSocket } from 'ws';  // WebSocket нужен ради константы OPEN

const wss = new WebSocketServer({ port: 8080 });

wss.on('connection', (ws) => {
  ws.send('Добро пожаловать!');

  ws.on('message', (raw) => {
    const text = raw.toString();

    // Разослать всем живым клиентам
    for (const client of wss.clients) {
      if (client.readyState === WebSocket.OPEN) {
        client.send(text);
      }
    }
  });
});

// Клиент
const ws = new WebSocket('wss://example.com/ws');
ws.onopen    = () => ws.send('привет');
ws.onmessage = (e) => console.log(e.data);
ws.onclose   = () => /* переподключение пишешь сам */;

Сервер открывает один долгоживущий HTTP-ответ и пишет в него текстовые события. Клиент только слушает.

// Примеры ниже используют import, поэтому в package.json нужно
// "type": "module". Без этой строки Node ждёт CommonJS и упадёт
// с «Cannot use import statement outside a module».
import express from 'express';
const app = express();

app.get('/events', (req, res) => {
  res.setHeader('Content-Type',  'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  // Connection здесь только для HTTP/1.1. В HTTP/2 этот заголовок запрещён
  if (req.httpVersionMajor === 1) res.setHeader('Connection', 'keep-alive');
  res.setHeader('X-Accel-Buffering', 'no');  // чтобы Nginx не копил ответ в буфере
  res.flushHeaders();

  const timer = setInterval(() => {
    const payload = { ts: Date.now(), value: Math.random() };

    // Формат строгий: поле, двоеточие, значение. Событие закрывают ДВА \n
    res.write(`id: ${payload.ts}\n`);
    res.write(`data: ${JSON.stringify(payload)}\n\n`);
  }, 2000);

  req.on('close', () => { clearInterval(timer); res.end(); });
});

// Клиент — всё встроено в браузер
const es = new EventSource('/events');
es.onmessage = (e) => console.log(JSON.parse(e.data));
es.onerror   = () => /* браузер переподключится сам */;

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

const waiting = new Map();   // res -> timer

app.get('/poll', (req, res) => {
  const since = Number(req.query.since ?? 0);
  const missed = getEventsAfter(since);

  // Если что-то уже накопилось — отдаём сразу, без ожидания
  if (missed.length) return res.json(missed);

  // Таймаут обязателен: иначе прокси оборвёт соединение сам
  const timer = setTimeout(() => {
    waiting.delete(res);
    res.json([]);          // пустой ответ — клиент сразу спросит снова
  }, 25_000);

  // Храним ответ ВМЕСТЕ с его таймером, иначе погасить его потом нечем
  waiting.set(res, timer);

  req.on('close', () => { clearTimeout(timer); waiting.delete(res); });
});

function publish(event) {
  store(event);
  for (const [res, timer] of waiting) {
    clearTimeout(timer);   // иначе через 25 с сработает res.json([]) на уже отвеченном ответе
    res.json([event]);
  }
  waiting.clear();
}

Nest CLI создаёт каркас и умеет генерировать части модуля. Для примера понадобятся сам Nest, валидация и TypeORM с драйвером PostgreSQL.

npm i -g @nestjs/cli
nest new shop            # каркас приложения
cd shop

npm i @nestjs/typeorm typeorm pg
npm i class-validator class-transformer

nest g module orders     # создаст orders.module.ts и подключит его к AppModule
nest g controller orders
nest g service orders

Две таблицы: счёт пользователя и заказ. На них мы потом покажем транзакцию — списание денег и создание заказа должны происходить вместе или не происходить вовсе.

// src/orders/account.entity.ts
import { Entity, PrimaryGeneratedColumn, Column } from 'typeorm';

@Entity()
export class Account {
  @PrimaryGeneratedColumn()
  id: number;

  // numeric вместо float: деньги нельзя хранить в плавающей точке
  @Column({ type: 'numeric', precision: 12, scale: 2 })
  balance: string;
}

// src/orders/order.entity.ts
import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn } from 'typeorm';

@Entity()
export class Order {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  accountId: number;

  @Column({ type: 'numeric', precision: 12, scale: 2 })
  total: string;

  // ключ идемпотентности: повторный запрос не создаст второй заказ
  @Column({ unique: true })
  requestId: string;

  @CreateDateColumn()
  createdAt: Date;
}

DTO здесь ровно то же, что FormRequest в Laravel: описание того, что мы согласны принять. Разница в том, что правила пишутся декораторами прямо над полями, а не массивом в методе rules().

// src/orders/dto/create-order.dto.ts
import { IsInt, IsPositive, IsNumberString, IsUUID } from 'class-validator';

export class CreateOrderDto {
  @IsInt()
  @IsPositive()
  accountId: number;

  // строка, а не number: иначе float испортит копейки
  @IsNumberString()
  total: string;

  @IsUUID()
  requestId: string;
}

Чтобы декораторы начали работать, валидацию включают глобально. Заодно просим отсекать лишние поля — иначе клиент пришлёт isAdmin: true, и оно доедет до сервиса.

// src/main.ts
import { NestFactory } from '@nestjs/core';
import { ValidationPipe } from '@nestjs/common';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.useGlobalPipes(new ValidationPipe({
    whitelist: true,             // выкинуть поля, которых нет в DTO
    forbidNonWhitelisted: true,  // и вернуть 400, если такие были
    transform: true,             // привести типы: '5' из params станет number
  }));

  app.enableShutdownHooks();     // без этого SIGTERM не доедет до onModuleDestroy
  await app.listen(3000);
}
bootstrap();

Guard отвечает на один вопрос: продолжать обработку или отказать. Он срабатывает до валидации — нет смысла разбирать тело запроса от того, кого мы всё равно не пустим.

// src/orders/api-key.guard.ts
import { CanActivate, ExecutionContext, Injectable, UnauthorizedException } from '@nestjs/common';

@Injectable()
export class ApiKeyGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest();
    const key = request.headers['x-api-key'];

    if (key !== process.env.API_KEY) {
      throw new UnauthorizedException('Неверный ключ');
    }
    return true;
  }
}

В контроллере не должно быть бизнес-логики. Его работа — принять запрос, передать данные в сервис и вернуть результат. Ровно как тонкий контроллер в Laravel.

// src/orders/orders.controller.ts
import { Body, Controller, Get, Param, Post, UseGuards } from '@nestjs/common';
import { OrdersService } from './orders.service';
import { CreateOrderDto } from './dto/create-order.dto';
import { ApiKeyGuard } from './api-key.guard';

@Controller('orders')
export class OrdersController {
  // зависимость объявляется в конструкторе — Nest подставит её сам
  constructor(private readonly orders: OrdersService) {}

  @Post()
  @UseGuards(ApiKeyGuard)
  create(@Body() dto: CreateOrderDto) {
    return this.orders.create(dto);
  }

  @Get(':id')
  findOne(@Param('id') id: number) {
    return this.orders.findOne(id);
  }
}

Здесь живёт логика. Списание денег и создание заказа обязаны быть атомарными: если заказ не создался, деньги должны вернуться. В TypeORM это делают через DataSource.transaction — аналог DB::transaction() в Laravel.

// src/orders/orders.service.ts
import { Injectable, BadRequestException, ConflictException, NotFoundException } from '@nestjs/common';
import { InjectDataSource } from '@nestjs/typeorm';
import { DataSource } from 'typeorm';
import { Account } from './account.entity';
import { Order } from './order.entity';
import { CreateOrderDto } from './dto/create-order.dto';

@Injectable()
export class OrdersService {
  constructor(@InjectDataSource() private readonly dataSource: DataSource) {}

  async create(dto: CreateOrderDto) {
    return this.dataSource.transaction(async (manager) => {

      // Блокируем строку счёта до конца транзакции.
      // Без этого два одновременных запроса прочитают один и тот же
      // баланс и спишут дважды — классическая гонка.
      const account = await manager.findOne(Account, {
        where: { id: dto.accountId },
        lock: { mode: 'pessimistic_write' },
      });

      if (!account) throw new NotFoundException('Счёт не найден');

      const balance = Number(account.balance);
      const total   = Number(dto.total);
      if (balance < total) throw new BadRequestException('Недостаточно средств');

      account.balance = (balance - total).toFixed(2);
      await manager.save(account);

      try {
        return await manager.save(Order, {
          accountId: dto.accountId,
          total: dto.total,
          requestId: dto.requestId,
        });
      } catch (e: any) {
        // 23505 — нарушение уникальности: такой requestId уже был.
        // Значит это повтор, а не новая покупка.
        if (e.code === '23505') throw new ConflictException('Заказ уже создан');
        throw e;
      }
    });
  }

  async findOne(id: number) {
    const order = await this.dataSource.getRepository(Order).findOneBy({ id });
    if (!order) throw new NotFoundException();
    return order;
  }
}

Модуль перечисляет, из чего состоит фича и что она отдаёт наружу. Всё, чего нет в exports, остаётся внутренним — это и есть граница, которой нет у сервис-провайдера Laravel.

// src/orders/orders.module.ts
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { OrdersController } from './orders.controller';
import { OrdersService } from './orders.service';
import { Order } from './order.entity';
import { Account } from './account.entity';

@Module({
  imports: [TypeOrmModule.forFeature([Order, Account])],
  controllers: [OrdersController],
  providers: [OrdersService],
  exports: [OrdersService],   // другие модули смогут его внедрить
})
export class OrdersModule {}

// src/app.module.ts — подключение базы и нашего модуля
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { OrdersModule } from './orders/orders.module';

@Module({
  imports: [
    TypeOrmModule.forRoot({
      type: 'postgres',
      host: 'localhost',
      port: 5432,
      username: 'postgres',
      password: 'postgres',
      database: 'shop',
      autoLoadEntities: true,
      synchronize: true,   // только для разработки: в проде — миграции
    }),
    OrdersModule,
  ],
})
export class AppModule {}

npm run start:dev

# без ключа — 401 от guard
curl -X POST localhost:3000/orders \
  -H 'Content-Type: application/json' \
  -d '{"accountId":1,"total":"100.00","requestId":"3f1a..."}'

# с ключом, но с лишним полем — 400 от ValidationPipe (forbidNonWhitelisted)
curl -X POST localhost:3000/orders \
  -H 'x-api-key: secret' -H 'Content-Type: application/json' \
  -d '{"accountId":1,"total":"100.00","requestId":"3f1a...","isAdmin":true}'

# корректный запрос — 201 и созданный заказ
curl -X POST localhost:3000/orders \
  -H 'x-api-key: secret' -H 'Content-Type: application/json' \
  -d '{"accountId":1,"total":"100.00","requestId":"3f1a..."}'

# тот же requestId ещё раз — 409, второй заказ не создан

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

Если хук вернул промис, Nest дождётся его перед переходом к следующему шагу — поэтому в них можно спокойно делать асинхронную работу.

const app = await NestFactory.create(AppModule);

// без этой строки хуки по сигналам не сработают
app.enableShutdownHooks();

await app.listen(3000);

Запрос проходит фиксированную последовательность. У каждого типа обработчиков есть три уровня — глобальный, контроллера и маршрута, — и они тоже идут в строгом порядке.

Провайдер регистрируется в модуле, Nest строит граф зависимостей по типам параметров конструктора — ровно как контейнер Laravel по рефлексии.

// Четыре формы — аналог bind/singleton/instance в Laravel
{ provide: PaymentGateway, useClass: StripeGateway }
{ provide: 'CONFIG', useValue: { timeout: 5000 } }
{ provide: Client, useFactory: (cfg) => new Client(cfg), inject: [Config] }
{ provide: Alias, useExisting: Original }

Через них подменяют реализации — например, мок платёжного шлюза в тестах.

app.useGlobalPipes(new ValidationPipe({
  whitelist: true,              // выкинуть поля, которых нет в DTO
  forbidNonWhitelisted: true,   // или вообще отклонить запрос
  transform: true,              // привести типы: '5' → 5
}));

export class CreateOrderDto {
  @IsUUID()      productId: string;
  @IsInt() @Min(1) quantity: number;
  @IsString() @IsOptional() comment?: string;
}

@nestjs/passport + @nestjs/jwt: JwtStrategy валидирует токен, JwtAuthGuard вешается на контроллер или глобально.

// Роли: свой декоратор через SetMetadata + guard, читающий их через Reflector
@Roles('admin')
@UseGuards(JwtAuthGuard, RolesGuard)
@Delete(':id')
remove(@Param('id') id: string) { /* ... */ }

// TypeORM: все запросы внутри идут через manager
await dataSource.transaction(async (manager) => {
  const order = await manager.findOneOrFail(Order, {
    where: { id },
    lock: { mode: 'pessimistic_write' },   // SELECT ... FOR UPDATE
  });
  // ...
});

// Prisma
await prisma.$transaction(async (tx) => { /* ... */ });

const moduleRef = await Test.createTestingModule({
  providers: [PaymentsService, LedgerService],
})
  .overrideProvider(PaymentGateway)
  .useValue(mockGateway)
  .compile();

-- Вариант 1: атомарный UPDATE с условием, затем проверка rowCount
UPDATE accounts SET balance = balance - $1
WHERE id = $2 AND balance >= $1;

-- Вариант 2: блокировка строки в транзакции
SELECT * FROM accounts WHERE id = $1 FOR UPDATE;

Плюс идемпотентность операции по ключу: уникальный индекс на idempotency_key.

-- Нарушение уникальности в Postgres = код 23505
-- Либо ловим его, либо:
INSERT INTO processed_events (event_id) VALUES ($1)
ON CONFLICT (event_id) DO NOTHING RETURNING event_id;
-- Вернулась строка → обрабатываем впервые. Пусто → уже обработано.

-- SKIP LOCKED: берём строку и блокируем, занятые другими — пропускаем
SELECT id FROM jobs
WHERE status = 'pending' AND run_at <= now()
ORDER BY id
FOR UPDATE SKIP LOCKED
LIMIT 1;

Платёжные провайдеры доставляют вебхуки как минимум один раз: повторы при таймауте — норма, а не сбой. Обработчик обязан быть идемпотентным.

@Injectable()
export class PaymentsService {
  constructor(
    private readonly ds: DataSource,
    private readonly ledger: LedgerService,
  ) {}

  async applyEvent(evt: PspEvent): Promise<void> {
    await this.ds.transaction(async (m) => {

      // 1. Дедупликация: второй такой же вебхук ничего не вставит
      const fresh = await m.query(
        `INSERT INTO processed_events (event_id) VALUES ($1)
         ON CONFLICT (event_id) DO NOTHING RETURNING event_id`,
        [evt.id],
      );
      if (fresh.length === 0) return;   // уже обработан

      // 2. Блокируем заказ — параллельный вебхук подождёт
      const order = await m.findOneOrFail(Order, {
        where: { id: evt.orderId },
        lock: { mode: 'pessimistic_write' },
      });
      if (order.status !== 'pending') return;

      order.status = 'paid';
      await m.save(order);

      // 3. Проводки и задача коммитятся ВМЕСТЕ с оплатой
      await this.ledger.post(m, [
        { account: 'psp_clearing', debit: evt.amountMinor },
        { account: 'revenue',      credit: evt.amountMinor },
      ]);
      await m.insert(Job, { type: 'deliver_key', orderId: order.id });
    });
  }
}

async requestKey(orderId: string, requestId: string) {
  try {
    const res = await fetch(`${this.baseUrl}/keys`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Idempotency-Key': requestId,
      },
      body: JSON.stringify({ orderId }),
      signal: AbortSignal.timeout(5_000),
    });
    if (!res.ok) return { status: 'error', code: res.status };
    return { status: 'ok', key: (await res.json()).key };
  } catch (e) {
    // Таймаут НЕ значит отказ: операция могла пройти.
    if (e instanceof Error && e.name === 'TimeoutError') {
      return { status: 'unknown' };
    }
    throw e;
  }
}

Баланс не хранится изменяемым числом, а считается из проводок. Каждая операция — набор проводок, где сумма дебетов равна сумме кредитов; иначе транзакция не коммитится.