Навигация

Конфигурация и валидация в Node.js

Сервис падает не только из-за ошибок в бизнес-логике: пустой JWT_SECRET, DATABASE_URL с опечаткой или limit=abc в query дают те же 500, которые потом ищут неделю. Конфигурация и входные данные — две границы, где ошибку ещё дёшево остановить: до того, как она попадёт в базу и логику. Разберём, как отделить конфиг от кода, проверить env на старте и описать params, query и body схемами, которые одновременно служат типами.

Содержание

  1. Конфигурация отдельно от кода
  2. Источники конфигурации и приоритет
  3. Локальный .env и загрузка переменных
  4. Валидация конфига на старте
  5. Секреты: хранение и утечки
  6. Три источника входа
  7. Схемы zod: parse и safeParse
  8. Приведение типов и значения по умолчанию
  9. Ошибки валидации и статус 422
  10. DTO, unknown и any
  11. Валидация ответа и контракт API
  12. Практика: TaskFlow
  13. Частые ошибки
  14. Ключевые тезисы для интервью
  15. Заключение
  16. Полезные ссылки

Конфигурация отдельно от кода

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

В Node соблазн обойтись process.env велик, и сначала это выглядит безобидно:

// плохо: конфиг размазан по модулям
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const port = process.env.PORT || 3000;
const logLevel = process.env.LOG_LEVEL ?? 'info';

Проблемы начинаются, когда таких строк становится десяток. Никто не знает полный список обязательных переменных: одна появляется в db.js, другая в auth.js, третья только в тесте. PORT — строка, поэтому PORT='3000 ' с пробелом даёт неожиданный результат. Опечатка в имени (DATABSE_URL) не ловится ни типами, ни линтером, а падение происходит в момент первого запроса к базе, то есть уже под трафиком.

Поэтому конфиг собирают в один модуль — единственную точку, где приложение читает окружение. Модуль проверяет значения, приводит типы, подставляет дефолты и экспортирует уже готовый объект:

import { config } from './config.js';

const pool = new Pool({ connectionString: config.DATABASE_URL });

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

Чем отличается от фронтенда

Во фронтенде переменные окружения обычно вшиваются в бандл на этапе сборки: Vite заменяет import.meta.env.VITE_API_URL, Next.js — process.env.NEXT_PUBLIC_*. Собранный файл уже содержит конкретные значения, поэтому «один артефакт для всех сред» там не работает, а всё, что начинается с публичного префикса, видно любому пользователю. В Node env читается в рантайме: тот же контейнер запускается с разными переменными, а секреты не попадают в артефакт. Отсюда и разные правила: на клиенте публичные переменные не секрет, на сервере DATABASE_URL — секрет.


Источники конфигурации и приоритет

У конфигурации несколько источников, и они не равноправны:

ИсточникПримерКогда уместен
Аргументы CLI--port=3000разовый запуск, скрипты, отладка
Переменные окруженияPORT=3000контейнеры, прод, CI
Файл .env.env.localлокальная разработка
Файл конфигаconfig/production.jsonсложные структуры, не секреты
Дефолты в схемеdefault(3000)безопасное значение по умолчанию

Приоритет идёт от самого явного к самому неявному: аргументы командной строки перекрывают окружение, окружение — файл .env, а файл — дефолты. Такой порядок позволяет локально работать с .env, но задать одну переменную прямо перед командой node и проверить поведение продакшена.

На практике в Node-сервисе почти всегда достаточно окружения. Файлы конфига берут, когда настройка — это вложенная структура (например, список интеграций с параметрами), которую неудобно описывать десятком плоских переменных. Но и тогда файл содержит не секреты, а ссылки на них.

Полезно договориться о префиксе: APP_PORT, APP_DATABASE_URL. В окружении контейнера живут десятки переменных от других инструментов, и общее имя вроде PORT может неожиданно пересечься с чужой настройкой.

Отдельно стоит помнить, что окружение — не «типобезопасное хранилище». Любая переменная либо строка, либо undefined. Даже PORT=3000 — это строка '3000', а не число. Всё, что делает её числом, булевым или URL, — работа схемы.


Локальный .env и загрузка переменных

