إدارة البيئات والمتغيرات السرية في Apidog (Dev, Staging, Prod)

يواجه كل فريق واجهة برمجة تطبيقات (API) نفس المشكلة. الطلبات الأولى التي تنشئها تشير إلى خادم واحد، مع رمز مميز واحد يتم لصقه في الترويسة. ثم تظهر بيئة التدريج (Staging). ثم بيئة الإنتاج (Production). فجأة، تجد نفسك تقوم بتحرير عناوين URL يدويًا قبل كل تشغيل، ويقوم شخص ما باختبار نقطة نهاية الحذف (delete endpoint) على بيئة الإنتاج لأن عنوان URL الأساسي كان قديمًا. توجد متغيرات بيئة API للقضاء على هذا النوع من الأخطاء بالكامل، ويقوم Apidog بدمجها في صميم المنتج بدلاً من إضافتها كملحقات.

يوضح لك هذا الدليل كيفية إعداد بيئات التطوير (dev)، والتدريج (staging)، والإنتاج (prod) في Apidog، وتخزين الرموز المميزة (tokens) ومفاتيح API كمتغيرات بدلاً من سلاسل نصية ثابتة، والحفاظ على الأسرار الحقيقية بعيدًا عن السحابة باستخدام قيم محلية، وتمرير البيئات إلى التكامل المستمر (CI) عبر واجهة سطر الأوامر (CLI) الخاصة بـ Apidog. إذا كنت ترغب في الحصول على صورة أوسع لما يجب أن يتعامل معه عميل API مع إدارة البيئة والأسرار، فقد قمنا بتغطية ذلك بشكل منفصل. هنا ننتقل إلى الجانب العملي.

لماذا تتسبب عناوين URL والرموز المميزة الثابتة في مشاكل عند وجود بيئة ثانية

مع بيئة واحدة، يعمل التشفير الثابت بشكل جيد. يكون https://api.acmepay.dev موجودًا في كل طلب، ويوجد الرمز المميز الخاص بك في كل ترويسة تفويض (Authorization header)، ولا توجد مشاكل حتى الآن.

تبدأ المشاكل لحظة ظهور بيئة ثانية:

يحتاج كل طلب إلى التعديل لإعادة استهدافه. خمسون نقطة نهاية موجهة إلى بيئة التطوير تعني خمسين تعديلاً لعنوان URL لاختبار بيئة التدريج، ثم خمسين تعديلاً آخر للتبديل مرة أخرى. ستفوت واحدة.
تتسرب الرموز المميزة عبر الحدود. يتم حفظ مفتاح API للإنتاج الملصق في نص الطلب مع المشروع، ومشاركته مع الفريق، وتصديره مع المجموعة. منهجية تطبيق الاثني عشر عاملاً (Twelve-Factor App) صريحة بشأن هذا الأمر: تختلف الإعدادات بين عمليات النشر، ولا يختلف الكود، لذا فإن الإعدادات لا تنتمي أبدًا إلى الأثر الذي تشاركه.
تتوقف عمليات التشغيل عن أن تكون قابلة للتكرار. عندما يكون عنوان URL وبيانات الاعتماد موجودة داخل كل طلب، يصبح "تشغيل اختبارات الدخان (smoke tests) على بيئة التدريج" طقسًا يدويًا للبحث والاستبدال بدلاً من تبديل بنقرة واحدة.

الحل قديم ومثبت: افصل تعريف الطلب (الطريقة، المسار، الجسم، التأكيدات) عن سياق النشر (عنوان URL الأساسي، بيانات الاعتماد، المعرفات الخاصة بالبيئة). تبقى الطلبات متطابقة في كل مكان. يتغير السياق فقط.

كيف يقوم Apidog بنمذجة البيئات والمتغيرات

يقسم Apidog المشكلة إلى جزأين يعملان معًا.

