حِزم SDK
SDK لغة Go
في هذه الصفحة
التثبيت
go get github.com/motazalmaroai/nanoflags-sdk/go@v0.2.0- الوحدة github.com/motazalmaroai/nanoflags-sdk/go بالإصدار v0.2.0. تتطلب Go 1.22 أو أحدث.
- الاعتماديات:
github.com/coder/websocket(التحديثات الحيّة) وgolang.org/x/text(تطبيع Unicode للطرح التدريجي). وكل ما عدا ذلك، بما فيه Ed25519، من المكتبة القياسية. - الحزمة
engineنقلٌ لمحرك NanoFlags. وهي مختبَرة على الحالات المشتركة المولَّدة من المحرك المرجعي (21,998 حالة تقييم) إضافة إلى حالات خاصة بـ Go، وتعطي النتائج نفسها التي تعطيها حزمتا جافاسكريبت وPython. - برخصة Apache-2.0. والشيفرة المصدرية في مستودع nanoflags-sdk.
البدء السريع
انسخ مفتاح خادم (nf_srv_…) من الإعدادات ← مفاتيح SDK (Settings → SDK keys) في لوحة التحكم واحفظه في متغير بيئة.
package main
import (
"context"
"log"
"os"
"time"
nanoflags "github.com/motazalmaroai/nanoflags-sdk/go"
)
func main() {
client, err := nanoflags.New(os.Getenv("NANOFLAGS_SDK_KEY"), nanoflags.WithService("checkout-api"))
if err != nil {
log.Fatal(err)
}
defer client.Close()
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if err := client.WaitForReady(ctx); err != nil {
log.Printf("flags not loaded yet (%v): evaluations return their fallbacks", err)
}
user := nanoflags.Context{"key": "user-42", "plan": "pro", "country": "SA"}
if client.BoolVariation("new-checkout", user, false) {
// ...
}
}أنشئ عميلًا واحدًا لكل مفتاح SDK عند البدء وشاركه بين الـ goroutines. والعنوان الأساسي افتراضيًا هو الحافة المستضافة https://edge.nanoflags.io. وأمثلة قابلة للتشغيل في go/examples.
السياقات
nanoflags.Context من النوع map[string]any. وقد تكون القيم نصوصًا أو قيمًا منطقية أو أرقامًا أو nil أو شرائح أو خرائط. و"key" هو الهوية الثابتة المستخدمة في الطرح بالنسب المئوية، وعادةً معرّف المستخدم أو الحساب. وتطابق قواعد الاستهداف كل خاصية أخرى.
ctx := nanoflags.Context{"key": account.ID, "plan": account.Plan, "beta": true, "seats": 12}
ranking := client.StringVariation("search-ranking", ctx, "relevance-v2")- لا يغادر السياق العملية لاتخاذ القرار. وانظر القياس لمعرفة ما ترسله بيانات التشخيص.
- مرّر
keyنفسه للمستخدم نفسه في كل مكان: يقع المفتاح نفسه في شريحة الطرح نفسها في Go وPython وجافاسكريبت ولوحة التحكم.
القراءات المُنمَّطة
انتبه إلى ترتيب الوسائط: مفتاح العلم، ثم السياق، ثم قيمة الاحتياط.
enabled := client.BoolVariation("new-checkout", user, false)
accent := client.StringVariation("accent", user, "blue")
limit := client.Float64Variation("rate-limit", user, 100)
layout := client.JSONVariation("layout", user, map[string]any{"cols": 3})
all := client.AllFlags(user) // map[string]any, records no telemetry| الدالة | تعيد |
|---|---|
BoolVariation(key, ctx, fallback bool) bool | القيمة المنطقية للعلم |
StringVariation(key, ctx, fallback string) string | القيمة النصية للعلم |
Float64Variation(key, ctx, fallback float64) float64 | القيمة الرقمية للعلم |
JSONVariation(key, ctx, fallback any) any | بيانات Go عادية: nil وbool وfloat64 وstring و[]any وmap[string]any |
…VariationDetail(key, ctx, fallback) | القيمة مع Detail، انظر التفاصيل والأسباب |
Evaluate(key, ctx, fallback any) Detail | نتيجة المحرك دون فحص للنوع |
AllFlags(ctx) · AllFlagsDetail(ctx) | كل أعلام الإعداد |
تحصل على قيمة الاحتياط عندما لم يُحمَّل إعداد بعد، أو لعلم مجهول (أو غير مكشوف للعميل مع مفتاح متصفح)، أو عندما يقدّم العلم نوعًا غير المطلوب. والعلم المعطّل ليس حالة احتياط: فهو يعيد قيمة off المضبوطة له.
التفاصيل والأسباب
on, detail := client.BoolVariationDetail("new-checkout", user, false)
log.Printf("%v reason=%s rule=%s revision=%d", on, detail.Reason, detail.RuleID, detail.Revision)
for _, step := range detail.Trace { // the same steps the dashboard shows
log.Printf("%-10s %s — %s", step.Kind, step.Title, step.Detail)
}config Configuration loaded — r63
rule Rule 01 matched — plan = pro
allocation Allocation evaluated — 25% rollout · key inside allocation (bucket 12.34)
result Returned true — Inside the 25% allocation.| الحقل | المعنى |
|---|---|
Value | القيمة المقدَّمة. |
Reason | rule_match، default (لم تطابق قاعدة)، off (العلم معطّل)، flag_not_found، error. والثوابت: nanoflags.ReasonRuleMatch وهكذا. |
RuleIndex · RuleID | القاعدة المطابقة (فهرس يبدأ من الصفر، و-1 عند عدم المطابقة). |
InRollout · Bucket | مؤشرات تُضبط للطرح بالنسب المئوية (الشريحة من 0 إلى 99.99). |
Revision | نسخة الإعداد التي جاءت منها النتيجة. |
Trace | []TraceStep بالحقول Kind وTitle وDetail. |
Error | لماذا كان Reason هو error (خطأ تقييم أو عدم تطابق نوع). |
التحديثات الحيّة وOnChange
يفتح العميل اتصال WebSocket واحدًا إلى GET /v1/live. وتدفع الحافة كل نسخة منشورة موقّعةً مسبقًا؛ فيتحقق منها العميل ويستبدلها ذرّيًا. ولا تحلّ إجابة HTTP أقدم محل نسخة مدفوعة أبدًا.
stop := client.OnChange(func(e nanoflags.ChangeEvent) {
if e.HasLatency {
log.Printf("now on r%d via %s, %v after commit", e.Revision, e.Transport, e.Latency)
}
})
defer stop()
client.OnError(func(err error) {
var nf *nanoflags.Error
if errors.As(err, &nf) {
log.Printf("nanoflags %s: %v", nf.Code, err)
}
})| الحقل | المعنى |
|---|---|
Revision · PreviousRevision | النسخة الجديدة والنسخة التي حلّت محلها (-1 للأولى). |
Checksum | بصمة الإعداد الجديد. |
Source | network أو store أو bootstrap |
Transport | live (مدفوعة) أو stream (مجلوبة بعد إشعار أحداث من الخادم) أو poll |
Latency · HasLatency | من الالتزام في قاعدة البيانات حتى هذا الحدث، للنسخ المدفوعة التي تحمل وقت التزامها. يقارن ساعة قاعدة البيانات بساعة هذا الجهاز. |
- تعمل الدوال المرتدة بالترتيب على goroutine واحدة للعميل: اجعلها قصيرة. وكلٌّ من
OnChangeوOnErrorوOnStatusيعيد دالة لإلغاء الاشتراك. - الاحتياط: ما دام تعذّر فتح اتصال، أحداث الخادم (
GET /v1/stream)، واستطلاعGET /v1/bundleمعETagكل 30 ثانية (وكل 5 دقائق كشبكة أمان أثناء سلامة الاتصال). وتتراجع محاولات إعادة الاتصال من ثانية واحدة حتى 5 دقائق مع تذبذب. وانظر وسائل النقل للبروتوكول.
الجاهزية والحالة
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if err := client.WaitForReady(ctx); errors.Is(err, nanoflags.ErrNotReady) {
// no configuration yet: evaluations return their fallbacks
}
client.Status() // nanoflags.StatusNotReady | StatusReady | StatusStale
client.Revision() // revision in use
client.Transport() // "live" | "stream" | "poll"
<-client.Ready() // closed once the first load has finishedWaitForReady(ctx)يعود بعد انتهاء التحميل الأول:nilعندما يكون إعداد قيد الاستخدام، وإلا السبب (*nanoflags.ErrorأوErrNotReadyأو خطأ السياق).StatusReady: الإعداد معروف أنه الحالي.StatusStale: إعداد قيد الاستخدام لكن لا يُعرف أنه الحالي (تعذّر الوصول إلى الحافة، أو استُعيد من المخزن، أو حُذفت البيئة).StatusNotReady: لا شيء محمَّل.- لا توقف الطلبات بانتظار الجاهزية: انتظر مرة واحدة عند البدء بمهلة قصيرة، ودع قيم الاحتياط تغطي الباقي.
آخر إعداد سليم والتهيئة المسبقة
الطلبات الفاشلة تُبقي الإعداد الحالي (StatusStale). والحزمة التي تفشل في التحقق، أو تحتاج محركًا أحدث، لا تحلّ محل المستخدمة أبدًا.
client, err := nanoflags.New(sdkKey,
nanoflags.WithStore(nanoflags.FileStore("/var/cache/app/flags.json")), // survives restarts
)
// Or start from a configuration you ship:
data, _ := os.ReadFile("flags-bootstrap.json")
client, err = nanoflags.New(sdkKey, nanoflags.WithBootstrapJSON(data))FileStoreيكتب ذرّيًا بالصلاحيات0600، فيستطيع التشغيل بعد إعادة البدء التقييم قبل الوصول إلى الحافة. ويُتحقق من النسخة المحفوظة مجددًا عند التحميل.WithStoreيقبل أيStore(Load(ctx)/Save(ctx, data)). وWithBootstrap(*engine.Bundle)يقبل حزمة محلَّلة.
التحقق من التوقيع
مع العنوان الأساسي الافتراضي، يُتحقق من توقيع Ed25519 لكل حزمة مقابل مفاتيح الإنتاج المضمّنة في الوحدة (OfficialSigningKeys) قبل استخدامها: عبر الاتصال الحي وعبر الاستطلاع ومن المخزن. وتُرفض الحزم غير الموقّعة. وتُحسب بصمة البايتات الموقّعة كما قدّمتها الحافة تمامًا.
require := true
client, err := nanoflags.New(sdkKey,
nanoflags.WithBaseURL("https://flags.internal.example"),
nanoflags.WithVerification(nanoflags.VerifyOptions{
PublicKeys: []nanoflags.JWK{{Kty: "OKP", Crv: "Ed25519", X: "…", Kid: "k1"}},
Require: &require,
}),
)- الحزمة الموقّعة بمعرّف مفتاح مجهول (تدوير مفاتيح) تجعل العميل يحمّل
GET /v1/keysمرة واحدة، ومرة في الدقيقة على الأكثر. - تُثبَّت الحزم على أول بيئة وُقّعت لها.
- على حافة أخرى يكون التحقق معطّلًا ما لم تضبطه. و
FetchKeys: trueيحمّل المفاتيح من تلك الحافة؛ والمفاتيح المثبّتة أقوى. وWithoutVerification()يعطّله. - النص القانوني والترويسات موصوفة في التواقيع.
جلسات الاختبار
تثبّت جلسة الاختبار المشتركة (بالإنجليزية)، التي تُنشأ في لوحة التحكم (السيناريوهات ← جلسة اختبار مشتركة، Scenarios → Shared test session)، لقطةً من الإعداد وسياقًا اصطناعيًا على رمز (nf_ts_…). والخدمة التي تتلقى الرمز في ترويسة x-nanoflags-session تقيّم على تلك اللقطة، بسياق الجلسة وقد غطّاه سياق الاستدعاء (والغلبة للاستدعاء)، لذلك الطلب وحده. وتحمل الأحداث المأخوذة كعيّنة من جلسة معرّفَها. وجلسات الاختبار المشتركة جزء من خطة Scale.
// net/http middleware: reads x-nanoflags-session and resolves the session once per request.
mux := http.NewServeMux()
mux.HandleFunc("/cart", func(w http.ResponseWriter, r *http.Request) {
flags := client.FlagsFor(r.Context()) // session-scoped while the session is active
v2 := flags.BoolVariation("checkout-v2", nanoflags.Context{"key": userID}, false)
// The next service joins the same session (or add nanoflags.SessionHeaders(r.Context())).
downstream := &http.Client{Transport: &nanoflags.SessionTransport{}}
req, _ := http.NewRequestWithContext(r.Context(), http.MethodGet, pricingURL, nil)
res, err := downstream.Do(req)
// …
})
http.ListenAndServe(":8080", nanoflags.SessionMiddleware(client)(mux))
// Anywhere else (queues, jobs, tests): carry the token in a context.Context.
ctx := nanoflags.WithSession(context.Background(), job.SessionToken)
client.FlagsFor(ctx).BoolVariation("checkout-v2", nanoflags.Context{"key": job.UserID}, false)
// Or resolve one explicitly.
s := client.Session(ctx, r.Header.Get(nanoflags.SessionHeader), nanoflags.SessionService("checkout-api"))
s.Active(); s.ID(); s.ExpiresAt(); s.Revision()| الواجهة | الوصف |
|---|---|
client.Session(ctx, token, opts...) *SessionEvaluator | تحلّ الجلسة (GET /v1/session) وتعيد مقيّمًا محصورًا فيها؛ ولا يحدّ ctx إلا مدة الانتظار. |
SessionEvaluator | دوال القراءة الخاصة بالعميل، ومعها Active() وID() وExpiresAt() وRevision(). |
SessionMiddleware(client, opts...) | func(http.Handler) http.Handler: يعمل المعالج داخل جلسة الطلب. |
client.FlagsFor(ctx, opts...) | مقيّم الطلب الذي ينتمي إليه ctx، يُحلّ مرة واحدة لكل طلب وعميل؛ وخارج الجلسة يتصرّف كالعميل. |
WithSession(ctx, token) | ctx وفيه token جلسةً حالية؛ والرمز الغائب أو المشوّه يُخرج من أي جلسة. |
CurrentSession(ctx) · SessionHeaders(ctx) | الرمز الحالي (أو "")؛ وhttp.Header فيه x-nanoflags-session داخل الجلسة، وإلا فارغ. |
SessionTransport{Base} | http.RoundTripper يضيف الترويسة إلى الطلبات الصادرة بسياق جلسة. |
SessionService(name) | يُرسل كـ X-NanoFlags-Service (افتراضيًا: WithService)؛ وقد تُقصر الجلسة على خدمات معيّنة. |
SessionHeader · IsSessionToken(s) | "x-nanoflags-session"؛ والرمز من 1 إلى 512 محرفًا ASCII قابلًا للطباعة. |
- تُسأل الحافة مرة واحدة لكل رمز وخدمة، ويتشارك المستدعون المتزامنون الطلب نفسه، ويُخزَّن الجواب مؤقتًا حتى تنتهي الجلسة. وتُتذكَّر الرموز المجهولة 15 ثانية، وعمليات البحث الفاشلة (المبلَّغ عنها عبر
OnErrorبالرمزsession) 3 ثوانٍ. - لا تفشل أبدًا: الرمز الغائب أو المشوّه أو المجهول أو المنتهي أو الملغى أو غير المسموح به يعود إلى الإعداد العادي، ويتصرّف المقيّم تمامًا كالعميل. وإن انتهت الجلسة أثناء الطلب تعيد
Active()القيمة false وتستمر التقييمات على الإعداد المنشور. ولا تغيّر نسخةٌ منشورة حديثًا ما تقيّمه جلسة نشطة. - تُمرَّر الجلسة المجهولة إلى الخدمات التالية مع ذلك: الخدمة التالية تقرّر بنفسها.
- تغيّر الجلسة اللقطة والسياق اللذين يستخدمهما التقييم فقط؛ فهي لا تمنح أي وصول إلى البيانات ولا يجوز استخدامها للتفويض. وحزم الجلسات غير موقّعة، فلا ينطبق عليها التحقق. والجلسة الملغاة تظل تعمل في عملية خزّنتها مؤقتًا حتى وقت انتهائها.
مزوّد OpenFeature
go get github.com/motazalmaroai/nanoflags-sdk/go/ofprovider@v0.1.0import (
"github.com/open-feature/go-sdk/openfeature"
nanoflags "github.com/motazalmaroai/nanoflags-sdk/go"
"github.com/motazalmaroai/nanoflags-sdk/go/ofprovider"
)
client, err := nanoflags.New(os.Getenv("NANOFLAGS_SDK_KEY"))
if err != nil {
log.Fatal(err)
}
_ = openfeature.SetProviderAndWait(ofprovider.New(client, ofprovider.WithCloseClient()))
of := openfeature.NewDefaultClient()
on, _ := of.BooleanValue(ctx, "new-checkout", false,
openfeature.NewEvaluationContext("user-42", map[string]any{"plan": "pro"}))- وحدة منفصلة (
github.com/motazalmaroai/nanoflags-sdk/go/ofproviderبالإصدار v0.1.0، وGo 1.24، وOpenFeature Go SDK v1.17)، فلا يعتمد الـ SDK نفسه على OpenFeature. - يبقى التقييم محليًا في العميل المغلَّف. ويصبح مفتاح الاستهداف هو
key. - الأسباب:
DISABLEDوDEFAULTوTARGETING_MATCHوSPLIT(الطرح التدريجي)، وERRORمعFLAG_NOT_FOUNDأوPROVIDER_NOT_READYأوTYPE_MISMATCHأوGENERAL. والمتغيّر هو معرّف القاعدة؛ وتحمل البيانات الوصفية للعلمrevision. - الأحداث:
PROVIDER_READYوPROVIDER_STALEوPROVIDER_ERROR، وPROVIDER_CONFIGURATION_CHANGEDمع مفاتيح الأعلام التي تغيّرت. - الخيارات:
WithCloseClient()يغلق عميل NanoFlags عند الإيقاف؛ وWithInitTimeout(d)يحدّ مدة التهيئة.
الخيارات
| الخيار | الافتراضي |
|---|---|
WithBaseURL(url) | https://edge.nanoflags.io |
WithService(name) | "unknown"، الاسم الذي تُبلغ به هذه العملية |
WithHTTPClient(*http.Client) | النقل الافتراضي (يحترم HTTPS_PROXY) |
WithPollInterval(d) · WithLivePollInterval(d) | 30 ث / 5 د (0 يعطّل الاستطلاع) |
WithLive(bool) · WithStreaming(bool) | true / true |
WithVerification(VerifyOptions) · WithoutVerification() | الحافة المستضافة: مفاتيح مضمّنة والتواقيع إلزامية؛ والحافات الأخرى: معطّل |
WithStore · WithBootstrap · WithBootstrapJSON | لا شيء |
WithEvents(EventsOptions) | 10 % من التقييمات، تُرسل كل 10 ث؛ وبلاغ خدمة كل 60 ث. وDisabled: true يعطّله. |
WithLogger(*slog.Logger) | يُهمَل |
رموز الأخطاء
تصل أعطال الخلفية إلى OnError كـ *nanoflags.Error له Code: network وunauthorized وhttp وinvalid_bundle وstore وconfig وsignature وsession وengine وenvironment_deleted. والتحديث الفاشل لا يغيّر الإعداد المستخدم أبدًا. والمعاني مطابقة لـ SDK جافاسكريبت.
القياس
يحمل الحدث المأخوذ كعيّنة أسماء الخصائص التي تستخدمها قواعد العلم مقرونة بنوعها ({"plan": "string"})، ولا يحمل قيمها افتراضيًا أبدًا. وEventsOptions.Redact يحلّ محل ذلك.
الإغلاق والإيقاف
client, err := nanoflags.New(sdkKey)
if err != nil {
log.Fatal(err)
}
defer client.Close() // idempotent; waits for every goroutine
// Before exiting a short job, send queued telemetry:
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()
_ = client.Flush(ctx)Close()يوقف الاتصال الحي والاستطلاع والقياس، وينتظر كل goroutine. واستدعاؤه أكثر من مرة آمن.- بعد
Close()يواصل التقييم العمل على آخر إعداد. Refresh(ctx)يعيد التحقق الآن؛ وFlush(ctx)يرسل القياس المنتظر الآن.
حل المشكلات
- كل تقييم يعيد قيمة الاحتياط. افحص الخطأ من
WaitForReadyوسجّلOnError. الرمزunauthorizedيعني أن المفتاح رُفض؛ ومع مفتاح متصفح (nf_pub_…) لا تُسلَّم إلا الأعلام المكشوفة للعميل. - ترتيب وسائط خاطئ. دوال القراءة في Go تأخذ
(key, ctx, fallback). أمّا حزمتا Python وجافاسكريبت فتأخذان قيمة الاحتياط قبل السياق. - خلف وسيط. النقل الافتراضي يحترم
HTTPS_PROXY؛ ومرّرWithHTTPClientلإعدادات TLS أو وسطاء مخصّصين. وإن حُجبت الترقية يستخدم العميل أحداث الخادم والاستطلاع، ويعرضTransport()القيمةstreamأوpoll. 403«error code: 1010» من طلبات HTTP الخاصة بك. ترفض الحافة بعض قيم User-Agent الافتراضية للمكتبات. ويرسل الـ SDK nanoflags-go/<version>، فلا يتأثر بذلك إلا الشيفرة التي تستدعي الحافة مباشرة (مثل طلبات OFREP أو السكربتات): اضبط هناك ترويسةUser-Agentوصفية.- الرمز
signature. لم تجتز حزمة التحقق فلم تُستخدم. ومعWithBaseURLمخصّص ثبّت مفاتيح تلك الحافة. - الرمز
engine. يحتاج الإعداد محرك تقييم أحدث منSupportedEngineVersion: حدّث الوحدة. - الرمز
environment_deleted. أغلقت الحافة الاتصال بالرمز4004. يتوقف العميل عن إعادة الاتصال ويُبقي آخر إعداد بحالةStatusStale؛ استبدل المفتاح.