استخدام متغيرات البيئة

الهدف

أعلِن إعدادًا مرة واحدة في حلّك — عنوان خدمة، صندوق بريد، مفتاح تشغيل — واترك بيئات التطوير والاختبار والإنتاج تجيب عنه كلٌّ بطريقتها، دون تعديل الحل بعد كل استيراد.

لماذا وُجد هذا

الحل المُرقَّى من التطوير إلى الاختبار إلى الإنتاج يُفترض أن يكون الحل نفسه. ومع ذلك فبعض ما يفعله لا بدّ أن يختلف من بيئة إلى أخرى: الخدمة التي يستدعيها، والعنوان الذي يرسل منه، وما إذا كانت ميزةٌ ما مفعّلة.

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

يقسم متغير البيئة الإعداد إلى نصفين:

• الإعلان — اسمه ونوعه ووصفه وقيمته الافتراضية. وهذا ملك الحل وينتقل معه.
• القيمة — إجابة هذه البيئة. وهي ملك البيئة ولا تغادرها أبدًا. فتصدير الحل لا يحملها، واستيراد الحل لا يستبدلها.

المتطلبات المسبقة

• أنت مسجَّل الدخول بصفة صانع، وقد اخترت حلًّا وبيئة.

الخطوات

إعلان متغير (في التطوير عادةً)

1. افتح حلّك واختر متغيرات البيئة من التنقل الجانبي.
2. اختر جديد.
3. أدخل اسم عرض (مثلًا عنوان API الفواتير). ويُملأ الاسم المنطقي أدناه ببادئة ناشرك — فيصير invoice_api_url هو par_invoice_api_url.
4. اختر نوعًا: نص أو رقم أو منطقي (true/false) أو JSON. وتُفحص أي قيمة تُعيَّن للمتغير مقابل هذا النوع، في أي بيئة كُتبت.
5. اكتب وصفًا. وهو هنا أجدر بالوقت من أكثر ما تبنيه: فمن يعيّن القيمة في الإنتاج ليس أنت في الغالب، والاسم وحده نادرًا ما يقول كيف تبدو القيمة الصحيحة.
6. أدخل — إن شئت — قيمة افتراضية، وهي ما يُستعمل حيثما لم تعيّن بيئةٌ قيمةً. اتركها فارغة لما لا افتراضي معقول له (سرٌّ، أو عنوان خاص بكل عميل)، ليكون المتغير غير المعيَّن ظاهر الغياب لا خاطئًا في صمت.
7. اختر حفظ.

تعيين قيمة هذه البيئة (في كل بيئة)

1. افتح متغيرات البيئة، ثم اختر صف المتغير (أو حدّده واختر تعيين القيمة).
2. أدخل القيمة التي ينبغي أن تستعملها هذه البيئة، واختر حفظ.
3. وللعودة إلى الافتراضي المعلَن، أفرغ المربع واحفظ. فذلك قرارٌ بذاته، وهو السبيل الوحيد للرجوع بعد تعيين قيمة مرة واحدة.

ويخبرك عمود القيمة الفعّالة بأي الحالات الثلاث كل متغير:

ما يقرأ	ما يعني
قيمة	هذه البيئة عيّنتها
قيمة، يليها (باستخدام الافتراضية)	لم يُعيَّن هنا شيء؛ يسري افتراضي الحل
غير معيَّنة	لا هذا ولا ذاك — لا شيء يجيب هذا المتغير هنا، وكل ما يقرأه لن يجد شيئًا

وغير معيَّنة هي الحالة التي يجب معالجتها قبل التشغيل الفعلي.

قراءة متغير من خطوة إضافة

في خطوة إضافة بلغة BS Lang، تُعيد getEnvironmentVariable("par_invoice_api_url") القيمة الفعّالة للبيئة التي تجري فيها الكتابة. وهذا ما يجعل نصًّا برمجيًّا واحدًا صحيحًا في كل مكان: فهو يسمّي الإعداد لا العنوان.

ويُقرأ المتغير غير المعيَّن سلسلةً فارغة، فالأفضل لنصٍّ يحتاجه أن يقول ذلك بدل أن يمضي:

if (getEnvironmentVariable("par_invoice_api_url") == "") {
    throwValidationError("عنوان API الفواتير غير مهيّأ في هذه البيئة.");
}

فغياب الإعداد خطأ تهيئة لا قيمة — والإخفاق الصريح هنا أرحم كثيرًا من إخفاق غامض في مكان آخر.

ما الذي يحدث خلف الكواليس

الإعلان مكوّنٌ من مكوّنات الحل كالجدول أو مجموعة الخيارات: يُتحقَّق منه مقابل مخطط منشور، ويقع في مساحة أسماء ناشرك، وينتقل في حزمة الحل. أما القيمة فتُخزَّن مقابل البيئة ولا تُكتب في حزمة أبدًا.

وعند الاستيراد إلى بيئة أخرى:

• المتغير الذي يصل لأول مرة يحلّ بقيمته الافتراضية المعلَنة وبلا قيمة؛
• والمتغير الموجود أصلًا يُحدَّث إعلانه — تسمية أُعيدت، أو افتراضي تغيّر، أو وصف صُحِّح — وتبقى قيمته كما عيّنتها تلك البيئة تمامًا.

والقاعدة الثانية هي ما وُجدت هذه الميزة كلها من أجله. فترقية حلٍّ إلى الإنتاج يجب ألّا تعيد توجيه الإنتاج في صمت إلى عنوان بيئة التطوير.

وإلغاء تثبيت الحل يزيل متغيراته بقيمها — فعند تلك النقطة لم يبقَ ما يُهيَّأ.

حل المشكلات

• «'…' is not a valid Number value.» (أو Boolean/JSON) — القيمة لا تطابق النوع المعلَن. وتُفحص عمدًا حيث تكتبها لا حيثما تُقرأ لاحقًا: فالنص الذي يكتشفها سيخفق بعيدًا عن الخطأ نفسه، وفي الإنتاج على الأرجح.
• غيّرتُ النوع فاختفت قيمتي. — لم تعد القيمة تناسب النوع الجديد، فمُسحت بدل أن تبقى شيئًا لا يقرؤه أحد. ويعود المتغير إلى افتراضيه ويُقرأ «غير معيَّن»، وهو ظاهر. عيّنها من جديد.
• استوردتُ الحل ولا يزال الإنتاج يعرض القيمة القديمة. — هذا هو السلوك المقصود: الاستيراد لا يستبدل أبدًا قيمة البيئة نفسها. غيّرها من لوحة تعيين القيمة في الإنتاج.
• وصلت قيمتي الافتراضية إلى الإنتاج ولم تصل قيمة التطوير. — مقصود أيضًا. فالافتراضي جزء من الإعلان وينتقل؛ أما القيمة فللبيئة ولا تنتقل.
• يقرأ النص سلسلة فارغة. — المتغير معلَن لكنه غير معيَّن في هذه البيئة، أو أن الاسم مكتوب خطأً. راجع عمود القيمة الفعّالة؛ فـغير معيَّنة تفصل بين الحالتين والخطأ الإملائي، إذ لا يظهر الأخير في القائمة أصلًا.
• «An environment variable named … already exists in this environment.» — الأسماء المنطقية فريدة داخل البيئة الواحدة. اختر اسمًا آخر، أو عدّل الموجود.

سيناريوهات ذات صلة

• إنشاء حل.
• تصدير حل.
• إضافة مكوّن إلى حل.