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

حِزم SDK

OpenFeature ‏(OFREP): أي لغة

تتحدث NanoFlags بروتوكول OpenFeature للتقييم عن بُعد (OFREP) 0.4.0. يستطيع أي مزوّد OpenFeature OFREP قراءة أعلامك، بما في ذلك Go وPython وJava و.NET وPHP وRuby وSwift وKotlin وجافاسكريبت. ولا تحتاج إلى SDK من NanoFlags لهذه اللغات.

العنوان الأساسي والمفاتيح

  • العنوان الأساسي: https://edge.nanoflags.io. ويضيف المزوّد /ofrep/v1/... بنفسه.
  • المصادقة: مفتاح SDK الخاص بك، مرسلًا في Authorization: Bearer <key> أو في X-API-Key: <key>.
    • مفتاح الخادم (nf_srv_…): للخوادم. يقيّم كل أعلام بيئته.
    • مفتاح المتصفح (nf_pub_…): لتطبيقات الويب والجوال. لا يرى إلا الأعلام الموسومة client-exposed، وأي علم آخر يُجاب بـ FLAG_NOT_FOUND.
    • لا تضع مفتاح خادم في تطبيق متصفح أو جوال أبدًا.
  • النتائج نفسها كما في حِزم SDK: تقيّم الحافة على النسخة المنشورة الموقّعة الحالية لبيئتك، بمحرك التقييم نفسه الذي تستخدمه حِزم NanoFlags، فيحصل السياق نفسه على القيمة نفسها في الحالتين.
OFREP أم SDK أصلي؟
يرسل مزوّد OFREP طلب HTTP لكل تقييم (مزوّدو الخادم) أو لكل استطلاع (مزوّدو الويب والجوال). أمّا حِزم NanoFlags الأصلية فتحمّل الإعداد الموقّع مرة واحدة وتقيّم داخل العملية في أجزاء من المليون من الثانية مع تحديثات حيّة. في جافاسكريبت أو تايبسكريبت فضّل @nanoflags/sdk مع @nanoflags/openfeature-provider؛ وفي Python حزمة nanoflags؛ وفي Go SDK لغة Go؛ وفي Java و.NET وPHP وRuby حزم Java و.NET وPHP وRuby؛ وفي تطبيقات الجوال حزم React Native وFlutter وiOS وAndroid. ولكلٍّ منها مزوّد OpenFeature خاص. واستخدم OFREP لكل لغة أخرى.

البدء السريع

في كل الأمثلة، targetingKey هو الهوية المستخدمة في الطرح بالنسب المئوية، وعادةً معرّف المستخدم أو الحساب. وتطابق قواعدُ الاستهداف كلَّ خاصية أخرى.

Go

sh
go get github.com/open-feature/go-sdk/openfeature github.com/open-feature/go-sdk-contrib/providers/ofrep
go
import (
	"context"
	"os"

	"github.com/open-feature/go-sdk-contrib/providers/ofrep"
	"github.com/open-feature/go-sdk/openfeature"
)

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

sh
pip install openfeature-sdk openfeature-provider-ofrep
python
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)

للأعلام الرقمية التي تحمل أعدادًا صحيحة استخدم get_integer_value؛ فدالة get_float_value في مزوّد Python ترفض القيمة JSON ‏25.

Java

pom.xml
<dependency>
  <groupId>dev.openfeature</groupId>
  <artifactId>sdk</artifactId>
  <version>1.23.0</version>
</dependency>
<dependency>
  <groupId>dev.openfeature.contrib.providers</groupId>
  <artifactId>ofrep</artifactId>
  <version>0.0.2</version>
</dependency>
java
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;
import dev.openfeature.contrib.providers.ofrep.OfrepProvider;
import dev.openfeature.contrib.providers.ofrep.OfrepProviderOptions;
import dev.openfeature.sdk.*;
import java.util.Map;

OfrepProviderOptions options = OfrepProviderOptions.builder()
    .baseUrl("https://edge.nanoflags.io")
    .headers(ImmutableMap.of("Authorization", ImmutableList.of("Bearer " + System.getenv("NANOFLAGS_SERVER_KEY"))))
    .build();
OpenFeatureAPI.getInstance().setProviderAndWait(OfrepProvider.constructProvider(options));
Client client = OpenFeatureAPI.getInstance().getClient();

EvaluationContext ctx = new ImmutableContext("user-123", Map.of("region", new Value("US"), "plan", new Value("pro")));
boolean enabled = client.getBooleanValue("checkout-v2", false, ctx);

.NET

sh
dotnet add package OpenFeature
dotnet add package OpenFeature.Providers.Ofrep
csharp
using OpenFeature;
using OpenFeature.Model;
using OpenFeature.Providers.Ofrep;
using OpenFeature.Providers.Ofrep.Configuration;

var options = new OfrepOptions("https://edge.nanoflags.io")
{
    Headers = new Dictionary<string, string>
    {
        ["Authorization"] = $"Bearer {Environment.GetEnvironmentVariable("NANOFLAGS_SERVER_KEY")}",
    },
};
await Api.Instance.SetProviderAsync(new OfrepProvider(options));
var client = Api.Instance.GetClient();

var ctx = EvaluationContext.Builder()
    .SetTargetingKey("user-123")
    .Set("region", "US")
    .Set("plan", "pro")
    .Build();