Для разработки удобно держать значения в файле .env в корне проекта:

# .env — только локально, в git не попадает
NODE_ENV=development
PORT=3000
DATABASE_URL=postgres://app:devpass@localhost:5432/taskflow
JWT_SECRET=dev-only-secret-change-me-please
LOG_LEVEL=debug

Файл добавляют в .gitignore, а в репозиторий коммитят .env.example — тот же список ключей без значений. Новый разработчик копирует пример в .env и заполняет своими локальными данными. Это дешевле, чем инструкция «спроси у коллеги пароль от локальной базы».

Загрузить файл можно двумя способами. Первый — библиотека dotenv:

// первая строка точки входа
import 'dotenv/config';

Важно, что порядок импортов здесь не косметика: модули вычисляются в порядке импорта, поэтому dotenv/config должен выполниться раньше модуля конфига, который читает process.env. Если линтер сортирует импорты, такая зависимость легко ломается.

Второй способ — встроенный в Node:

node --env-file=.env src/server.js

Опция появилась в Node 20.6 и не требует зависимости. Если файла может не быть, берут --env-file-if-exists=.env (Node 22.9+); из кода файл загружает process.loadEnvFile('.env') (Node 20.12+). Встроенный загрузчик не решает проблему порядка импортов: переменные появляются до выполнения любого модуля.

Есть тонкость, которая часто удивляет: dotenv не перезаписывает переменные, уже заданные в окружении. Если в шелле есть PORT=4000, файл со значением 3000 его не изменит. Это соответствует 12-factor: платформа или secret store передают реальные значения, а .env — лишь локальный дефолт. Встроенный --env-file ведёт себя похоже.

Синтаксис .env простой: KEY=VALUE, комментарии с #, кавычки для значений с пробелами. Подстановки вида ${HOME} по умолчанию нет — для неё нужен отдельный пакет вроде dotenv-expand. Если значение содержит #, его лучше заключить в кавычки, иначе хвост может уйти в комментарий.

И главное: .env не должен попадать в образ. Даже если файл удалить следующей командой RUN, он останется в предыдущем слое. Поэтому .env* добавляют в .dockerignore, а в контейнере переменные приходят от платформы.


Валидация конфига на старте

Главное решение здесь — когда проверять конфиг. Проверка при первом обращении к переменной выглядит лениво и удобно, но превращает ошибку конфигурации в 500 в произвольный момент времени. Проверка на старте (fail fast) делает её дефектом деплоя: процесс не принимает трафик, оркестратор видит падение, а в логе — понятное сообщение.

Особенно опасны «мягкие» ошибки: сервис стартует, но работает неправильно. JWT_SECRET=undefined превращается в строку 'undefined', и токены подписываются предсказуемым ключом. Пустой DATABASE_URL даёт ошибку на каждый запрос, но health check может отвечать 200. Явное падение на старте лучше тихой деградации.

Схема описывает окружение как обычный объект. Загрузчик намеренно ничего не завершает: он только проверяет и возвращает данные, а решение «упасть» принимает точка входа.

// src/env.js
import { z } from 'zod';

const EnvSchema = z.object({
  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
  PORT: z.coerce.number().int().min(1).max(65535).default(3000),
  DATABASE_URL: z.url(),
  JWT_SECRET: z.string().min(32),
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
});

export class ConfigError extends Error {}

export function loadConfig(env = process.env) {
  const result = EnvSchema.safeParse(env);

  if (!result.success) {
    const fields = Object.keys(z.flattenError(result.error).fieldErrors);
    throw new ConfigError(`Некорректная конфигурация: ${fields.join(', ')}`);
  }

  return Object.freeze(result.data);
}
// src/config.js
import { loadConfig } from './env.js';

let config;
try {
  config = loadConfig();
} catch (error) {
  console.error(error.message);
  process.exit(1);
}

export { config };

Такое разделение даёт две вещи. Загрузчик остаётся обычной функцией, которую можно вызвать в тесте с произвольным объектом окружения, а поведение процесса — «залогировать и завершиться с кодом 1» — описано в одном месте и не повторяется в каждом модуле. Если config.js импортирован до listen, некорректное окружение роняет сервис ещё до приёма трафика.

