کتابخانه‌ی استاندارد · سیستم و ابزار

محیط env

متغیرهای محیطی: خواندن با گونه‌ی درست، پرونده‌ی .env، نمایه‌ی اجرا و پوشاندن مقدارهای حساس.

واردسازی محیط

نام آرگومان‌ها شناسه‌ی خود کد است و معادل فارسی ندارد؛ گونه‌ها، کلیدواژه‌ها و نام بسته‌ها با معادل فارسی نوشته می‌شوند.

تنظیماتی مثل درگاه سرور، نشانی پایگاه داده و کلیدهای API بهتر است در متغیرهای محیطی باشند، نه در کد؛ همان روش «دوازده‌عاملی» پیکربندی سرویس‌ها. بسته‌ی محیط آن‌ها را با گونه‌ی درست و مقدار پیش‌فرض می‌خواند، رازها را برای لاگ می‌پوشاند، پرونده‌های .env را بارگذاری می‌کند، برای هر محیط پرونده‌ی خودش را برمی‌دارد و قالب‌های ${NAME} را پر می‌کند. برای مقدار خام یک متغیر سیستم عامل.متغیر محیطی کافی است؛ برای خواندن یا نوشتن پرونده‌های .env مثل داده و بی‌دست زدن به محیط بسته‌ی پرونده محیط را، و برای گزینه‌های خط فرمان بسته‌ی پرچم را ببینید.

«نمایه» می‌گوید برنامه در محیط توسعه، آزمایش یا تولید اجرا می‌شود. از SALAM_ENV خوانده می‌شود؛ اگر تعریف نشده یا خالی باشد، APP_ENV و بعد ENV امتحان می‌شوند و پیش‌فرض development است. نمایه مقدار را با حروف کوچک ولی در بقیه‌ی جهات همان‌طور که نوشته شده برمی‌گرداند. تولید است، توسعه است و آزمایش است نام‌های prod، dev و testing را هم می‌پذیرند، ولی بارگذاری نمایه نام را همان‌طور که هست به کار می‌برد، پس با SALAM_ENV=prod پرونده‌ی .env.prod را می‌خواند، نه .env.production.

اشتباه‌های رایج:

  • اعتماد به این‌که تابع‌های گونه‌دار مقدار را بررسی می‌کنند. دریافت صحیح برای abc و 12px هم مثل متغیری که نیست پیش‌فرض را می‌دهد، و دریافت منطقی فقط true، 1، yes، on و false، 0، no، off را با حروف کوچک می‌شناسد، پس DEBUG=True پیش‌فرض را می‌دهد.
  • انتظار این‌که پرونده‌ی .env برنده شود. بارگذاری و بارگذاری نمایه هرگز متغیری را که از قبل تعریف شده جایگزین نمی‌کنند، که در تولید همین درست است؛ بارگذاری اجباری و بارگذاری نقطه‌محیط جایگزین می‌کنند.
  • نوشتن رازها در لاگ. آن‌ها را از پوشاندن بگذرانید و پرونده‌های .env.local را بیرون از کنترل نسخه نگه دارید.

خواندن همه‌ی تنظیمات هنگام شروع

همه‌ی تنظیمات را یک بار و در یک تابع درون یک ساختار بخوانید. بقیه‌ی برنامه همان ساختار را می‌گیرد و خودش سراغ محیط نمی‌رود؛ این‌طور فهرست متغیرها یک جا می‌ماند و آزمودن کد آسان می‌شود. تنظیمات را هنگام شروع چاپ کنید، ولی رازها را اول از پوشاندن بگذرانید.

env-guide-config.salam
واردسازی محیط
واردسازی رشته

ساختار پیکربندی:
    همگانی میزبان: رشته = ""
    همگانی درگاه: صحیح۶۴ = ۰
    همگانی کارگرها: صحیح۶۴ = ۰
    همگانی اشکال زدایی: منطقی = نادرست
    همگانی نشانی پایگاه: رشته = ""
    همگانی کلید: رشته = ""
پایان

