المدونة والأدلة
أعلام الميزات بأي لغة برمجة مع 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 الخاص به:
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:
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 وغيرها يُضبطون بالعنوان الأساسي وترويسة المفتاح نفسيهما. وفي الخلفية، يرسل كل مزوّد طلبًا كهذا:
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 نتائج التقييم كما يلي:
| الحالة | reason | variant |
|---|---|---|
| العلم موقوف في هذه البيئة | DISABLED | off |
| العلم بلا قواعد | STATIC | default |
| لم تطابق أي قاعدة | DEFAULT | default |
| طابقت قاعدة ذات قيمة ثابتة | 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 لتلك اللغة.
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):
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