Разберём важные детали:

  • z.coerce.number() превращает строку '3000' в число и заодно отсекает '3000abc': Number('3000abc') даёт NaN, который не проходит .number().
  • z.url() проверяет, что строка разбирается как URL. postgres://... — валидный URL, поэтому проверка работает и для строк подключения. В Zod 3 это записывалось как z.string().url().
  • z.enum(...) ловит опечатку в NODE_ENV и LOG_LEVEL, которая иначе тихо включает не тот режим.
  • default() даёт безопасное значение, когда переменная не задана. Если у сервиса нет разумного дефолта (пароль, ключ), дефолта быть не должно — пусть старт падает.
  • flattenError группирует ошибки по полям. В Zod 3 эквивалент — error.flatten(). В лог попадают только имена полей, не значения: иначе DATABASE_URL с паролем окажется в логах.

Object.freeze защищает от случайной записи в конфиг, но заморозка поверхностная: вложенный объект останется изменяемым. Если конфиг содержит вложенные структуры, нужен глубокий freeze или запрет на вложенность.

Тип выводится из схемы там же, где она объявлена:

export type Config = z.infer<typeof EnvSchema>;

Фабрика loadConfig(env) нужна для тестов: она принимает объект окружения и не читает глобальный process.env. Экспортированный config — удобство для приложения: он собирается поверх той же фабрики, а решение о завершении процесса принимает отдельный модуль.

В NestJS ту же роль играет ConfigModule с validate или validationSchema: конфиг собирается при старте модуля, а провайдеры получают типизированные значения. В Fastify и Express валидацию пишут сами — как выше, — но принцип один.


Секреты: хранение и утечки

Секрет — это конфиг, который нельзя показывать никому, кроме сервиса: пароль базы, JWT_SECRET, ключи платёжного провайдера, токен внешнего API. Утечка одного такого значения обычно означает компрометацию данных, а не просто неудобство.

В продакшене секреты приходят из secret store: Kubernetes Secrets, Vault, AWS Secrets Manager, Docker secrets или менеджер облачной платформы. Платформа подставляет их в окружение при запуске контейнера, а доступ к ним регулируется правами и аудитом. Ротация — тоже часть платформы: ключ меняется в одном месте, а приложение получает новое значение при следующем рестарте или перечитывании.

.env, .env.production и любые файлы с реальными значениями в продакшене не используются. Причины простые:

  • файл легко коммитится случайно — git add . не спрашивает;
  • файл попадает в образ и остаётся в слоях даже после удаления;
  • файл читается любым процессом и часто попадает в логи и дампы;
  • ротация и разграничение доступа в файле не реализуются;
  • в репозитории оказываются секреты, которые потом живут в истории навсегда.

Практические правила:

  • В git — только .env.example. Реальные .env* в .gitignore, а в CI — проверка на случайно добавленные секреты.
  • В логах — только имена ключей. Не логировать config целиком, а тем более строку подключения: пароль в DATABASE_URL — часть URL.
  • Не возвращать детали ошибок наружу. Error middleware для 500 отдаёт общий текст, а стек и сообщение пишет в лог. Это уже обсуждалось в статье «Express и middleware».
  • Разные секреты для разных сред. Локальный пароль не должен работать на стейдже, а стейджевый — в проде.
  • Минимальные права. Пользователь базы для приложения не должен уметь менять схему, если миграции запускает отдельный процесс.
  • Секреты видны дочерним процессам. child_process.spawn по умолчанию наследует окружение, поэтому сторонний бинарник получает все переменные. Если это нежелательно, окружение передают явно.

Отдельная ловушка — фронтенд. Всё, что вшито в клиентский бандл, публично, независимо от имени переменной. NEXT_PUBLIC_* и VITE_* — не секреты, а конфигурация интерфейса. Подробнее — в статье «Управление секретами во фронтенде».


Три источника входа

У запроса есть несколько источников данных, и каждый приходит в своём виде:

ИсточникЧто содержитТипТипичная ошибка
req.paramsидентификаторы из путивсегда строкаNumber('abc') даёт NaN
req.queryфильтры, пагинация, сортировкастрока или массив строк?done=false — непустая строка
req.bodyJSON после парсерапроизвольная формабез парсера undefined
req.headersтокен, язык, тип контентастрока или undefinedдоверие заголовкам прокси