تابع خواندن پیکربندی(): پیکربندی:
    برگشت پیکربندی {
        میزبان = محیط.دریافت با پیش فرض("APP_HOST"، "127.0.0.1")،
        درگاه = محیط.دریافت صحیح("APP_PORT"، ۸۰۸۰)،
        کارگرها = محیط.دریافت صحیح("APP_WORKERS"، ۴)،
        اشکال زدایی = محیط.دریافت منطقی("APP_DEBUG"، نادرست)،
        نشانی پایگاه = محیط.دریافت با پیش فرض("APP_DB_URL"، "sqlite://app.db")،
        کلید = محیط.دریافت("APP_API_KEY")
    }
پایان

تابع ریشه:
    محیط.تنظیم("APP_PORT"، "9000")
    محیط.تنظیم("APP_DEBUG"، "yes")
    محیط.تنظیم("APP_API_KEY"، "sk-test-1234567890")
    محیط.حذف("APP_HOST")
    محیط.حذف("APP_WORKERS")
    محیط.حذف("APP_DB_URL")
    پ := خواندن پیکربندی()
    سرچاپ "گوش می‌دهد روی"، پ.میزبان + ":" + رشته.از عدد(پ.درگاه برگردان صحیح)
    سرچاپ "کارگرها:"، پ.کارگرها، "اشکال‌زدایی:"، پ.اشکال زدایی
    سرچاپ "پایگاه داده:"، پ.نشانی پایگاه
    سرچاپ "کلید API:"، محیط.پوشاندن(پ.کلید)
    اگر پ.کلید.طول() برابر ۰: سرچاپ "هشدار: APP_API_KEY تنظیم نشده است" پایان
پایان
خروجیگوش می‌دهد روی 127.0.0.1:9000 کارگرها: 4 اشکال‌زدایی: true پایگاه داده: sqlite://app.db کلید API: sk****90

پرونده‌ی .env چه چیزهایی می‌تواند داشته باشد

پرونده‌ی .env در هر خط یک NAME=value دارد. خط‌هایی که با # شروع شوند توضیح‌اند، export در ابتدای خط مجاز است تا همان پرونده در پوسته هم کار کند، و مقدار می‌تواند در نقل‌قول دوتایی یا تکی باشد. در مقدار بی‌نقل‌قول یا با نقل‌قول دوتایی، ${NAME} جایگزین می‌شود؛ نقل‌قول تکی متن را دقیقا همان‌طور که نوشته شده نگه می‌دارد.

env-guide-dotenv.salam
واردسازی محیط
واردسازی ورودی خروجی

تابع ریشه:
    ورودی خروجی.نوشتن پرونده(".env"، "# تنظیمات محلی\nexport APP_NAME=\"فروشگاه سلام\"\nAPP_PORT=8080\nAPP_URL=http://localhost:${APP_PORT}\nAPP_GREETING='سلام ${APP_NAME}'\nEMPTY=\n")
    محیط.تنظیم("APP_PORT"، "3000")
    سرچاپ "خوانده شد:"، محیط.بارگذاری(".env")
    سرچاپ محیط.دریافت("APP_NAME")
    سرچاپ محیط.دریافت("APP_PORT")
    سرچاپ محیط.دریافت("APP_URL")
    سرچاپ محیط.دریافت("APP_GREETING")
    سرچاپ محیط.دارد("EMPTY")، "[" + محیط.دریافت("EMPTY") + "]"، محیط.دریافت با پیش فرض("EMPTY"، "جایگزین")
پایان
خروجیخوانده شد: 4 فروشگاه سلام 3000 http://localhost:8080 سلام ${APP_NAME} true [] جایگزین

سه نکته: بارگذاری هیچ‌وقت متغیری را که از قبل تعریف شده عوض نمی‌کند، پس APP_PORT همان 3000 می‌ماند، و عددی که برمی‌گرداند فقط متغیرهایی را می‌شمارد که واقعا تنظیم کرده است. ${APP_PORT} درون پرونده مقدار خود پرونده را به کار می‌برد. و مقدار خالی تنظیم می‌شود ولی خالی است: دارد درست می‌گوید و دریافت با پیش فرض مقدار پیش‌فرض را می‌دهد.

یک دسته پرونده برای هر محیط

بارگذاری نمایه تا چهار پرونده را از یک پوشه می‌خواند و هر پرونده‌ی بعدی بر قبلی‌ها مقدم است: .env، .env.local، .env.<نمایه> و .env.<نمایه>.local. پرونده‌های اول و سوم را در مخزن بگذارید و پرونده‌های .local را، که مقدارها و رازهای خود هر برنامه‌نویس را دارند، بیرون از کنترل نسخه نگه دارید. متغیری که در محیط واقعی تعریف شده باشد باز هم بر همه‌ی پرونده‌ها مقدم است.