**البيئة (environment)** هي سياق مسمى، مثل Dev أو Staging أو Prod. تحمل كل بيئة عنوان URL أساسيًا خاصًا بها (الخادم الذي تُرسل إليه الطلبات) ومجموعتها الخاصة من قيم المتغيرات. عند تبديل البيئة، يتم إعادة توجيه كل طلب في المشروع على الفور، كما تصف وثائق إدارة البيئة.

**المتغير (variable)** هو عنصر نائب مسمى (named placeholder) يمكنك الإشارة إليه كـ {{variable_name}} في أي مكان تُستخدم فيه قيمة: عناوين URL، معلمات الاستعلام، الترويسات، نصوص الطلبات، والسكريبتات. عند وقت التشغيل، يحل Apidog العنصر النائب مقابل البيئة النشطة والنطاقات الأخرى المستخدمة.

نطاقات المتغيرات وأيها يفوز

يحل Apidog المتغيرات عبر خمسة نطاقات. من الأقل إلى الأعلى أولوية: عمومي (global)، وحدة (module)، بيئة (environment)، بيانات (data)، ومحلي (local).

النطاق	أين يتواجد	الاستخدام النموذجي
عمومي (Global)	المشروع بأكمله، كل بيئة	ثوابت مثل `{{api_version}}`
وحدة (Module)	وحدة واحدة من المشروع	إعدادات لكل خدمة في مشروع الخدمات المصغرة
بيئة (Environment)	البيئة النشطة فقط	`{{base_url}}`, `{{auth_token}}`, `{{merchant_id}}`
بيانات (Data)	ملفات CSV/JSON خارجية في عمليات الاختبار	مدخلات الاختبار صفًا بصف
محلي (مؤقت) (Local (temporary))	طلب واحد أو تشغيل اختبار، ثم يختفي	رمز مميز مستخرج في منتصف السيناريو

ترتيب الأولوية مهم في الممارسة العملية. إذا قمت بتعريف {{auth_token}} كبديل عمومي (global fallback) فإنه يعمل في كل مكان، ولكن في اللحظة التي تُعرّف فيها بيئة Staging رمز {{auth_token}} الخاص بها، تفوز قيمة البيئة بينما تكون Staging نشطة. هذا هو بالضبط ما تريده: قيم افتراضية مشتركة في الأسفل، وتجاوزات خاصة بالبيئة في الأعلى. للحصول على شرح تفصيلي لكل نطاق، راجع دليلنا حول إتقان المتغيرات في Apidog.

هناك سلوك واحد يربك الناس: المتغيرات المحلية (local variables) مؤقتة بطبيعتها. إذا قمت بتعيين واحد في نص برمجي، فإنه يختفي عند اكتمال التشغيل. هذه ميزة للقيم المؤقتة (scratch values) داخل سيناريو الاختبار، وتعتبر خطأ في نموذجك الذهني إذا كنت تتوقع بقاءها. أي شيء تحتاجه غدًا يجب أن يكون في بيئة أو متغير عمومي.

إعداد بيئات التطوير، التدريج، والإنتاج في Apidog

إليك سير العمل لواجهة برمجة تطبيقات المدفوعات (payments API) مع ثلاثة عمليات نشر.

1. إنشاء البيئات الثلاث

افتح إدارة البيئة من الزاوية اليمنى العلوية للمشروع وأنشئ بيئة جديدة لكل عملية نشر. امنح كل واحدة اسمًا وعنوان URL أساسيًا:

Dev ← https://api-dev.acmepay.dev
Staging ← https://api-staging.acmepay.dev
Prod ← https://api.acmepay.com

حافظ على عناوين URL الأساسية مسبوقة بالبروتوكول وبدون شرطة مائلة في النهاية، لكي تتصل المسارات (paths) بشكل نظيف.

2. تعريف أسماء المتغيرات نفسها في كل بيئة

الاتساق هو كل الحيلة. تُعرّف كل بيئة نفس أسماء المتغيرات بقيم مختلفة:

المتغير	تطوير	تدريج	إنتاج
`{{auth_token}}`	رمز مميز للتطوير	رمز مميز للتدريج	رمز مميز للإنتاج
`{{merchant_id}}`	`mrc_test_449`	`mrc_stg_449`	`mrc_live_8821`
`{{webhook_secret}}`	سر التطوير	سر التدريج	سر الإنتاج

3. الإشارة إلى المتغيرات في الطلبات، وليس القيم الخام أبدًا

طلب إنشاء دفعة (charge) يبدو الآن هكذا في كل مكان:

POST /v1/charges
Authorization: Bearer {{auth_token}}

{
  "merchant_id": "{{merchant_id}}",
  "amount": 1999,
  "currency": "usd"
}

لا يظهر عنوان URL الأساسي على الإطلاق؛ يقوم Apidog بإضافة عنوان URL الأساسي للبيئة النشطة تلقائيًا. لا يوجد شيء في تعريف الطلب يسمي بيئة ما، وهذا ما يجعله قابلاً للنقل.

4. التبديل باستخدام المحدد

يوجد محدد البيئة في الزاوية اليمنى العلوية من نافذة Apidog. اختر Staging وسيتم حل كل طلب، وسيناريو اختبار، وسكريبت في المشروع مقابل عنوان URL الأساسي لبيئة التدريج وقيم متغيرات التدريج. لا يوجد تعديل، ولا بحث واستبدال. إذا كنت تفكر فيما يجب أن يكون في أي طبقة نشر، فإن مقارنتنا بين بيئات Sandbox مقابل Test تغطي كيفية تقسيم الفرق لها عادةً.

هل أتيت من Postman؟ بيئاتك الحالية تنتقل معك. يشرح دليل ترحيل Postman كيفية استيراد المجموعات والبيئات ببضع نقرات، بما في ذلك قيم المتغيرات.

الحفاظ على الأسرار محلية: القيم المشتركة مقابل القيم المحلية

هذا هو الجزء الذي تخطئ فيه معظم الفرق، وهو الجزء الذي يثبت فيه تصميم Apidog جدارته.

يمكن لكل بيئة ومتغير عمومي في Apidog أن يحمل قيمتين، كما هو موثق في مرجع المتغيرات:

**قيمة مشتركة (Shared value)**: متزامنة مع خوادم Apidog ومرئية لكل فرد في المشروع.
**قيمة محلية (Local value)**: مخزنة فقط في ذاكرة التخزين المؤقت لعميلك على جهازك. لا تتم مزامنتها مع السحابة أبدًا ولا يراها أعضاء الفريق الآخرون.

عندما توجد القيمتان معًا، يستخدم عميلك القيمة المحلية. لذا فإن النمط الآمن للأسرار بسيط:

قم بإنشاء المتغير، على سبيل المثال {{auth_token}}، في كل بيئة.
اترك القيمة المشتركة فارغة، أو عيّنها إلى عنصر نائب مثل SET_LOCALLY.
ضع الرمز المميز الحقيقي في القيمة المحلية على جهازك الخاص.

تتم مزامنة بنية المتغير مع الفريق. أما السر فلا. يقوم كل مهندس بإدخال بيانات اعتماده مرة واحدة، ويعمل كل طلب مشترك له على الفور. يتوافق هذا مع ورقة غش إدارة الأسرار من OWASP: قم بتحديد نطاق الأسرار بإحكام، وشاركها عبر قنوات محكومة، وأبعدها عن أي شيء يتم نسخه على نطاق واسع.

هناك تحذيران يستحقان المعرفة. القيم المحلية موجودة في ذاكرة التخزين المؤقت للعميل، لذا فإن مسح ذاكرة التخزين المؤقت لـ Apidog يحذفها، والانتقال إلى جهاز كمبيوتر محمول جديد يعني إعادة إدخالها. خصص خمس دقائق لذلك، وليس خمس ساعات من مراجعة الحوادث بسبب مزامنة مفتاح إنتاج مع اثني عشر شخصًا.