params и query — это всегда строки, потому что URL не знает типов. Повторяющийся ключ ?tag=a&tag=b в Express 5 с парсером simple превращается в массив. body зависит от парсера: express.json() даёт объект, но только если content-type совпал, а JSON синтаксически корректен. В Express 5 неразобранное тело — undefined, а не {}.

Отдельно стоит помнить про req.query в Express 5: это геттер, доступный только для чтения. Присваивание req.query = parsed в строгом режиме ESM бросает TypeError, а нормализованное значение нужно хранить в отдельном поле — например, req.validated. Это же касается попыток «починить» query на месте: Express 5 сознательно не даёт менять результат парсинга.

С точки зрения доверия источники делятся на две группы. Окружение контролирует оператор или платформа: там не ждут атаки, но ждут опечатки. Запрос контролирует клиент: там ждут и опечаток, и намеренно странных значений. Поэтому конфиг проверяют на старте, а вход — на каждой границе.

И ещё одно отличие от фронтенда: клиентская валидация формы — это удобство пользователя, её обходят через curl за десять секунд. Серверная валидация — единственная, которая что-то гарантирует. Клиентскую можно оставить, но дублировать правила на сервере всё равно придётся.


Схемы zod: parse и safeParse

Схема — это декларативное описание формы данных, из которого одновременно получаются две вещи: проверка в рантайме и TypeScript-тип. В отличие от ручных if (typeof x === 'string'), схема собирается из маленьких частей, композируется и даёт структурированные ошибки.

import { z } from 'zod';

const CreateTaskSchema = z.strictObject({
  title: z.string().trim().min(1).max(200),
  done: z.boolean().default(false),
});

У схемы два основных способа применения:

// parse: бросает ZodError при несоответствии
const task = CreateTaskSchema.parse(input);

// safeParse: возвращает результат-объединение
const result = CreateTaskSchema.safeParse(input);

if (!result.success) {
  result.error.issues; // [{ path, message, code }, ...]
} else {
  result.data;          // типизированные данные
}

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

Схема объекта по умолчанию отбрасывает ключи, которых нет в описании. Это защищает от случайного попадания лишних полей в данные, но молча скрывает опечатки: клиент отправил titel вместо title, а получил 422 по отсутствующему title — без упоминания лишнего ключа. Для тела запроса обычно выбирают строгий режим:

ФормаЛишние ключи
z.object({...})отбрасываются (strip)
z.strictObject({...})ошибка валидации
z.looseObject({...})сохраняются как есть

В Zod 3 те же режимы включались методами .strict() и .passthrough(). В Zod 4 они стали отдельными функциями, а старые методы остались для совместимости.

Выбор режима зависит от источника. Для body строгий вариант обычно правильный: неизвестное поле — почти наверняка опечатка или попытка присвоить служебное значение. Для query он может быть слишком жёстким: аналитика и рекламные ссылки добавляют параметры вроде utm_source, и API начнёт отклонять валидные запросы. Там чаще оставляют strip или явно перечисляют разрешённые служебные ключи.

Схемы композируются, поэтому не приходится дублировать поля между созданием и обновлением:

const BaseTask = z.object({
  title: z.string().trim().min(1).max(200),
  done: z.boolean(),
});

const CreateTask = BaseTask.partial({ done: true }); // done необязателен
const UpdateTask = BaseTask.partial();              // все поля необязательны
const TaskResponse = BaseTask.extend({ id: z.uuid() });

Для вариантов тела с разной формой используют z.discriminatedUnion по полю-тегу: он выбирает ветку по значению type и даёт понятную ошибку, если тег неизвестен. Для строковых форматов в Zod 4 есть z.uuid(), z.iso.datetime(), z.httpUrl(); цепочки вроде z.string().uuid() устарели.

Тип выводится из схемы:

type CreateTaskDto = z.infer<typeof CreateTask>;

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


Приведение типов и значения по умолчанию

Вход из HTTP и env почти всегда строковый, поэтому приведение — не удобство, а часть контракта. Но именно здесь больше всего ловушек.