env-guide-profiles.salam
واردسازی محیط
واردسازی ورودی خروجی

تابع ریشه:
    ورودی خروجی.نوشتن پرونده(".env"، "DB_HOST=localhost\nLOG_LEVEL=debug\nCACHE=off\n")
    ورودی خروجی.نوشتن پرونده(".env.local"، "DB_HOST=127.0.0.1\n")
    ورودی خروجی.نوشتن پرونده(".env.production"، "DB_HOST=db.internal\nLOG_LEVEL=warn\n")
    ورودی خروجی.نوشتن پرونده(".env.production.local"، "LOG_LEVEL=error\n")
    محیط.تنظیم("SALAM_ENV"، "production")
    محیط.تنظیم("CACHE"، "on")
    سرچاپ "نمایه:"، محیط.نمایه()، محیط.تولید است()
    سرچاپ "بارگذاری شد:"، محیط.بارگذاری نمایه(".")
    سرچاپ "DB_HOST ="، محیط.دریافت("DB_HOST")
    سرچاپ "LOG_LEVEL ="، محیط.دریافت("LOG_LEVEL")
    سرچاپ "CACHE ="، محیط.دریافت("CACHE")
پایان
خروجینمایه: production true بارگذاری شد: 2 DB_HOST = db.internal LOG_LEVEL = error CACHE = on

این‌جا DB_HOST از .env.production می‌آید، LOG_LEVEL از .env.production.local، و CACHE همان on می‌ماند چون پیش از بارگذاری تنظیم شده بود. پرونده‌هایی که وجود ندارند بی‌خطا کنار گذاشته می‌شوند.

پر کردن یک الگو با متغیرها

گسترش در هر متنی ${NAME} را جایگزین می‌کند و ${NAME:-default} وقتی متغیر تعریف نشده یا خالی است مقدار پیش‌فرض را می‌گذارد. برای رشته‌های اتصال و مسیرهایی که بخشی از آن‌ها تنظیم‌پذیر است مناسب است. نام ناشناخته‌ی بدون پیش‌فرض رشته‌ی خالی می‌شود، پس متغیرهای مهم را اول با دارد بررسی کنید.

env-guide-expand.salam
واردسازی محیط

تابع ریشه:
    محیط.تنظیم("DB_USER"، "shop")
    محیط.تنظیم("DB_NAME"، "orders")
    محیط.حذف("DB_HOST")
    محیط.حذف("DB_PORT")
    الگو := "postgres://${DB_USER}@${DB_HOST:-localhost}:${DB_PORT:-5432}/${DB_NAME}"
    سرچاپ محیط.گسترش(الگو)
    محیط.تنظیم("DB_HOST"، "db.example.com")
    سرچاپ محیط.گسترش(الگو)
    سرچاپ محیط.گسترش("تعریف‌نشده: [${NOT_SET_ANYWHERE}]")
پایان
خروجیpostgres://shop@localhost:5432/orders postgres://shop@db.example.com:5432/orders تعریف‌نشده: []

دام‌ها

  • دریافت صحیح و دریافت اعشاری هم وقتی متغیر تعریف نشده یا خالی است پیش‌فرض را برمی‌گردانند و هم وقتی عدد نیست: abc و 12px هر دو پیش‌فرض را می‌دهند. اگر تنظیم نادرست باید برنامه را متوقف کند، متن را با دریافت بخوانید و با تبدیل.تجزیه عدد درون تلاش تجزیه کنید.
  • دریافت منطقی هر چیزی را که نشناسد نادرست می‌گیرد، مقدار پیش‌فرض هر چه باشد. به بزرگی و کوچکی حرف حساس است و فقط true، 1، yes و on را می‌پذیرد؛ TRUE و Yes نادرست‌اند.
  • بارگذاری مقدارهای موجود را نگه می‌دارد، بارگذاری اجباری آن‌ها را جایگزین می‌کند و بارگذاری نقطه‌محیط هم جایگزین می‌کند. وقتی محیط واقعی باید برنده باشد، که در تولید همین را می‌خواهید، بارگذاری را به کار ببرید.
  • تنظیم محیط همین برنامه و فرایندهایی را که بعدا اجرا می‌کند تغییر می‌دهد، نه پوسته‌ای را که برنامه را اجرا کرده است.

