انتقل إلى المحتوى
NanoFlags
ابدأ مجانًا

كل المقالات

المدونة والأدلة

أعلام الميزات بأي لغة برمجة مع OpenFeature وOFREP

تتحدث NanoFlags بروتوكول OpenFeature للتقييم عن بُعد (OFREP 0.4.0)، فيستطيع أي مزوّد OFREP من OpenFeature قراءة أعلامك. متى تستخدمه، ومتى يكون SDK الأصلي خيارًا أفضل، وكيف تقابل النتائج الأسبابَ والمتغيّرات.

فريق هندسة NanoFlagsنُشر في 3 دقائق قراءة

نطوّر حِزم SDK أصلية لـ NanoFlags بلغات جافاسكريبت وتايبسكريبت وPython وGo. تحمّل هذه الحِزم الإعداد الموقّع مرة واحدة، وتتحقق منه، وتقيّم الأعلام داخل العملية مع تحديثات حيّة. وكتابة SDK بهذه الجودة وصيانته لكل لغة تستخدمها فرقك ليس أمرًا واقعيًا، لنا ولا لغيرنا. لذا بدلًا من ذيل طويل من الأغلفة الرقيقة، تطبّق NanoFlags معيارًا مفتوحًا له مزوّدون جاهزون بلغات كثيرة.

OpenFeature في فقرة واحدة

OpenFeature مواصفة مفتوحة لواجهات تقييم أعلام الميزات. يستدعي كودك عميلًا محايدًا (getBooleanValue("checkout-v2", false, context))، ويصل مزوّد (provider) ذلك العميلَ بنظام الأعلام. أمّا بروتوكول التقييم عن بُعد (OFREP) فهو جزء المعيار الذي يعرّف واجهة HTTP بسيطة لتقييم الأعلام عن بُعد، فيعمل مزوّد OFREP عام واحد لكل لغة مع أي نظام يتحدث البروتوكول.

ما الذي تطبّقه NanoFlags

  • OFREP 0.4.0 على الحافة: تقييم علم واحد (POST /ofrep/v1/evaluate/flags/{key}) وتقييم جماعي لكل علم يراه المفتاح (POST /ofrep/v1/evaluate/flags)، مع ETag و304 Not Modified للطلب الجماعي.
  • العنوان الأساسي https://edge.nanoflags.io؛ والمصادقة بمفتاح SDK الخاص بك في Authorization: Bearer … أو X-API-Key: ….
  • التقييم على النسخة المنشورة الموقّعة الحالية للبيئة، بمحرك التقييم نفسه الذي تستخدمه الحِزم الأصلية، فيحصل السياق نفسه على القيمة نفسها في الحالتين.
  • مفاتيح الخادم (nf_srv_…) تقيّم كل أعلام بيئتها. ومفاتيح المتصفح (nf_pub_…) لا ترى إلا الأعلام المكشوفة للعميل؛ وأي علم آخر يُجاب بـ FLAG_NOT_FOUND.

بدايتان سريعتان

بلغة Go، مع OpenFeature Go SDK ومزوّد OFREP الخاص به:

main.go
provider := ofrep.NewProvider("https://edge.nanoflags.io", ofrep.WithBearerToken(os.Getenv("NANOFLAGS_SERVER_KEY")))
if err := openfeature.SetProviderAndWait(provider); err != nil {
	panic(err)
}
client := openfeature.NewClient("checkout")

evalCtx := openfeature.NewEvaluationContext("user-123", map[string]any{"region": "US", "plan": "pro"})
enabled, _ := client.BooleanValue(context.Background(), "checkout-v2", false, evalCtx)

بلغة Python، مع openfeature-sdk وopenfeature-provider-ofrep:

app.py
import os
from openfeature import api
from openfeature.evaluation_context import EvaluationContext
from openfeature.contrib.provider.ofrep import OFREPProvider

key = os.environ["NANOFLAGS_SERVER_KEY"]
api.set_provider(OFREPProvider("https://edge.nanoflags.io", headers_factory=lambda: {"Authorization": f"Bearer {key}"}))
client = api.get_client()

ctx = EvaluationContext(targeting_key="user-123", attributes={"region": "US", "plan": "pro"})
enabled = client.get_boolean_value("checkout-v2", False, ctx)

أمثلة Java و.NET وNode.js والمتصفح في دليل OFREP؛ ومزوّدو PHP وRuby وSwift وKotlin وغيرها يُضبطون بالعنوان الأساسي وترويسة المفتاح نفسيهما. وفي الخلفية، يرسل كل مزوّد طلبًا كهذا:

HTTP خام
curl -X POST https://edge.nanoflags.io/ofrep/v1/evaluate/flags/checkout-v2 \
  -H "Authorization: Bearer $NANOFLAGS_SERVER_KEY" -H "Content-Type: application/json" \
  -d '{"context":{"targetingKey":"user-123","region":"US"}}'
# {"key":"checkout-v2","value":true,"reason":"TARGETING_MATCH","variant":"us","metadata":{"revision":42,"ruleIndex":0,"ruleId":"us"}}

الأسباب والمتغيّرات والبيانات الوصفية

يُبلغ OpenFeature عن سبب إرجاع القيمة لا عن القيمة وحدها. وتقابل NanoFlags نتائج التقييم كما يلي:

الأسباب والمتغيّرات
الحالةreasonvariant
العلم موقوف في هذه البيئةDISABLEDoff
العلم بلا قواعدSTATICdefault
لم تطابق أي قاعدةDEFAULTdefault
طابقت قاعدة ذات قيمة ثابتةTARGETING_MATCHمعرّف القاعدة
طابق طرح بنسبة مئويةSPLIT<rule id>:rollout أو <rule id>:otherwise

تحمل البيانات الوصفية للعلم دائمًا revision، أي النسخة المنشورة التي قُيّمت، وعند مطابقة قاعدة تحمل أيضًا ruleIndex وruleId. وبهذا تصبح إجابة OFREP قابلة للتتبع إلى إعداد محدد غير قابل للتغيير في سجل NanoFlags.

OFREP أم SDK أصلي؟

اختر عن وعي. مزوّد OFREP للخادم يرسل طلب HTTP لكل تقييم؛ ومزوّد الويب أو الجوال يجلب كل الأعلام المكشوفة للعميل في طلب واحد ثم يعيد الفحص على فترات (بتكلفة زهيدة بفضل 304). أمّا SDK الأصلي فيحمّل الإعداد مرة واحدة، ويقيّم في أجزاء من المليون من الثانية دون شبكة في المسار الحرج، ويستلم التغييرات عبر اتصال حيّ.

  • جافاسكريبت وتايبسكريبت: استخدم @nanoflags/sdk، مع مزوّد OpenFeature الخاص بنا إن أردت واجهة OpenFeature.
  • Python وGo: استخدم حزمتي Python وGo الأصليتين؛ ولكلٍّ منهما مزوّد OpenFeature خاص أيضًا.
  • كل لغة أخرى: استخدم مزوّد OFREP من OpenFeature لتلك اللغة.
SDK أصلي خلف واجهة OpenFeature
import { OpenFeature } from "@openfeature/server-sdk";
import { createClient } from "@nanoflags/sdk";
import { NanoFlagsProvider } from "@nanoflags/openfeature-provider";

const nanoflags = createClient({ sdkKey: process.env.NANOFLAGS_SDK_KEY!, baseUrl: "https://edge.nanoflags.io", service: "checkout-api" });
await OpenFeature.setProviderAndWait(new NanoFlagsProvider({ client: nanoflags }));

const enabled = await OpenFeature.getClient().getBooleanValue("checkout-v2", false, { targetingKey: user.id, region: "US" });

الحدود الحالية

  • لا قناة دفع عبر OFREP: مزوّدو المتصفح يستطلعون دوريًا، ومزوّدو الخادم يسألون مع كل تقييم.
  • لا تُطبَّق جلسات الاختبار المشتركة على تقييمات OFREP.
  • لا تُبلَّغ تقييمات OFREP كأحداث تقييم، فلا تظهر في رؤى استخدام الأعلام.
  • لكل مفتاح 1,000 تقييم لكل 10 ثوانٍ في كل موقع من مواقع الحافة (مفاتيح المتصفح تُحسب لكل شبكة زائر)؛ وبعدها تجيب الحافة بـ 429 مع Retry-After، فيتوقف المزوّدون مؤقتًا.

جرّبه دون حساب، بالمفتاح العام للعرض الحي في الصفحة الرئيسية (العلمان demo-new-checkout وdemo-accent):

sh
curl -X POST https://edge.nanoflags.io/ofrep/v1/evaluate/flags \
  -H "X-API-Key: nf_pub_4ced72c484c4f388a900aeeaf81e130c110c11730d555dd8" -H "Content-Type: application/json" \
  -d '{"context":{"targetingKey":"user-123"}}'
  • openfeature
  • ofrep
  • sdk
  • go
  • python
  • java
  • .net