Числа. z.coerce.number() использует Number(). Это значит, что '10' станет 10, '' станет 0, а '10abc' станет NaN и не пройдёт проверку. Границы задаются сразу: .int(), .min(1), .max(100). Для пагинации границы обязательны.

Булевы. z.coerce.boolean() — классическая ловушка: приведение через Boolean() считает истиной любую непустую строку. Запрос ?done=false даст true. Для query булево описывают явно:

const done = z.enum(['true', 'false'])
  .transform((value) => value === 'true')
  .optional();

Тогда ?done=false — это false, ?done=yes — 422, а отсутствие параметра — undefined. Тот же подход годится для флагов вида ?include=deleted.

Пустая строка. Переменная PORT=, заданная пустой, с точки зрения схемы определена. Number('') даёт 0, и проверка .min(1) падает с сообщением про диапазон, а не про пустое значение. Если пустая строка в проекте означает «не задано», её нормализуют до undefined:

const optionalUrl = z.preprocess(
  (value) => (value === '' ? undefined : value),
  z.url().optional(),
);

default и optional — разные вещи. .optional() разрешает undefined, но оставляет его в данных. .default() подставляет значение, когда вход undefined, и делает поле обязательным в типе результата. .nullable() разрешает null — важно для JSON, где null приходит явно и не равен отсутствию поля.

Порядок проверок. z.string().trim().min(1) сначала обрезает пробелы, потом проверяет длину, поэтому строка из одних пробелов отклоняется. Обратный порядок .min(1).trim() проверит исходную строку и пропустит ' ', а потом обрежет её до пустой. Мелочь, которая превращается в пустые заголовки в базе.

Массивы из query. Повторяющийся ключ приходит массивом, одиночный — строкой. Схема нормализует оба случая:

const tags = z.union([z.string(), z.array(z.string())])
  .transform((value) => (Array.isArray(value) ? value : [value]))
  .optional();

Transform не валидирует результат. .transform() меняет значение и не проверяет то, что получилось. Если после преобразования нужна ещё проверка, её добавляют через .pipe(): сначала привести, потом проверить инвариант нового типа. И помните, что transform меняет выходной тип схемы — z.infer это увидит.


Ошибки валидации и статус 422

Ошибка валидации — это не сбой сервера, а неверный запрос. Поэтому она не должна превращаться в 500 и не должна раскрывать внутренности приложения.

Разделяют три случая:

  • 400 Bad Request — запрос не разбирается: битый JSON или неверный content-type. express.json() бросает SyntaxError со status: 400.
  • 413 Payload Too Large — тело больше лимита (entity.too.large); это ограничение размера, а не формата.
  • 422 Unprocessable Content — синтаксис корректен, но данные не проходят правила: отсутствует title, limit вне диапазона, неизвестный status. Код описан в RFC 9110; многие API используют для этого 400, и это допустимо, если решение принято осознанно и одинаково во всём сервисе.

Формат ответа должен быть предсказуемым и машинно-читаемым:

{
  "error": "validation failed",
  "details": [
    { "source": "body", "path": "title", "message": "String must contain at least 1 character(s)" },
    { "source": "query", "path": "limit", "message": "Number must be less than or equal to 100" }
  ]
}

Здесь есть source — тело, query или params, — path до конкретного поля и текст, который можно показать разработчику клиента. В ответ не попадают ни стек, ни исходное значение секретного поля, ни весь объект ZodError целиком.

Удобно собрать проверку в один middleware, чтобы не повторять safeParse в каждом обработчике:

// src/middleware/validate.js
import { HttpError } from '../errors.js';

export function validate(schemas) {
  return (req, res, next) => {
    const issues = [];
    const data = {};

    for (const [source, schema] of Object.entries(schemas)) {
      const result = schema.safeParse(req[source]);

      if (result.success) {
        data[source] = result.data;
        continue;
      }

      for (const issue of result.error.issues) {
        issues.push({
          source,
          path: issue.path.join('.'),
          message: issue.message,
        });
      }
    }

    if (issues.length > 0) {
      return next(new HttpError(422, 'validation failed', { issues }));
    }

    req.validated = { ...req.validated, ...data };
    next();
  };
}