تابع‌ها

دریافت Get

تابع دریافت(name: رشته): رشته
مقدار متغیر، یا رشته‌ی خالی اگر تعریف نشده باشد؛ این‌جا متغیر خالی و تعریف‌نشده یکسان دیده می‌شوند.
env-Get.salam
واردسازی محیط

تابع ریشه:
    محیط.تنظیم("PORT"، "8080")
    محیط.تنظیم("DEBUG"، "true")
    محیط.تنظیم("RATIO"، "0.75")
    سرچاپ محیط.دریافت("PORT")، محیط.دارد("PORT")، محیط.دارد("NOPE")
    سرچاپ محیط.دریافت صحیح("PORT"، ۸۰)، محیط.دریافت صحیح("NOPE"، ۸۰)
    سرچاپ محیط.دریافت منطقی("DEBUG"، نادرست)، محیط.دریافت اعشاری("RATIO"، ۱.۰)
    سرچاپ محیط.دریافت با پیش فرض("HOST"، "localhost")
    محیط.حذف("PORT")
    سرچاپ محیط.دارد("PORT")
    محیط.تنظیم("API_KEY"، "sk-1234567890abcdef")
    سرچاپ محیط.پوشاندن("sk-1234567890abcdef")، محیط.دریافت پوشیده("API_KEY")
    محیط.تنظیم("NAME"، "سلام")
    سرچاپ محیط.گسترش("زبان ${NAME} روی درگاه ${PORT:-3000}")
پایان
خروجی8080 true false 8080 80 true 0.75 localhost false sk****ef sk****ef زبان سلام روی درگاه 3000

دریافت با پیش فرض GetOr

تابع دریافت با پیش فرض(name: رشته، def: رشته): رشته
مقدار متغیر، یا مقدار پیش‌فرض اگر تعریف نشده یا خالی باشد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: env-Get.salam

دارد Has

تابع دارد(name: رشته): منطقی
اگر متغیر تعریف شده باشد، حتی با مقدار خالی، درست برمی‌گرداند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: env-Get.salam

دریافت صحیح GetInt

تابع دریافت صحیح(name: رشته، def: صحیح۶۴): صحیح۶۴
مقدار متغیر به شکل عدد صحیح، یا پیش‌فرض اگر تعریف نشده، خالی یا عدد صحیح نباشد: abc و 12px پیش‌فرض را می‌دهند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: env-Get.salam

دریافت اعشاری GetFloat

تابع دریافت اعشاری(name: رشته، def: اعشار۶۴): اعشار۶۴
مقدار متغیر به شکل عدد اعشاری، یا پیش‌فرض اگر تعریف نشده، خالی یا عدد نباشد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: env-Get.salam

دریافت منطقی GetBool

تابع دریافت منطقی(name: رشته، def: منطقی): منطقی
مقدار به شکل منطقی: دقیقاً true، 1، yes یا on (با حروف کوچک، فاصله‌ی دو سر مجاز) درست و false، 0، no یا off نادرست حساب می‌شوند. هر چیز دیگری، و متغیری که تعریف نشده یا خالی است، پیش‌فرض را می‌دهد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: env-Get.salam

تنظیم Set

تابع تنظیم(name: رشته، value: رشته): منطقی
متغیر را برای همین برنامه و فرآیندهایی که پس از آن اجرا می‌کند تنظیم می‌کند؛ در صورت موفقیت درست برمی‌گرداند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: env-Get.salam

حذف Unset

تابع حذف(name: رشته): منطقی
متغیر را حذف می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: env-Get.salam

پوشاندن Mask

تابع پوشاندن(value: رشته): رشته
مقدار حساس را برای لاگ می‌پوشاند: مقداری بلندتر از هشت نویسه دو نویسه‌ی اول و آخرش را دور **** نگه می‌دارد، مقدار کوتاه‌تر همه ستاره می‌شود و مقدار خالی خالی می‌ماند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: env-Get.salam

دریافت پوشیده GetMasked

تابع دریافت پوشیده(name: رشته): رشته
مقدار متغیر را پوشیده برمی‌گرداند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: env-Get.salam

نمایه Profile