يمكنك أيضًا وضع علامة على بيئة كاملة على أنها خاصة بدلاً من مشتركة. بيئة Prod مرئية فقط للشخصين اللذين يقومان بالنشر هي إعداد مشروع، وتتراكم مع القيم المحلية للدفاع المتعمق.

استخدام البيئات في سيناريوهات الاختبار والتكامل المستمر (CI)

تنتقل البيئات مباشرة إلى سيناريوهات اختبار Apidog. قم ببناء سيناريو مرة واحدة (إنشاء دفعة، استطلاع الحالة، تأكيد التسوية)، ثم اختر البيئة التي ستشغله عليها في وقت التنفيذ. يصبح نفس السيناريو اختبار الدخان (smoke test) الخاص بالتطوير ومجموعة اختبار الانحدار (regression suite) لبيئة التدريج.

تقوم السكريبتات بقراءة وكتابة نفس النطاقات. يبدو المعالج اللاحق (post-processor) الذي يلتقط رمزًا مميزًا جديدًا من استجابة تسجيل الدخول بهذا الشكل:

const body = pm.response.json();
pm.environment.set("auth_token", body.access_token);

تحل الطلبات اللاحقة في السيناريو {{auth_token}} إلى القيمة الملتقطة. بالنسبة لأنماط مثل سحب معلمات الطلب إلى السكريبتات، راجع استرداد معلمات الطلب في سكريبتات ما قبل/بعد الطلب.

بالنسبة للتكامل المستمر (CI)، تأخذ واجهة سطر الأوامر (CLI) لـ Apidog البيئة كعلامة (flag):

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 637132 \
  -e 358171 \
  --env-var "auth_token=$STAGING_API_TOKEN"

تختار -e البيئة بواسطة المعرف (ID). لاحظ أن واجهة سطر الأوامر (CLI) تحل القيم المشتركة، وليس القيم المحلية لجهازك، وهذا سلوك صحيح: لا ينبغي أن تكون أسرارك الشخصية قابلة للوصول من عامل بناء (build agent) على أي حال. بدلاً من ذلك، قم بحقن بيانات الاعتماد الحقيقية في وقت التشغيل، باستخدام تجاوزات --env-var و --global-var على شكل key=value، أو --variables لتحميل ملف كامل. قم بتخزين الأسرار الفعلية في مخزن الأسرار الخاص بمزود CI الخاص بك (أسرار GitHub Actions، متغيرات GitLab CI) ومررها. لا يحتوي خط الأنابيب (pipeline) أبدًا على رمز مميز بنص عادي، وتدوير بيانات الاعتماد يعني تحديث سر CI واحد.

سير عمل الفريق الناتج عن هذا

بالنظر إلى كل ما سبق، فإن تقسيم العمل واضح:

**مشتركة، متزامنة (Shared, synced)**: أسماء البيئات، عناوين URL الأساسية، أسماء المتغيرات، القيم المشتركة للعناصر النائبة، سيناريوهات الاختبار.
**شخصية، محلية (Personal, local)**: رموز ومفاتيح كل مهندس كقيم محلية.
**مملوكة للتكامل المستمر (CI-owned)**: بيانات اعتماد خط الأنابيب في مخزن أسرار CI، محقونة عبر علامات CLI.

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

الأخطاء الشائعة التي يجب تجنبها