Три решения в этом коде стоит проговорить:

  • Все источники проверяются вместе. Если валидировать только body, ошибка в limit уйдёт в базу и вернётся как 500. Ошибки собираются, а не бросаются на первой: клиент получает полную картину за один запрос.
  • Результат кладётся в req.validated, а не обратно в req.query. В Express 5 query только для чтения, а в req.body лежат сырые данные, к которым не должно быть доверия. Отдельное поле явно показывает, что данные проверены и приведены.
  • Ошибка уходит в next(err). Дальше её обрабатывает обычный error middleware из статьи «Express и middleware»: 422 с деталями, 500 без.

Middleware подключается после парсера тела и до обработчика:

tasksRouter.post('/', validate({ body: CreateTaskSchema }), createTask);

Если парсер не подключён, req.body равен undefined и схема честно вернёт ошибку «ожидался объект». Это лучше, чем TypeError в обработчике, но правильнее — подключить express.json() до роутера.

Для params валидация особенно важна перед запросом в базу: id, который не является UUID, не должен доходить до WHERE id = $1. Валидация здесь — не только про 422, но и про то, что в SQL попадает предсказуемое значение.

В TypeScript поле req.validated дополняют через declaration merging или типизированный хелпер запроса. Альтернатива — res.locals, но она привязана к ответу и хуже читается в сервисном коде.


DTO, unknown и any

DTO (data transfer object) — это форма данных на границе: то, что приходит в запросе или уходит в ответе. DTO не равен сущности базы и не равен доменной модели. У них разные задачи и часто разные поля.

Начнём с типов. JSON.parse в TypeScript возвращает any, и это опасно:

const body = JSON.parse(raw);
body.title; // компилируется, даже если title — число или undefined

any отключает проверку и распространяется по коду: стоит передать его в функцию, и она тоже теряет типы. Утверждение as CreateTask не лучше — это обещание компилятору, что данные соответствуют типу, хотя проверки не было. Ошибка проявится в базе или в ответе клиенту.

unknown ведёт себя иначе: использовать значение нельзя, пока тип не сужен.

const body: unknown = JSON.parse(raw);

// придётся проверить вручную...
if (typeof body !== 'object' || body === null || !('title' in body)) {
  throw new HttpError(422, 'title is required');
}

// ...или один раз на границе, схемой
const result = CreateTaskSchema.safeParse(body);
if (!result.success) throw new HttpError(422, 'validation failed');
const dto = result.data; // дальше тип известен и проверен

Схема — единственное место, где unknown превращается в конкретный тип по реальным данным. Внутри приложения типы уже можно считать гарантией: туда не попадает ничего, что не прошло границу.

Теперь про маппинг. Соблазн передать тело прямо в ORM велик:

// плохо: mass assignment
const task = await db.task.create({ data: req.body });

Клиент отправляет { "title": "x", "ownerId": "<чужой id>", "role": "admin" }, и поля, о которых API не думал, попадают в базу. Это называется mass assignment. Даже строгая схема не спасает, если поля разрешены, а права на них не проверены.

Правильный вариант — явный DTO и явная сборка сущности:

tasksRouter.post('/', validate({ body: CreateTaskSchema }), async (req, res) => {
  const { title, done } = req.validated.body;
  const task = await db.task.create({
    data: { title, done, ownerId: req.user.id },
  });
  res.status(201).json(toTaskResponse(task));
});

Здесь ownerId берётся из аутентификации, а не из тела; id, createdAt и служебные поля генерирует база. DTO содержит только то, что клиент вправе задать, а контроллер переводит DTO в доменную сущность. Подробнее про сужение типов — в статье «TypeGuard в TypeScript».


Валидация ответа и контракт API

Валидировать вход необходимо, но контракт ломается и на выходе. Типичные проблемы:

  • в ответ попадает поле, которого там быть не должно: passwordHash, внутренний ownerId, служебный флаг;
  • форма ответа меняется при рефакторинге, и клиент неожиданно ломается;
  • разные эндпоинты возвращают одну сущность в разных формах;
  • документация расходится с реальностью, потому что её пишут руками.

Самое дешёвое решение — явный сериализатор. Не res.json(row) из базы, а функция, которая собирает ответ по контракту:

