دليل NanoFlags بالعربية

ما هو NanoFlags

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

يُقيَّم العلم محليًا وبشكل متزامن داخل تطبيقك عبر حزمة @nanoflags/sdk: تحتفظ الحزمة بالإعدادات المنشورة في الذاكرة وتجيب فورًا دون أي طلب شبكي. تُستخدم الشبكة في الخلفية فقط لتحميل الإعدادات واستقبال كل نشر جديد وإرسال عيّنة من بيانات القياس.

مصطلحات أساسية

نسب الإطلاق التدريجي حتمية: تُحسب الشريحة الرقمية لكل مستخدم بخوارزمية MurmurHash3 من مفتاح العلم (افتراضيًا) ومعرّف المستخدم key، فيحصل المستخدم نفسه على النتيجة نفسها في كل خادم وكل متصفح. التفاصيل في Rollout bucketing.

مسار النشر

في البيئات المحمية مثل Production يمرّ كل تعديل بالخطوات التالية. أما Development وStaging فيمكن النشر فيهما مباشرة من المسودة.

1. المسودة: عدّل قواعد العلم في مسودة البيئة. الحفظ لا يغيّر شيئًا لدى المستخدمين.
2. التغيير: أنشئ تغييرًا يحدّد الأعلام المعنية وسبب التعديل، ويمكن ربطه بمرجع في الشيفرة.
3. السيناريوهات: شغّل السيناريوهات المحفوظة على المسودة من لوحة التحكم أو من CI. يُشترط أن تنجح جميعها على المسودة نفسها التي ستُنشر؛ أي تعديل لاحق يتطلب تشغيلًا جديدًا.
4. الموافقة: يطلب صاحب التغيير الموافقة، ويوافق عليه مدير (admin) أو مالك (owner) غير صاحبه، وبالعدد المطلوب في إعدادات البيئة (من 1 إلى 5). الموافقة مرتبطة بالمسودة كما كانت لحظة إعطائها؛ أي تعديل بعدها يُبطلها ويتطلب موافقة جديدة.
5. النشر: تُنشر المسودة كنسخة جديدة. إذا سبقك أحد زملائك بنشر آخر يُرفض النشر برسالة DESTINATION_CHANGED بدل الكتابة فوق نسخته.
6. المراقبة: تستقبل التطبيقات المتصلة النسخة الجديدة فورًا عبر اتصال مباشر دون انتظار دورة استطلاع، وتُبلغ الخدمات عن النسخة التي تعمل بها. قياسات زمن الانتشار الحالية منشورة في صفحة الحالة.

البدء السريع

1. أنشئ حسابًا، ثم أدخل اسم مساحة العمل (workspace) واسم أول مشروع. يُنشأ المشروع ومعه ثلاث بيئات: Development وStaging وProduction المحمية.
2. من Flags → New flag أنشئ علمًا، وفعّله في مسودة Development. فعّل خيار client-exposed إذا كان المتصفح سيقرؤه.
3. من Settings → SDK & access keys أنشئ مفتاحًا لبيئة Development: مفتاح Server للخوادم أو Client للمتصفح. يظهر المفتاح مرة واحدة فقط، فاحفظه في مدير الأسرار.
4. ثبّت الحزمة وقيّم العلم مع قيمة احتياط صريحة:

npm install @nanoflags/sdk

import { createClient } from "@nanoflags/sdk";

const flags = createClient({
  sdkKey: process.env.NANOFLAGS_SDK_KEY!, // nf_srv_…
  baseUrl: "https://edge.nanoflags.io",
  service: "checkout-api",
});

await flags.ready(); // never rejects; check flags.status

// false is the fallback: returned when no configuration is available
const enabled = flags.boolean("checkout-v2", false, { key: user.id, region: "SA" });

flags.on("update", ({ revision, transport }) => console.log(`r${revision} via ${transport}`));

وفي React:

import { createClient } from "@nanoflags/sdk";
import { NanoFlagsProvider, useFlag } from "@nanoflags/sdk/react";

const client = createClient({ sdkKey: "nf_pub_…", baseUrl: "https://edge.nanoflags.io", service: "web" });

export function App({ user }: { user: { id: string } }) {
  return (
    <NanoFlagsProvider client={client} context={{ key: user.id }}>
      <Checkout />
    </NanoFlagsProvider>
  );
}

function Checkout() {
  const v2 = useFlag("checkout-v2", false);
  return v2 ? <NewCheckout /> : <OldCheckout />;
}

• مرّر دائمًا الخاصية key في السياق: هي هوية المستخدم التي يُحسب بها الإطلاق التدريجي، ومن دونها يُعامَل السياق كأنه خارج النسبة.
• أنشئ عميلًا واحدًا لكل عملية وأعد استخدامه، واستدعِ flags.close() عند الإغلاق.
• بعد ذلك انشر المسودة من Publish draft، وستصل النسخة الجديدة إلى الحدث update.

الدليل الكامل خطوة بخطوة: Quickstart. مرجع الحزمة: JavaScript SDK. وتتوفر حزم أصلية لـ Python وGo، وتستطيع اللغات الأخرى استخدام OFREP.

الأدوار والصلاحيات

تُطبَّق الصلاحيات في قاعدة البيانات نفسها لا في الواجهة فقط. لا يستطيع صاحب التغيير الموافقة على تغييره. التفاصيل في Roles and approvals.

المفاتيح

كل مفتاح يخص بيئة واحدة في مشروع واحد. هناك أربعة أنواع:

لا يخزّن NanoFlags إلا بصمة المفتاح (SHA-256)، لذلك لا يمكن عرضه مرة أخرى. لتدوير مفتاح: أنشئ بديلًا، وحدّث تطبيقك، ثم ألغِ القديم. يتوقف قبول المفتاح الملغى خلال دقيقة تقريبًا، لكن التطبيقات التي حمّلت الإعدادات تواصل التقييم بآخر نسخة لديها. التفاصيل في Keys and scopes وCI keys.

ماذا تعني الإشارات المُبلَّغ عنها

تميّز لوحة التحكم بوضوح بين أربع حالات، ولا تصف أي إطلاق بأنه «آمن»:

• مسودة: ما تعدّله ولم يُنشر بعد.
• منشورة: النسخة التي تقدّمها الخدمة للبيئة الآن.
• مُبلَّغ عنها: عملية واحدة على الأقل تستخدم مفتاح هذه البيئة قالت إنها حمّلت النسخة N. هذا لا يثبت أن كل النسخ العاملة من خدمتك استقبلتها، ولا أن الخدمة سليمة.
• غير معروفة: لا يوجد بلاغ. غياب البلاغ لا يثبت شيئًا: قد يكون القياس معطّلًا أو محجوبًا أو خارج العيّنة.

افتراضيًا لا ترسل الحزمة أي قيم من سياق المستخدم، بل أسماء الخصائص التي تستخدمها قواعد العلم وأنواعها فقط، مثل { "region": "string" }. التفاصيل في What a reported signal proves.

المراجع التفصيلية

الحزم والأدوات

• JavaScript SDK: الخيارات والحالات وطرق النقل والتحقق من التوقيع.
• Python SDK وGo SDK: التثبيت والتقييم والتحديثات الحية والتحقق من التوقيع ومزوّد OpenFeature.
• OpenFeature (OFREP): أي لغة أخرى عبر مزوّد OFREP، مثل Java و.NET وPHP وRuby وSwift وKotlin.
• React وNode test sessions وOpenFeature.
• CLI وCI and GitHub Actions.

الواجهات والسياسات

• Edge HTTP API وManagement API وWebhooks.
• Security وPlans and limits.