**إلزام (Committing) الرموز المميزة الحقيقية في القيم المشتركة.** الخطأ الأكثر شيوعًا على الإطلاق. إذا كان السر يحتاج إلى الوصول إلى زملاء الفريق، فإنه يمر عبر مدير كلمات مرور أو خزانة (vault)، وليس عبر متغير متزامن. قم بمراجعة قيمك المشتركة مرة واحدة؛ أي شيء يبدو وكأنه بيانات اعتماد حية يجب أن ينتقل إلى القيم المحلية ويتم تدويره.
**نسيان أي بيئة نشطة.** الذاكرة العضلية ترسل الطلبات قبل أن تتحقق العين من المحدد. اجعل العمليات المدمرة أكثر صعوبة في الخطأ: حافظ على Prod خاصة لعدد أقل من الأشخاص، وامنح المتغيرات الخاصة بالإنتاج فقط أسماء مميزة أو قيمًا مشتركة كعناصر نائبة بحيث يفشل تشغيل بيئة خاطئة بصوت عالٍ عند المصادقة بدلاً من النجاح بصمت.
**توقع بقاء المتغيرات المؤقتة.** المتغيرات ذات النطاق المحلي التي يتم تعيينها أثناء التشغيل تختفي عند انتهائه. قم بترقية أي شيء دائم إلى نطاق البيئة بشكل صريح في السكريبت الخاص بك.
**أسماء متغيرات مختلفة عبر البيئات.** إذا أطلق عليها التطوير {{token}} وأطلق عليها التدريج {{auth_token}}، فإن تبديل البيئات سيعطل نصف طلباتك. نفس الأسماء في كل مكان، قيم مختلفة فقط.
**بيئة عملاقة واحدة لكل شيء.** إذا كنت تضع dev_base_url و prod_base_url في بيئة واحدة، فقد أعدت بناء مشكلة التشفير الثابت بخطوات إضافية. بيئة واحدة لكل سياق نشر.

هل أنت مستعد لإعداد هذا؟ قم بتنزيل Apidog مجانًا، وأنشئ بيئاتك الثلاث، وانقل رمزك المميز الأول إلى قيمة محلية. يستغرق الأمر حوالي عشر دقائق لمشروع موجود.

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

كيف أحافظ على الأسرار خارج مشاريع Apidog المشتركة؟

قم بتخزينها كقيم محلية. كل متغير له قيمة مشتركة (متزامنة مع الفريق) وقيمة محلية (مخزنة مؤقتًا على جهازك فقط). اترك القيمة المشتركة كعنصر نائب واحتفظ بالرمز المميز الحقيقي محليًا. لعزل إضافي، قم بوضع علامة على البيئات الحساسة مثل Prod على أنها خاصة بحيث يراها أشخاص محددون فقط.

ما الفرق بين المتغيرات العمومية ومتغيرات البيئة؟

تنطبق المتغيرات العمومية على المشروع بأكمله بغض النظر عن البيئة النشطة؛ استخدمها للقيم التي لا تتغير أبدًا بين عمليات النشر، مثل سلسلة إصدار API. تنتمي متغيرات البيئة إلى بيئة واحدة وتفوز على المتغيرات العمومية عندما يحدد كلاهما نفس الاسم. يشرح دليل المتغيرات الخاص بنا جميع النطاقات الخمسة، بما في ذلك الوحدة والبيانات والمحلية.

لماذا ينجح اختباري في عميل Apidog ولكنه يفشل في التكامل المستمر (CI)؟

عادةً لأن العميل يحل القيم المحلية بينما واجهة سطر الأوامر (CLI) تحل القيم المشتركة. إذا كان رمزك المميز موجودًا فقط في قيمة محلية، فسترى واجهة سطر الأوامر متغيرًا فارغًا أو عنصرًا نائبًا. قم بتمرير بيانات الاعتماد صراحةً في خط الأنابيب باستخدام --env-var "auth_token=$YOUR_CI_SECRET" بحيث يوفر CI سرّه الخاص في وقت التشغيل.

هل يمكنني نقل بيئات Postman الخاصة بي إلى Apidog؟

نعم. يقوم Apidog باستيراد مجموعات وبيئات Postman مباشرة، مع الحفاظ على أسماء المتغيرات وقيمها سليمة، بحيث تستمر مراجع {{base_url}} في العمل بعد الترحيل. راجع القيم المستوردة بعد ذلك وانقل أي بيانات اعتماد حقيقية إلى قيم محلية، حيث يمكن لتصديرات Postman أن تحمل الأسرار كنص عادي.