export function toTaskResponse(row) {
  return {
    id: row.id,
    title: row.title,
    done: row.done,
  };
}

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

Fastify решает это иначе: response-схема у маршрута одновременно сериализует и обрезает лишние поля, а заодно ускоряет сборку JSON. Это одна из причин, по которым в Fastify контракт живёт рядом с обработчиком — подробнее в статье «Fastify и NestJS». В NestJS похожую роль играет сериализация DTO с исключением полей.

Схемы полезны и для документации: из них генерируют OpenAPI, и тогда описание эндпоинта не расходится с проверкой. Даже без генерации полезно держать контрактные тесты: фикстура ответа проверяется схемой, а изменения формы видны на ревью.

Отдельный вопрос — обратная совместимость. Добавление обязательного поля в запрос ломает существующих клиентов; удаление поля из ответа ломает тех, кто его читал. Безопаснее добавлять необязательные поля и не убирать существующие без периода deprecation. Это уже тема версионирования API, но валидация — тот механизм, который не даёт контракту тихо измениться.


Практика: TaskFlow

Соберём конфиг и валидацию для API из статьи «Express и middleware». Начнём с конфига:

// src/env.js
import { z } from 'zod';

const EnvSchema = z.object({
  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
  PORT: z.coerce.number().int().min(1).max(65535).default(3000),
  DATABASE_URL: z.url(),
  JWT_SECRET: z.string().min(32),
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
});

export class ConfigError extends Error {}

export function loadConfig(env = process.env) {
  const result = EnvSchema.safeParse(env);
  if (!result.success) {
    const fields = Object.keys(z.flattenError(result.error).fieldErrors);
    throw new ConfigError(`Некорректная конфигурация: ${fields.join(', ')}`);
  }
  return Object.freeze(result.data);
}
// src/config.js
import { loadConfig } from './env.js';

let config;
try {
  config = loadConfig();
} catch (error) {
  console.error(error.message);
  process.exit(1);
}

export { config };

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

// src/server.js
import { app } from './app.js';
import { config } from './config.js';

app.listen(config.PORT, () => {
  console.log(`TaskFlow слушает ${config.PORT} (${config.NODE_ENV})`);
});

Теперь схемы маршрутов и middleware:

// src/routes/tasks.js
import { Router } from 'express';
import { randomUUID } from 'node:crypto';
import { z } from 'zod';
import { HttpError } from '../errors.js';
import { validate } from '../middleware/validate.js';

export const tasksRouter = Router();
const tasks = [];

const CreateTaskSchema = z.strictObject({
  title: z.string().trim().min(1).max(200),
  done: z.boolean().default(false),
});

const ListTasksQuerySchema = z.object({
  done: z.enum(['true', 'false'])
    .transform((value) => value === 'true')
    .optional(),
  limit: z.coerce.number().int().min(1).max(100).default(20),
});

const TaskIdParamsSchema = z.strictObject({
  id: z.uuid(),
});

tasksRouter.get('/', validate({ query: ListTasksQuerySchema }), (req, res) => {
  const { done, limit } = req.validated.query;
  const result = tasks
    .filter((task) => done === undefined || task.done === done)
    .slice(0, limit);

  res.json(result);
});

tasksRouter.get('/:id', validate({ params: TaskIdParamsSchema }), (req, res) => {
  const task = tasks.find((item) => item.id === req.validated.params.id);
  if (!task) throw new HttpError(404, 'task not found');
  res.json(task);
});

tasksRouter.post('/', validate({ body: CreateTaskSchema }), (req, res) => {
  const { title, done } = req.validated.body;
  const task = { id: randomUUID(), title, done };
  tasks.push(task);
  res.status(201).json(toTaskResponse(task));
});

HttpError расширяется полем деталей, а error middleware добавляет их только для клиентских ошибок:

export class HttpError extends Error {
  constructor(status, message, details) {
    super(message);
    this.status = status;
    this.details = details;
  }
}
app.use((err, req, res, next) => {
  if (res.headersSent) return next(err);

  const status = err.status ?? 500;
  if (status >= 500) console.error({ err, requestId: req.id });

  res.status(status).json({
    error: status >= 500 ? 'internal error' : err.message,
    ...(err.details ? { details: err.details } : {}),
  });
});

