TypeScript Academy · درس

تحديد أنواع متغيرات البيئة

امنحوا process.env نوعًا دقيقًا تم التحقق منه

تحديد أنواع متغيرات البيئة درس مجاني في TypeScript Academy على CoddyKit. هذا هو الدرس 1 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في TypeScript Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة TypeScript Academy 4 دروس في المجموع.

مشكلة process.env

في Node، يُحدَّد نوع process.env على أنه Record<string, string | undefined>. وقد يكون أي متغير مفقودًا، كما أن كل القيم سلاسل نصية، لذا فإن الوصول الخام إليها غير آمن وغير مقيّد بالأنواع.

التصريح بواجهة Env مقيّدة بالأنواع

ابدأ بوصف الإعدادات التي يحتاج إليها تطبيقك فعليًا في صورة واجهة دقيقة، مع الأنواع الصحيحة والتمييز بين الحقول المطلوبة والاختيارية.

interface Env {
  PORT: number;
  NODE_ENV: "development" | "production";
  DATABASE_URL: string;
  DEBUG?: boolean; // optional
}

قراءة القيم الخام

تصل جميع القيم في صورة سلاسل نصية أو undefined. يجب قراءتها بحذر، لأن المفاتيح قد لا تكون موجودة ببساطة.

const rawPort = process.env.PORT; // string | undefined
const rawEnv = process.env.NODE_ENV; // string | undefined

المتغيرات المطلوبة مقابل الاختيارية

يجب أن تكون بعض المتغيرات موجودة حتى يعمل التطبيق، بينما تتوفر للمتغيرات الأخرى قيم بديلة مناسبة. يفشل المساعد الخاص بالقيم المطلوبة بوضوح عند غياب إحداها.

function required(name: string): string {
  const v = process.env[name];
  if (v === undefined) throw new Error("Missing env: " + name);
  return v;
}

تحليل الأرقام

تحتاج المتغيرات الرقمية إلى تحويل والتحقق من صحتها، لأن parseInt قد ينتج NaN. غلّف عملية التحليل بحيث تُرفض المدخلات غير الصالحة فورًا.

function num(name: string): number {
  const n = Number(required(name));
  if (Number.isNaN(n)) throw new Error(name + " is not a number");
  return n;
}

تحليل القيم المنطقية

تصل القيم المنطقية في صورة سلاسل نصية مثل "true". طبّعها صراحةً بدلًا من الاعتماد على اعتبار السلسلة غير الفارغة صحيحة.

function bool(name: string, def = false): boolean {
  const v = process.env[name];
  if (v === undefined) return def;
  return v === "true" || v === "1";
}

إنشاء الإعدادات المقيّدة بالأنواع

اجمع القيم التي حللتها في كائن واحد يطابق واجهة Env. ومن هذه النقطة فصاعدًا، يستخدم باقي التطبيق الإعدادات المقيّدة بالأنواع، ولا يصل إلى process.env مباشرةً.

const env: Env = {
  PORT: num("PORT"),
  NODE_ENV: required("NODE_ENV") as Env["NODE_ENV"],
  DATABASE_URL: required("DATABASE_URL"),
  DEBUG: bool("DEBUG"),
};

تقييد اتحادات السلاسل النصية

بالنسبة إلى المتغيرات التي لها مجموعة ثابتة من القيم، تحقّق من القيمة مقابل تلك المجموعة حتى لا تمر قيمة غير متوقعة على أنها من النوع الحرفي الخاطئ.

function oneOf<T extends string>(name: string, allowed: readonly T[]): T {
  const v = required(name) as T;
  if (!allowed.includes(v)) throw new Error(name + " invalid");
  return v;
}

توحيد الوصول

صدّر الكائن env الوحيد من وحدة واحدة. ويستورده كل مستهلك، فيحصل على تحديد كامل للأنواع ومكان واحد لتغيير منطق التحليل.

export const config = env;
// elsewhere: import { config } from "./config";

توسيع ProcessEnv (اختياري)

يمكنك التصريح بتوسعة وحدة لـNodeJS.ProcessEnv لتحديد نوع الوصول الخام، لكن كائن الإعدادات الذي جرى تحليله أكثر أمانًا، لأنه يتحقق من القيم ويحوّلها أيضًا.

// declare global { namespace NodeJS { interface ProcessEnv { PORT: string } } }

لماذا يتفوق كائن الإعدادات المقيّد بالأنواع

يوفر كائن الإعدادات الذي جرى تحليله والتحقق منه أنواعًا صحيحة (أرقامًا وقيمًا منطقية واتحادات)، ويضمن وجود المتغيرات المطلوبة، ويوفر استيرادًا واحدًا للتطبيق كله، بدلًا من عمليات القراءة غير الآمنة المتناثرة من process.env.

تحقق سريع

تحقق سريع من هذا الدرس.

مراجعة

صرّح بواجهة Env مقيّدة بالأنواع، ثم حلّل process.env باستخدام مساعدين يحوّلون القيم ويتحققون منها (الأرقام والقيم المنطقية واتحادات السلاسل النصية)، ويفشلون عند غياب المتغيرات المطلوبة. صدّر كائن config واحدًا مقيّدًا بالأنواع حتى لا يلمس التطبيق process.env الخام.

الأسئلة الشائعة

هل درس «تحديد أنواع متغيرات البيئة» مجاني؟

نعم — نص درس «تحديد أنواع متغيرات البيئة» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة TypeScript Academy، انتقل إلى CoddyKit PRO. تتضمن دورة TypeScript Academy 4 دروس في المجموع.

ماذا ستتعلم في «تحديد أنواع متغيرات البيئة»؟

امنحوا process.env نوعًا دقيقًا تم التحقق منه تتمرن على TypeScript Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ TypeScript Academy؟

لا تُشترط خبرة سابقة. TypeScript Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 1 من أصل 4.

كم من الوقت يستغرق درس «تحديد أنواع متغيرات البيئة»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس TypeScript Academy هذا؟

نعم. كل درس في TypeScript Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى TypeScript Academy