Валидация переменных окружения

Роль переменных окружения в конфигурации приложения

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

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

Использование схем валидации позволяет формализовать требования к конфигурации и обеспечить предсказуемость поведения приложения.

Базовая схема окружения в Zod

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

import { z } from "zod";

const envSchema = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]),
  PORT: z.string(),
  DATABASE_URL: z.string().url()
});

Каждое значение process.env поступает как строка, поэтому начальная схема часто описывает строковый уровень данных. Однако Zod позволяет сразу приводить значения к нужным типам.

Приведение типов при парсинге окружения

Типичная проблема — числовые и булевые значения, представленные строками:

const envSchema = z.object({
  PORT: z.coerce.number(),
  DEBUG: z.coerce.boolean()
});

z.coerce автоматически преобразует строку "3000" в число 3000, а "true" в true.

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

Обязательные и необязательные переменные

Переменные окружения часто имеют смешанную обязательность. Zod позволяет явно фиксировать это через optional и default.

const envSchema = z.object({
  API_KEY: z.string(),
  LOG_LEVEL: z.string().default("info"),
  FEATURE_FLAG: z.boolean().optional()
});

При отсутствии LOG_LEVEL будет подставлено значение "info". Для FEATURE_FLAG допускается undefined.

Безопасное извлечение конфигурации

После описания схемы выполняется валидация:

const env = envSchema.parse(process.env);

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

const result = envSchema.safeParse(process.env);

if (!result.success) {
  console.error(result.error.format());
  process.exit(1);
}

const env = result.data;

Такой подход позволяет централизованно обработать ошибки конфигурации.

Структурирование сложных конфигураций

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

const envSchema = z.object({
  server: z.object({
    PORT: z.coerce.number(),
    HOST: z.string()
  }),

  database: z.object({
    URL: z.string().url(),
    POOL_SIZE: z.coerce.number().default(10)
  })
});

Однако process.env не поддерживает вложенность, поэтому требуется маппинг:

const env = envSchema.parse({
  server: {
    PORT: process.env.PORT,
    HOST: process.env.HOST
  },
  database: {
    URL: process.env.DATABASE_URL,
    POOL_SIZE: process.env.DB_POOL_SIZE
  }
});

Такой слой преобразования повышает явность конфигурации.

Работа с опциональными и условными переменными

Некоторые переменные актуальны только при определённых режимах работы:

const envSchema = z.object({
  NODE_ENV: z.enum(["development", "production"]),

  DEV_TOOLS: z.string().optional(),

  DEBUG: z.coerce.boolean().optional()
}).refine((env) => {
  if (env.NODE_ENV === "development") {
    return typeof env.DEV_TOOLS === "string";
  }
  return true;
});

refine позволяет добавлять бизнес-ограничения поверх базовой схемы.

Нормализация значений через transform

Переменные окружения часто требуют приведения к удобному внутреннему формату.

const envSchema = z.object({
  CORS_ORIGINS: z.string().transform((val) => val.split(","))
});

Строка "a.com,b.com,c.com" преобразуется в массив ["a.com", "b.com", "c.com"].

Комбинация coerce и transform используется для построения полноценного слоя конфигурационной нормализации.

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

Некоторые значения требуют вычисляемых дефолтов:

const envSchema = z.object({
  TIMESTAMP: z.string().default(() => new Date().toISOString())
});

Функциональные значения позволяют фиксировать момент вычисления, а не статическое значение.

Интеграция с Node.js процессом запуска

Часто схема применяется на этапе старта приложения:

const env = envSchema.parse(process.env);

export default env;

Это создаёт единый источник конфигурации для всего приложения. Любая ошибка окружения выявляется до запуска серверной логики.

Типизация через Zod

Одним из ключевых преимуществ Zod является вывод TypeScript-типов:

const envSchema = z.object({
  PORT: z.coerce.number(),
  DATABASE_URL: z.string().url()
});

type Env = z.infer<typeof envSchema>;

Тип Env полностью соответствует валидированной структуре, что исключает расхождения между типами и реальными значениями.

Работа с безопасными значениями в runtime

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

const port = env.PORT; // всегда number
const dbUrl = env.DATABASE_URL; // всегда валидный URL строка

Отсутствие необходимости дополнительных проверок снижает количество защитного кода в бизнес-логике.

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

Ошибки Zod имеют детализированную структуру:

  • путь до поля
  • тип ошибки
  • ожидаемое значение
  • полученное значение
{
  issues: [
    {
      path: ["PORT"],
      message: "Expected number, received NaN"
    }
  ]
}

Такая структура упрощает диагностику проблем конфигурации в CI/CD и контейнерных окружениях.

Использование с dotenv

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

import "dotenv/config";
import { z } from "zod";

const env = envSchema.parse(process.env);

Схема выполняет роль финального слоя проверки поверх внешнего источника конфигурации.

Поведение при некорректных значениях

При нарушении контракта возможны различные стратегии:

  • немедленное завершение процесса
  • логирование и продолжение (редко применимо)
  • fallback на дефолтные конфигурации (ограниченные сценарии)

Zod обеспечивает детерминированную модель, где отклонения от схемы явно фиксируются.

Масштабирование схемы в больших проектах

В крупных системах схема окружения разбивается на модули:

const dbEnv = z.object({
  DATABASE_URL: z.string().url()
});

const serverEnv = z.object({
  PORT: z.coerce.number()
});

const envSchema = z.object({
  ...dbEnv.shape,
  ...serverEnv.shape
});

Такой подход позволяет поддерживать независимость подсистем конфигурации и повторное использование схем.

Защита от частичных конфигураций

Часто переменные присутствуют не полностью или содержат пустые строки. Zod позволяет фиксировать это через дополнительные проверки:

z.string().min(1)

или

z.string().refine((val) => val.trim().length > 0)

Это исключает случаи формально существующих, но фактически пустых значений.

Контроль допустимых значений

Для ограниченных наборов конфигураций используются перечисления:

z.enum(["info", "warn", "error"])

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

Повышение надёжности конфигурационного слоя

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

Оглавление