Пераверывайце зменныя сераўіса Node.js за дапамогою Zod і TypeScript.

Уявіце саботу пасля обеду падчас запуску працы. Компіляцыя пройшла, сервер запускаецца, і всі іду домоў. Чырвоў гадзіну пасля таго корыстувачы паведамляюць, што входы не выконваюцца. Выявілася, што ніхто не задаў значэнне JWT_SECRET у працоўнай асяроддзі. Аплікацыя запускалася нормальна і зламалася толькі тады, калі першы запіт звярнуўся да кода, які патрабаваў відсутняе значэнне.

Частае выкарыстоўванне process.env у всім кодзе падвышае верагатнасць такіх інцыдэнтав. Далей паказана, як заменіць такую практыку на модуль конфігурацыі з пераканальванымі дадзеннямі, выкарыстоўваючы Zod і TypeScript.

Звычны падход

Большасць коду на Node.js запошчае конфігурацыю там, дзе яна патрэбна: порт у аднам файле, строка з інформацыяй пра базу дадзенаў у іншам.

// Some random controller file
const port = process.env.PORT || 3000;
mongoose.connect(process.env.MONGO_URI);

Гэта зручна, але ў яе ёсць тры серьзныя проблемы.

1. Няма безпекі тыпаў. У TypeScript process.env.PORT ў фармаце string | undefined. Калі трэба чысло, кожны месца вызову павінен яго ручна аналізаваць.
2. Тыхія аберанцы. Калі MONGO_URI не ўказана, працэс не зупіняецца пад час запуску. Ён зупіняецца тады, калі нарэшце выконуецца тая конкрэтная лінія, можа, чырвоны гады пасля запуску, які выглядаў нормальным.
3. Няма едынага адказвальнага джэрага. Новачак не мае спісу зменных, якія патрэбны прыложэнню. Іхня ўзельная апцыя — шукаты ў всім рэпазітарыі элементы process.env.

Едыны файл-контролер

Рашэнь — гэта перастаць змешчвацца з process.env у логіцы бізнесу. Одын модуль, які можна назваць env.ts, чытае настройкі сярэдовышча аднойчы пад запуск, пераканае іх і экспортуе об’ект з строгай тыпавалізацыяй. Усе інша імпортуе гэты об’ект.

Zod — бібліятэка для пераканання схемы, якая спачатку падтрымлеяе TypeScript, выканае гэта перакананне.

Інсталюйце яе

npm install zod

Запісаце схему

Размясціце модуль у src/config/env.ts і точнаяя, якім должна быць віда сераўнір.

import dotenv from 'dotenv';
import { z } from 'zod';

// Load variables from .env file (if in development)
dotenv.config();

// 1. Define the schema
const envSchema = z.object({
  PORT: z.string().transform(Number).default('3000'),
  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
  MONGO_URI: z.string(),
  JWT_SECRET: z.string(),
  JWT_EXPIRES_IN: z.string().default('1d'),
});

// 2. Parse the environment against the schema
const _env = envSchema.safeParse(process.env);

// 3. Fail fast if it's invalid
if (!_env.success) {
  console.error('Invalid environment variables:', _env.error.format());
  process.exit(1); // Crash the app immediately!
}

// 4. Export the typed, validated object
export const env = _env.data;

Што робіць модуль

• Ён задае вімаганні. MONGO_URI — гэта обавязковыя рэчыпы. PORT таксама ў віглядзе рэчыпа, і .transform(Number) перакладае яго, пры чым стандартны значэнне — 3000. NODE_ENV павінен быць аднім з трох дазволеных значэнняў.
• Ён быстра фіксуе адмову. safeParse запускаецца як толькі файл імпортуецца, таму імпортуйце яго на самым пачатку вашага пункта запуску, чыя бы то ні было app.ts або server.ts. Калі які-небудзь обавязковыя зменныя відсутнія або маюць некорэктную форму, рэзультат паведамляе пра адмову, выходныя даныя пра бягучую проблему паказваюць точна, што зайшло не так, а process.exit(1) зупіняе працэс перш чым ён пачне апрацоўваць запыты.
• Ён экспортуе об’ект з атрыбутамі. У разе успеху спрацоўвання, апрацаваныя даныя маюць тыпы, выведзеныя пры помочы Zod, таму env.PORT ужо ёсць чыслам.

З того моменту будзь-які файл можа імпортуваты env і вікорыстовуваты яго.

Што ві отрымуеце

• Автодоповнення. Пры введэнні env. у вашому рэдакторы відображаецца спіс усіх доступніх змінніх.
• Без розкіданіх альтэрнатыв. Шаблоні || "default_value" знікаюць з контролерыв, оскількі значэння за замовчуванням місцяцца у схемі.
• Вбудована документація. Схема ёсць точнім спіском того, што потрыбно для працы додатку, а таксама відповідае на запітання новачків шчодо того, што мае буты у файлі .env.

Відсутнісць секрэту цяпер запобігае розгортанню за секунды під час запуску з чыткім повідомленням, замест того шчоб проблема проявілася праз годыну у вігляды розлючэного корыстувача.