var enabled = await client.GetBooleanValueAsync("checkout-v2", false, ctx);

جافاسكريبت: Node.js (مفتاح خادم)

sh
npm install @openfeature/server-sdk @openfeature/ofrep-provider
ts
import { OpenFeature } from "@openfeature/server-sdk";
import { OFREPProvider } from "@openfeature/ofrep-provider";

await OpenFeature.setProviderAndWait(
  new OFREPProvider({ baseUrl: "https://edge.nanoflags.io", headers: [["Authorization", `Bearer ${process.env.NANOFLAGS_SERVER_KEY}`]] }),
);
const client = OpenFeature.getClient();
const enabled = await client.getBooleanValue("checkout-v2", false, { targetingKey: "user-123", region: "US" });

جافاسكريبت: المتصفح (مفتاح متصفح)

sh
npm install @openfeature/web-sdk @openfeature/ofrep-web-provider
ts
import { OpenFeature } from "@openfeature/web-sdk";
import { OFREPWebProvider } from "@openfeature/ofrep-web-provider";

await OpenFeature.setContext({ targetingKey: "user-123", region: "US" });
await OpenFeature.setProviderAndWait(
  new OFREPWebProvider({
    baseUrl: "https://edge.nanoflags.io",
    headers: [["X-API-Key", "nf_pub_…"]], // browser keys are public by design
    pollInterval: 30_000,
  }),
);
const enabled = OpenFeature.getClient().getBooleanValue("checkout-v2", false);

يجلب مزوّد الويب كل الأعلام المكشوفة للعميل في طلب واحد ثم يقيّم محليًا. ويعيد الفحص كل pollInterval مع If-None-Match، فتجيب NanoFlags بـ 304 Not Modified ما لم يتغير شيء.

يوجد مزوّدون للغات أخرى أيضًا (PHP وRuby وSwift وKotlin/Android وغيرها). انظر منظومة OpenFeature. واضبط كلًّا منها بالعنوان الأساسي نفسه وترويسة المفتاح نفسها.

ما الذي تحصل عليه

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

تتضمن flagMetadata القيمة revision، أي النسخة المنشورة التي قُيّمت. وعند مطابقة قاعدة تتضمن أيضًا ruleIndex وruleId، وللطرح التدريجي inRollout. وعلم JSON قيمته null يعيد القيمة الافتراضية في شيفرتك.

ملاحظة عن الأعلام الموقوفة: مزوّدا Python وجافاسكريبت يعيدان قيمة الإيقاف للعلم، أمّا مزوّد Go فيعيد القيمة الافتراضية في شيفرتك.

الأخطاء

رمز الخطأمتىHTTP (علم واحد)
FLAG_NOT_FOUNDالعلم غير موجود، أو طلب مفتاح متصفح علمًا غير مكشوف للعميل404
TARGETING_KEY_MISSINGوصل العلم إلى طرح بنسبة مئوية والسياق بلا targetingKey400
INVALID_CONTEXTcontext ليس كائنًا، أو targetingKey ليس نصًّا400
PARSE_ERRORجسم الطلب ليس JSON400
TYPE_MISMATCHطلبت نوعًا مختلفًا عمّا يحمله العلم (يكتشفه المزوّد)، أو إعداد العلم لا يطابق نوعه400 / المزوّد
GENERALتعذّر تقييم العلم400

عند حدوث خطأ، يعيد المزوّد القيمة الافتراضية في شيفرتك مع رمز الخطأ. وعلى مستوى HTTP تجيب الحافة بـ:

  • 401 لمفتاح مفقود أو مجهول أو ملغى.
  • 403 لمفاتيح CI والمدير. استخدم مفتاح SDK.
  • 429 مع Retry-After عندما يتجاوز المفتاح 1,000 تقييم لكل 10 ثوانٍ في موقع واحد من مواقع Cloudflare. وتُحسب مفاتيح المتصفح لكل شبكة زائر. ويتوقف المزوّدون حتى الوقت المذكور في Retry-After.
  • 503 مع Retry-After إذا تعذّر تحميل الإعداد كليًا. وهذا نادر: تواصل الحافة تقديم آخر إعداد موقّع أثناء تعذّر الوصول إلى قاعدة البيانات.

HTTP الخام

sh
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"}}

curl -X POST https://edge.nanoflags.io/ofrep/v1/evaluate/flags \
  -H "X-API-Key: nf_pub_…" -H "Content-Type: application/json" \
  -d '{"context":{"targetingKey":"user-123"}}'
# {"flags":[{"key":"checkout-v2","value":false,"reason":"DEFAULT","variant":"default","metadata":{"revision":42}}, ...],
#  "metadata":{"revision":42,"environment":"production"}}   (header ETag: "…"; send it back as If-None-Match to get 304)

جرّبه الآن بمفتاح العرض العام: nf_pub_4ced72c484c4f388a900aeeaf81e130c110c11730d555dd8 (العلمان demo-new-checkout وdemo-accent).

الحدود

  • لا تُطبَّق جلسات الاختبار المشتركة (x-nanoflags-session) على تقييمات OFREP.
  • لا تُبلَّغ تقييمات OFREP كأحداث تقييم، فلا تظهر في رؤى استخدام الأعلام.
  • لا توجد قناة دفع (eventStreams). مزوّدو المتصفح يستطلعون دوريًا، والاستطلاع رخيص بفضل إجابات 304.