تابع نمایه(): رشته
نام نمایه‌ی اجرا با حروف کوچک، از SALAM_ENV، وگرنه APP_ENV، وگرنه ENV، وگرنه development.
env-Profile.salam
واردسازی محیط

تابع ریشه:
    محیط.تنظیم("SALAM_ENV"، "production")
    سرچاپ محیط.نمایه()، محیط.تولید است()، محیط.توسعه است()، محیط.آزمایش است()، محیط.آزمایشی است()
    محیط.تنظیم("SALAM_ENV"، "test")
    سرچاپ محیط.نمایه()، محیط.آزمایش است()
پایان
خروجیproduction true false false false test true

تولید است IsProduction

تابع تولید است(): منطقی
در نمایه‌ی production یا prod درست است.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: env-Profile.salam

توسعه است IsDevelopment

تابع توسعه است(): منطقی
در نمایه‌ی development یا dev درست است، که پیش‌فرض هم هست.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: env-Profile.salam

آزمایش است IsTest

تابع آزمایش است(): منطقی
در نمایه‌ی test یا testing درست است.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: env-Profile.salam

آزمایشی است IsStaging

تابع آزمایشی است(): منطقی
در نمایه‌ی پیش‌تولید (staging) درست است.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: env-Profile.salam

بارگذاری Load

تابع بارگذاری(path: رشته): صحیح
پرونده‌ی KEY=VALUE را بی‌تغییر دادن متغیرهای موجود بارگذاری می‌کند و ارجاع‌های ${NAME} را جایگذاری می‌کند. تعداد متغیرهایی را که تنظیم کرده برمی‌گرداند؛ پرونده‌ی ناموجود هیچ‌کدام را تنظیم نمی‌کند.
env-Load.salam
واردسازی محیط
واردسازی ورودی خروجی

تابع ریشه:
    ورودی خروجی.نوشتن پرونده(".env"، "DB_HOST=localhost\nDB_PORT=5432\n# توضیح\n")
    سرچاپ محیط.بارگذاری(".env")، محیط.دریافت("DB_HOST")
    محیط.تنظیم("DB_PORT"، "1")
    محیط.بارگذاری(".env")
    سرچاپ محیط.دریافت("DB_PORT")
    محیط.بارگذاری اجباری(".env")
    سرچاپ محیط.دریافت("DB_PORT")
    سرچاپ محیط.بارگذاری متن("A=1\nB=2")، محیط.دریافت("B")
    سرچاپ محیط.بارگذاری نقطه‌محیط(".env")
    ورودی خروجی.نوشتن پرونده(".env.test"، "MODE=testing\n")
    محیط.تنظیم("SALAM_ENV"، "test")
    سرچاپ محیط.بارگذاری نمایه(".")، محیط.دریافت("MODE")
پایان
خروجی2 localhost 1 5432 2 2 2 1 testing

بارگذاری اجباری Overload

تابع بارگذاری اجباری(path: رشته): صحیح
مثل بارگذاری، ولی متغیرهای موجود را هم با مقدار پرونده جایگزین می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: env-Load.salam

بارگذاری متن LoadText

تابع بارگذاری متن(text: رشته): صحیح
همان کار بارگذاری را از روی متن به‌جای پرونده انجام می‌دهد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: env-Load.salam

بارگذاری نقطه‌محیط LoadDotEnv

تابع بارگذاری نقطه‌محیط(path: رشته): صحیح
پرونده‌ی داده‌شده را بارگذاری می‌کند و مثل بارگذاری اجباری متغیرهای موجود را جایگزین می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: env-Load.salam

بارگذاری نمایه LoadProfile

تابع بارگذاری نمایه(dir: رشته): صحیح
.env، .env.local، .env.<نمایه> و .env.<نمایه>.local را از پوشه‌ی داده‌شده بارگذاری می‌کند، به‌طوری که پرونده‌های بعدی برنده‌اند، و متغیرهای موجود را جایگزین نمی‌کند. پرونده‌های ناموجود کنار گذاشته می‌شوند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: env-Load.salam

گسترش Expand

تابع گسترش(text: رشته): رشته
${نام} و ${نام:-پیش‌فرض} را در متن با مقدار متغیرها جایگزین می‌کند؛ نام ناشناخته‌ی بی‌پیش‌فرض خالی می‌شود.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: env-Get.salam