TypeScript Academy · درس

إعدادات تم التحقق منها بالمخطط

تحققوا من الإعدادات عند بدء التشغيل باستخدام مخطط

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

التحقق من الإعدادات عند بدء التشغيل

تؤدي مساعدات التحليل اليدوية الغرض، لكن المخطط يصرّح بالبنية والقواعد كاملةً في مكان واحد، ويتحقق منها عند بدء التشغيل، ويفشل فورًا قبل أن يبدأ التطبيق في استقبال الطلبات.

ماذا يعني الفشل الفوري

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

مخطط باستخدام zod

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

import { z } from "zod";
const EnvSchema = z.object({
  PORT: z.coerce.number().int().positive(),
  NODE_ENV: z.enum(["development", "production"]),
  DATABASE_URL: z.string().url(),
});

التحويل التلقائي المدمج

يمكن للمخططات تحويل السلاسل النصية إلى الأنواع الصحيحة تلقائيًا. إذ يحوّل z.coerce.number() القيمة "8081" إلى 8081، وبذلك تصبح سلاسل البيئة الخام أرقامًا فعلية بأمان.

// "8081" -> 8081 via z.coerce.number()

التحليل والفشل الفوري

يتحقق استدعاء parse من كل شيء. وإذا كانت أي قيمة غير صالحة، يرمي zod خطأً مفصلًا يمكنك تسجيله ثم إنهاء العملية، مما يوقف بدء التشغيل فورًا.

function loadConfig() {
  const result = EnvSchema.safeParse(process.env);
  if (!result.success) {
    console.error(result.error.format());
    process.exit(1);
  }
  return result.data;
}

استنتاج النوع

من أكبر الفوائد أن النوع الذي جرى التحقق منه يُشتق من المخطط باستخدام z.infer. فالمخطط هو مصدر الحقيقة الوحيد لكل من عمليات التحقق أثناء التشغيل والأنواع أثناء التصريف.

type Env = z.infer<typeof EnvSchema>;
// { PORT: number; NODE_ENV: "development" | "production"; DATABASE_URL: string }

أخطاء وصفية

يُبلغ المتحقق من المخطط عن الحقل الذي فشل والسبب بدقة، مثل: "PORT: يُتوقع رقم موجب". وتجعل الرسائل الواضحة تشخيص الإعدادات الخاطئة أمرًا سهلًا.

// e.g. { PORT: { _errors: ["Expected number, received nan"] } }

الحقول الاختيارية والافتراضية

تعبّر المخططات مباشرةً عن اختيارية الحقول وقيمها الافتراضية، فتزيل منطق القيم البديلة المكتوب يدويًا وتحافظ على جميع القواعد في تصريح واحد.

const Schema = z.object({
  LOG_LEVEL: z.enum(["info", "debug"]).default("info"),
  TIMEOUT_MS: z.coerce.number().optional(),
});

تحقق مرة واحدة، واستخدم في كل مكان

شغّل التحقق مرة واحدة عند بدء التشغيل، ثم صدّر الكائن الناتج المقيّد بالأنواع. ويمكن للشيفرة اللاحقة الوثوق بأن الإعدادات موجودة ومهيأة بصورة صحيحة.

export const config = loadConfig();

ما وراء البيئة: الملفات والوسائط

يمكن للمخطط نفسه التحقق من الإعدادات القادمة من ملف JSON أو من مصادر مدمجة، وليس من process.env فقط. فخطوة التحقق مستقلة عن مصدر القيم.

لماذا تتفوق المخططات على عمليات التحقق المخصصة

يوحّد المخطط التحقق وتحديد الأنواع، وينتج أخطاء غنية ومتسقة، ويدعم التحويل التلقائي والقيم الافتراضية، ويفشل فورًا، مستبدلًا عمليات التحقق اليدوية المتناثرة باستخدام if بتصريح واحد.

تحقق سريع

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

مراجعة

يصرّح مخطط الإعدادات (مثل zod) بالأنواع والقيود والتحويل التلقائي والقيم الافتراضية في مكان واحد، ويتحقق منها عند بدء التشغيل لكي يفشل فورًا مع أخطاء وصفية، كما يتيح لك استنتاج نوع الإعدادات باستخدام z.infer من مصدر الحقيقة الوحيد هذا.

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

هل درس «إعدادات تم التحقق منها بالمخطط» مجاني؟

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

ماذا ستتعلم في «إعدادات تم التحقق منها بالمخطط»؟

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

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

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

كم من الوقت يستغرق درس «إعدادات تم التحقق منها بالمخطط»؟

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

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

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

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

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