Конфигурация и валидация в Node.js
Сервис падает не только из-за ошибок в бизнес-логике: пустой JWT_SECRET, DATABASE_URL с опечаткой или limit=abc в query дают те же 500, которые потом ищут неделю. Конфигурация и входные данные — две границы, где ошибку ещё дёшево остановить: до того, как она попадёт в базу и логику. Разберём, как отделить конфиг от кода, проверить env на старте и описать params, query и body схемами, которые одновременно служат типами.
Содержание
- Конфигурация отдельно от кода
- Источники конфигурации и приоритет
- Локальный .env и загрузка переменных
- Валидация конфига на старте
- Секреты: хранение и утечки
- Три источника входа
- Схемы zod: parse и safeParse
- Приведение типов и значения по умолчанию
- Ошибки валидации и статус 422
- DTO, unknown и any
- Валидация ответа и контракт API
- Практика: TaskFlow
- Частые ошибки
- Ключевые тезисы для интервью
- Заключение
- Полезные ссылки
Конфигурация отдельно от кода
Конфигурация — всё, что отличает один запуск сервиса от другого: адрес базы, порт, уровень логов, ключи, лимиты. Код при этом остаётся одним и тем же. Третий принцип 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.body | JSON после парсера | произвольная форма | без парсера 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, сессии и токены — следующий слой, который стоит на той же границе запроса.
Полезные ссылки
- The Twelve-Factor App: Config — почему конфигурация живёт в окружении
- Node.js CLI:
--env-file— встроенная загрузка.env - Node.js:
process.loadEnvFile()— загрузка окружения из кода - dotenv — формат
.envи правила загрузки - Zod — схемы, вывод типов и ошибки
- Zod v4 changelog —
z.url(),strictObject,flattenError - OWASP: Input Validation Cheat Sheet — принципы серверной валидации
- Express и middleware — куда подключать валидацию в цепочке
- Fastify и NestJS — схемы маршрута и
ConfigModule - TypeGuard в TypeScript — сужение
unknownбез схем - Управление секретами во фронтенде — почему клиентский env не бывает секретным