استفاده از متغیرهای محیط
هدف
یک تنظیم را یک‌بار در راه‌حل خود اعلام کنید — نشانی یک سرویس، یک صندوق پستی، یک کلید روشن/خاموش — و بگذارید توسعه، آزمون و تولید هر کدام به شیوهٔ خود به آن پاسخ دهند، بی‌آنکه پس از هر واردسازی راه‌حل را دستکاری کنید.
چرا چنین چیزی لازم است
راه‌حلی که از توسعه به آزمون و سپس به تولید ارتقا می‌یابد قرار است همان راه‌حل باشد. با این حال بخشی از کاری که می‌کند ناچار باید در هر محیط فرق کند: سرویسی که فرا می‌خواند، نشانی‌ای که از آن ارسال می‌کند، اینکه یک قابلیت روشن باشد یا نه.
بدون متغیرهای محیط تنها دو راه برای بیان این تفاوت هست و هر دو بد است. می‌توانید پس از هر واردسازی اجزا را ویرایش کنید — که محیط‌ها را بی‌سروصدا از هم دور می‌کند و همین دور شدن را هم پنهان می‌کند. یا می‌توانید مقدار محیط توسعه را ثابت بنویسید و به یاد بسپارید که عوضش کنید — که تا روزی کار می‌کند که کسی به یاد نیاورد.
متغیر محیط، تنظیم را به دو نیم می‌کند:
- اعلان — نام، نوع، توضیح و پیش‌فرض. این از آنِ راه‌حل است و همراه آن جابه‌جا می‌شود.
- مقدار — پاسخِ همین محیط. این از آنِ محیط است و هرگز از آن بیرون نمی‌رود. صادر کردن راه‌حل آن را نمی‌برد و وارد کردن راه‌حل آن را بازنویسی نمی‌کند.
پیش‌نیازها
- به‌عنوان سازنده وارد شده‌اید و یک راه‌حل و یک محیط را برگزیده‌اید.
گام‌ها
اعلام یک متغیر (معمولاً در محیط توسعه)
- راه‌حل خود را باز کنید و در ناوبری کناری متغیرهای محیط را برگزینید.
- جدید را انتخاب کنید.
- یک نام نمایشی وارد کنید (برای نمونه،
نشانی API فاکتور). نام منطقی در پایین با پیشوند ناشر شما پر می‌شود —invoice_api_urlبهpar_invoice_api_urlتبدیل می‌شود. - یک نوع برگزینید: متن، عدد، بولی (
true/false) یا JSON. هر مقداری که برای متغیر تعیین شود — در هر محیطی که تایپ شود — با همین نوع سنجیده می‌شود. - یک توضیح بنویسید. اینجا بیش از بیشتر چیزهایی که می‌سازید ارزش وقت گذاشتن دارد: کسی که مقدار را در تولید تعیین می‌کند اغلب شما نیستید، و نامِ تنها به‌ندرت می‌گوید مقدار درست چه شکلی است.
- در صورت تمایل یک مقدار پیش‌فرض وارد کنید — آنچه هر جا محیطی مقداری تعیین نکرده باشد به کار می‌رود. برای چیزی که پیش‌فرض معقولی ندارد (یک راز، نشانی ویژهٔ هر مشتری) آن را خالی بگذارید تا متغیرِ تعیین‌نشده آشکارا تعیین‌نشده باشد، نه بی‌سروصدا نادرست.
- ذخیره را انتخاب کنید.
تعیین مقدارِ این محیط (در هر محیط)
- متغیرهای محیط را باز کنید، روی سطر متغیر کلیک کنید (یا آن را برگزینید و تعیین مقدار را انتخاب کنید).
- مقداری را که این محیط باید به کار ببرد وارد کنید و ذخیره را برگزینید.
- برای بازگشت به پیش‌فرض اعلام‌شده، کادر را خالی کنید و ذخیره کنید. این خودش یک تصمیم است، و پس از آنکه یک‌بار مقداری تعیین شد تنها راه بازگشت همین است.
ستون مقدار مؤثر می‌گوید هر متغیر در کدام یک از سه حالت است:
| چه می‌خوانید | یعنی چه |
|---|---|
| یک مقدار | این محیط آن را تعیین کرده است |
| یک مقدار، سپس (با مقدار پیش‌فرض) | اینجا چیزی تعیین نشده؛ پیش‌فرض راه‌حل به کار می‌رود |
| تعیین نشده | هیچ‌کدام — اینجا چیزی به این متغیر پاسخ نمی‌دهد و هر چه آن را بخواند چیزی نمی‌یابد |
تعیین نشده همان حالتی است که باید پیش از راه‌اندازی برطرف شود.
خواندن یک متغیر از یک گام افزونه
در یک گام افزونهٔ 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.» — نام‌های منطقی درون هر محیط یکتا هستند. نام دیگری برگزینید، یا همان متغیر موجود را ویرایش کنید.