اعتبار سنجی متغیرهای محیط در node.js با ZOD

آیا تا به حال یک پروژه را به سمت تولید سوق داده اید که فقط برای تحقق یک متغیر محیط از دست رفته یا اشتباه گرفته شده است؟ من دارم و سرگرم کننده نبود.

به تازگی ، من در یکی از پروژه های Node.js ما به یک مسئله ظریف اما مکرر رسیدم: متغیرهای محیطی که به درستی از پرونده .env بارگیری نمی شوند. در نگاه اول ، این به نظر می رسید بی اهمیت است – فقط از dotenv استفاده کنید ، درست است؟ اما از آنجا که پیکربندی ما پیچیده تر شد ، مقادیر نامشخص در سکوت شروع به خزیدن کردند و ویژگی ها را بدون خطاهای واضح شکستند.

مشکل با Plan.Env + process.env

مانند بسیاری از تیم ها ، ما با این مجموعه ساده شروع کردیم:

import dotenv from "dotenv";
dotenv.config();

const CORE_DB_URI = process.env.CORE_DB_URI;

اما مسائل به سرعت جمع شدند:
• ما فراموش کردیم که برخی از متغیرها را در محیط های مرحله بندی یا dev تنظیم کنیم.
• Typos در نامهای متغیر تا زمان اجرا غافل می شوند.
• برخی از متغیرها مانند پورت نیاز به تجزیه (تجزیه) دارند ، در حالی که برخی دیگر دارای برگه های قابل توجهی بودند – از دیگهای بخار.

از همه بدتر ، ما هیچ راهی برای دانستن اینکه چه چیزی از دست رفته یا نامعتبر است تا زمانی که چیزی شکست خورده بود ، نداشتیم. این یک تجربه توسعه دهنده عالی نیست.

دستیابی به موفقیت: اعتبار سنجی محیط با ZOD

پس از برخی تحقیقات و آزمایشات و خطا ، ما یک روش بهتر را کشف کردیم-یک طرحواره برای متغیرهای محیط با استفاده از ZOD و تجزیه و تحلیل فرآیند.

در اینجا به نظر می رسد:

import z from "zod";

const envSchema = z.object({
  NODE_ENV: z.string().optional(),
  HOST: z.string().optional(),
  PORT: z.string().transform(val => parseInt(val)).optional(),

  MONGO_DB_URI: z.string().nonempty("MONGO_DB_URI is required"),
  // ... add other required vars

  AWS_ACCESS_KEY: z.string().nonempty("AWS_ACCESS_KEY is required"),
  SMTP_USERNAME: z.string().nonempty("SMTP_USERNAME is required"),
});

سپس لودر پیکربندی را مانند این به روز کردیم:

import dotenv from "dotenv";
import { envSchema } from "./envSchema";

dotenv.config();

let parsedEnv;
try {
  parsedEnv = envSchema.parse(process.env);
  console.log("✅ Environment validation passed");
} catch (err) {
  console.error("❌ Environment validation failed:");
  console.error(JSON.stringify(err.format?.(), null, 2));
  process.exit(1);
}

مزایایی که به دست آوردیم

این اصلاح کننده به ما پیروزی های فوری داد:
• اعتبارسنجی در هنگام راه اندازی: برنامه حتی اجرا نمی شود مگر اینکه همه Env VAR های مورد نیاز وجود داشته باشد.
• خطاهای مفید: هر متغیر گمشده اکنون یک پیام خطای واضح را نشان می دهد.
• هیچ ریخته گری ضمنی یا بررسی های تهی بیشتر: همه چیز معتبر و در جلو تغییر یافته است.
• کد پیکربندی پاک کننده: No More Process.env.xyz || “Fallback” در همه جا.

به جای این:
const CORE_DB_URI = process.env.CORE_DB_URI!;

اکنون از این استفاده می کنیم:
const config = {
CORE_DB_URI: parsedEnv.CORE_DB_URI,
};

سریع شکست می خورد ، نه در تولید

یک چیز که واقعاً مرا در این الگوی فروخته است
[https://www.youtube.com/watch?v=eZBsBMf5zuQ]
قبل از اینکه برنامه شما در تولید نادرست باشد ، چگونه مشکلات پیکربندی را در زمان اجرا جلب می کند.

بدون اعتبار سنجی طرحواره ، یک متغیر محیط گمشده ممکن است تا زمانی که از آن استفاده شود خطایی ایجاد نکند. دیر است در آن زمان ، ممکن است کاربران از قبل تحت تأثیر قرار بگیرند.

با استفاده از ZOD ، اگر یک متغیر محیط مورد نیاز از دست رفته یا غلط باشد ، برنامه شما حتی بوت نمی شود. این عمدی است شما در خط لوله های توسعه ، مرحله بندی یا CI خطای روشنی دریافت می کنید – نه پس از ارسال کد شکسته.

این ساده ، ایمن و تمیز است.

افکار نهایی

دست کم گرفتن اهمیت بهداشت پیکربندی آسان است – تا زمانی که چیزی را بشکند. استفاده از ZOD برای اعتبار سنجی طرحواره ، نوع ایمنی ، خطاهای معنی دار و کد پاک کننده را به شما می دهد. اکنون این الگویی است که من به هر پروژه جدی Node.js منتقل می کنم.

اگر هنوز فقط به فرآیند .env + متکی هستید ، سعی کنید آن را با اعتبار سنجی ببندید. خود آینده و تیم شما – از شما متشکرم.