Что теперь закрыто:

  • сервис не стартует с отсутствующим DATABASE_URL или коротким JWT_SECRET;
  • ?done=false больше не считается истиной;
  • limit=500 и limit=abc возвращают 422 с указанием поля;
  • GET /tasks/not-a-uuid не доходит до поиска в базе;
  • лишние поля в теле отклоняются, а не оседают в сущности;
  • наружу не уходит ни конфиг, ни стек, ни внутренние поля задачи.

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

import assert from 'node:assert/strict';
import test from 'node:test';
import { loadConfig, ConfigError } from './env.js';

test('падает без JWT_SECRET', () => {
  assert.throws(
    () => loadConfig({ NODE_ENV: 'test', DATABASE_URL: 'postgres://localhost/db' }),
    ConfigError,
  );
});

Для этого загрузчик и вынесен отдельно: он принимает окружение аргументом, а не читает глобальный process.env, и бросает ошибку вместо завершения процесса. src/config.js поверх него добавляет продакшн-поведение — залогировать и выйти с кодом 1.


Частые ошибки

  • process.env.X в глубине кода. Полный список переменных неизвестен, типы теряются, тесты зависят от глобального окружения.
  • Валидация конфига при первом запросе. Ошибка деплоя превращается в 500 под трафиком и в тихую деградацию.
  • Логирование всего config. Пароль из DATABASE_URL и JWT_SECRET оказываются в логах и системах сбора.
  • .env в git или в образе. Секрет остаётся в истории или в слое, даже если файл потом удалили.
  • PORT без приведения. В коде оказывается строка '3000', сравнения и арифметика ведут себя неожиданно.
  • z.coerce.boolean() для query. ?done=false превращается в true.
  • z.string().min(1) без trim(). Строка из пробелов проходит проверку и попадает в базу.
  • parse в обработчике без обработки. ZodError уходит в error middleware как 500 вместо 422.
  • Валидация только body. limit, page и id доходят до базы сырыми строками.
  • Присваивание req.query = .... В Express 5 это read-only геттер, присваивание падает или молча не работает.
  • req.body напрямую в ORM. Mass assignment: клиент задаёт ownerId, role и другие служебные поля.
  • JSON.parse с as User. Проверки не было, а компилятор уверен в обратном.
  • Схема и тип написаны отдельно. После первого изменения поля расходятся, и ошибка видна только в рантайме.
  • Ответ собирается из строки базы. В JSON попадают passwordHash и внутренние идентификаторы.

Ключевые тезисы для интервью

  • Конфигурация — отдельный модуль и граница: один артефакт работает в разных средах, а process.env читается только в одном месте и сразу превращается в типизированный объект.
  • Конфиг валидируют на старте: ошибка деплоя роняет процесс до трафика, тогда как ленивая проверка даёт 500 в произвольный момент и риск тихой небезопасной деградации.
  • Значения окружения всегда строки; приведение типов и дефолты — часть схемы, а z.coerce.boolean() считает 'false' истиной, поэтому булевы из query описывают через enum и transform.
  • Секреты живут в secret store платформы и приходят через окружение; .env — локальный инструмент, который не коммитят, не кладут в образ и не логируют.
  • Вход валидируют на границе, где params и query — недоверенные строки: одна схема даёт и проверку в рантайме, и TypeScript-тип через z.infer.
  • safeParse и структурированные issues дают 422 с перечнем полей; parse без обработки превращает ожидаемую ошибку входа в 500.
  • DTO отделён от домена и ORM: явный маппинг и unknown на границе защищают от mass assignment и от типов, которые существуют только в обещаниях.

Заключение

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

Практический минимум выглядит так: один модуль конфига с fail fast, секреты из окружения, safeParse в middleware, 422 с понятными деталями, req.validated вместо сырых req.body, явные DTO и сериализаторы ответа. Этого достаточно, чтобы большая часть ошибок входа и деплоя перестала быть загадочными 500.

Дальше логично перейти к аутентификации: проверка Authorization, сессии и токены — следующий слой, который стоит на той же границе запроса.

Полезные ссылки