> ## Content Index
> Fetch the complete content index at: https://arabroot.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# معيار OpenFeature: بدل الأداة دون تغيير كود التطبيق
- URL: https://arabroot.io/articles/معيار-openfeature-بدل-الاداة-دون-تغيير-كود-التطبيق/
- Published: 2026-11-05T16:29:22.000Z
- Updated: 2026-11-05T17:25:24.000Z
- Description: نشغل كود متجر واحد على Unleash ثم على Flagsmith عبر OpenFeature، ونرى ما يوحده المعيار وما يتركه لكل مزود، ومنه فرق غير سعر الشحن لأفضل العملاء.
- Author: فريق عرب رووت
- Tags: الأدلة التقنية, DevOps والتشغيل, DevOps وCI/CD, الاستضافة الذاتية

في مراجعة نهاية الربع سأل المدير التقني لفريق المتجر الإلكتروني سؤالاً بسيطاً: جربنا [Unleash](https://arabroot.io/articles/unleash-%D8%B9%D9%84%D9%89-%D8%B3%D9%8A%D8%B1%D9%81%D8%B1%D9%83-%D8%A7%D9%84%D8%A7%D8%B7%D9%84%D8%A7%D9%82-%D8%A7%D9%84%D8%AA%D8%AF%D8%B1%D9%8A%D8%AC%D9%8A-%D9%85%D8%B9-kill-switch/) ثم [Flagsmith](https://arabroot.io/articles/flagsmith-%D9%84%D9%84%D8%A7%D8%B9%D8%AF%D8%A7%D8%AF%D8%A7%D8%AA-%D8%B9%D9%86-%D8%A8%D8%B9%D8%AF-remote-config-%D8%AF%D9%88%D9%86-%D9%86%D8%B4%D8%B1/) ثم [GrowthBook](https://arabroot.io/articles/%D9%82%D9%8A%D8%A7%D8%B3-%D8%A7%D8%AB%D8%B1-%D8%A7%D9%84%D9%85%D9%8A%D8%B2%D8%A9-%D9%85%D8%B9-growthbook-%D8%A7%D9%84%D8%A7%D9%8A%D8%B1%D8%A7%D8%AF-%D9%88%D9%85%D9%82%D8%A7%D9%8A%D9%8A%D8%B3-%D8%A7%D9%84%D8%AD%D9%85%D8%A7%D9%8A%D8%A9/)، وكل واحدة منها لها SDK بأسماء دوال مختلفة، فإذا اخترنا واحدة اليوم وغيرت ترخيصها غداً، أو كبرنا عليها، أو أردنا أن نجمع اثنتين، فكم سطراً في المتجر سوف نعدل؟ والسؤال ليس نظرياً، فمع الإصدار 8 في يونيو 2026 نقلت Unleash كودها المصدري إلى AGPLv3، وفي 2023 غيرت HashiCorp ترخيص Terraform كما شرحنا في [Terraform أم OpenTofu](https://arabroot.io/articles/terraform-%D8%A7%D9%85-opentofu-%D9%82%D8%B5%D8%A9-%D8%AA%D8%BA%D9%8A%D9%8A%D8%B1-%D8%A7%D9%84%D8%AA%D8%B1%D8%AE%D9%8A%D8%B5/)، والفرق التي كانت قد كتبت كودها على أداة واحدة دفعت ثمن التغيير بنفسها.

وجواب هذه المشكلة معيار مفتوح اسمه OpenFeature، شرحنا فكرته وأجزاءه في [مقال المفهوم](https://arabroot.io/articles/%D9%85%D9%81%D9%87%D9%88%D9%85-feature-flags-%D9%88%D8%A7%D9%84%D8%A7%D8%B7%D9%84%D8%A7%D9%82-%D8%A7%D9%84%D8%AA%D8%AF%D8%B1%D9%8A%D8%AC%D9%8A-gradual-rollout/#openfeature)، واستخدمناه هناك مع Flagsmith وحده. والوعد الذي يقدمه أن كودك يكلم OpenFeature، وملف واحد يعرف الأداة، فتغيير الأداة تغيير ملف واحد. وفي هذا المقال نختبر الوعد كما يختبر أي وعد: نكتب كود المتجر مرة واحدة، ونشغله على Unleash ثم على Flagsmith بالقواعد نفسها، ونقارن ما يخرج سطراً بسطر. وسوف نناقش في هذا المقال ما يلي:

- لماذا يحتاج الفريق إلى معيار بين كوده وأداة ال Flags، وما الذي يوحده المعيار فعلاً وما الذي يتركه لكل مزود.
- تجربة عملية: الأعلام الأربعة نفسها في Unleash 8.3.1 وFlagsmith 2.288.2، وكود واحد يقرؤها عبر مزودين رسميين.
- سبعة فروق ظهرت بين المزودين للاستدعاء نفسه، منها فرق غير سعر الشحن لعملاء الخطة المدفوعة.
- ماذا يحدث للعملاء لحظة تبديل الأداة، ولماذا يتبدل نصفهم تقريباً بين الصفحتين.
- النقل Flag بعد Flag بمزود متعدد Multi-Provider، ولماذا قلب الترتيب نتيجة Flag.
- الأحداث Events والبدء والخدمة متوقفة، وما الذي يقوله كل مزود لتطبيقك.
- خطاف واحد للمقاييس، وكم تكلف طبقة المعيار في كل تقييم، واختبار المطابقة قبل النقل.
- خطة نقل عملية من أداة إلى أخرى دون أن يشعر العملاء.

## لماذا معيار بين الكود والأداة؟ Vendor Lock-in

الارتباط بالمورد Vendor Lock-in في ال Feature Flags أخطر منه في أدوات كثيرة، والسبب أن ال Flags ليست في مكان واحد. فقاعدة البيانات يكلمها مستودع واحد في الكود، أما ال Flag فيقرأ في كل مكان تتغير فيه الصفحة: في معالج الدفع، وفي حساب الشحن، وفي قالب الصفحة، وفي اختبار الوحدة. وفي متجرنا الصغير صار كل استدعاء لل Flags بعد أسابيع من Unleash مكتوباً بطريقته: `isEnabled` مع `properties`، و`getVariant` مع `payload`، ومثله في Flagsmith `getIdentityFlags` مع الصفات. فالانتقال من أداة إلى أخرى يعني أن تعدل كل استدعاء في كل ملف، وكل تعديل فرصة لخطأ.

ويحل [معيار OpenFeature](https://openfeature.dev/specification/?ref=arabroot.io) هذه المشكلة بطبقة واحدة: واجهة تقييم Evaluation API موحدة يستدعيها كودك، ومزود Provider لكل أداة يترجم بينها وبين ال SDK الخاص بها. وهو مشروع في مؤسسة CNCF [في مستوى Incubating منذ نوفمبر 2023](https://www.cncf.io/projects/openfeature/?ref=arabroot.io)، والمزودون الذين استخدمناهم كلاهما رسمي: مزود Unleash يكتبه فريق Unleash نفسه في [مستودعه](https://github.com/Unleash/unleash-openfeature-node-provider?ref=arabroot.io)، ومزود Flagsmith في [مستودع مساهمات OpenFeature](https://github.com/open-feature/js-sdk-contrib/tree/main/libs/providers/flagsmith?ref=arabroot.io).

وقد يتساءل البعض: إذا كان المعيار يوحد الاستدعاء، فهل يوحد النتيجة؟ والإجابة أن المعيار يوحد الشكل وليس المعنى، وهذا هو موضوع هذا المقال كله. فالمعيار يقول إن كل تقييم يعيد قيمة وسبباً Reason ورمز خطأ إذا فشل، ويعرف [قائمة الأسباب القياسية](https://openfeature.dev/specification/types/?ref=arabroot.io): `STATIC` و`DEFAULT` و`TARGETING_MATCH` و`SPLIT` و`CACHED` و`DISABLED` و`UNKNOWN` و`STALE` و`ERROR`، ولكنه لا يستطيع أن يجبر كل مزود على أن يختار السبب نفسه للحالة نفسها، لأن الأدوات نفسها لا تعرف الأشياء نفسها عن قيمها.

## الفكرة نفسها التي نجحت مع OpenTelemetry

إذا كنت قد قرأت [OpenTelemetry للمطورين](https://arabroot.io/articles/opentelemetry-%D9%84%D9%84%D9%85%D8%B7%D9%88%D8%B1%D9%8A%D9%86-%D8%AA%D8%AA%D8%A8%D8%B9-%D8%A7%D9%84%D8%B7%D9%84%D8%A8%D8%A7%D8%AA-traces-%D8%B9%D8%A8%D8%B1-%D8%AE%D8%AF%D9%85%D8%AA%D9%8A%D9%86/)، فسوف تعرف الفكرة فوراً. قبل OpenTelemetry كان كل نظام مراقبة يطلب مكتبته الخاصة في الكود، فإذا غيرت النظام غيرت الكود، ثم جاء معيار واحد تكتب به التتبع مرة، ويختار فريق التشغيل أين يرسله. وOpenFeature يطبق الفكرة نفسها على ال Flags: الكود يكتب «ما قيمة هذا ال Flag لهذا العميل؟» بلغة واحدة، وفريق المنصة يختار الأداة التي تجيب. ولذلك لم يكن غريباً أن يكون المشروعان في المؤسسة نفسها، CNCF، وأن يتشابها في البنية: واجهة للكود، وطبقة خطافات للسجلات والمقاييس، ومزود أو مصدر لكل أداة.

ولكن الفرق بين المجالين مهم لفهم حدود OpenFeature. ففي التتبع يرسل الكود بيانات في اتجاه واحد، والأداة تستقبلها، فإذا اختلفت الأدوات في طريقة العرض فلا يتغير شيء في سلوك التطبيق. أما في ال Flags فالأداة تقرر ما يراه العميل، فكل اختلاف في تفسير السياق أو في معنى «غير موجود» يغير سلوك المتجر نفسه. لذلك تحتاج طبقة ال Flags إلى اختبار مطابقة لا تحتاج إليه طبقة التتبع، وهذا ما سوف تراه في التجربة.

## ما الذي يوحده المعيار؟ What the Spec Covers

قبل التجربة، هذه أجزاء المعيار التي سوف نستخدمها، مع ما يتركه كل جزء للمزود:

- **التقييم بالنوع Typed Evaluation:** أربع دوال لأربعة أنواع: منطقي ونص ورقم وكائن، ولكل منها نسخة `Details` تعيد السبب والنسخة Variant ورمز الخطأ، كما في [قسم التقييم](https://openfeature.dev/specification/sections/flag-evaluation/?ref=arabroot.io). والمعيار يقول متى يعاد الخطأ `TYPE_MISMATCH`، ولكن كل مزود يقرر ما الذي يعده «نوعاً مختلفاً».
- **سياق التقييم Evaluation Context:** الحقل الوحيد الذي يعرفه [قسم السياق](https://openfeature.dev/specification/sections/evaluation-context/?ref=arabroot.io) باسم هو `targetingKey`، أي معرف الشيء الذي نقيم له، وكل ما سواه مفاتيح حرة يقرؤها كل مزود بطريقته.
- **الخطافات Hooks:** كود يعمل قبل التقييم وبعده وعند الخطأ وفي النهاية، كما في [قسم الخطافات](https://openfeature.dev/specification/sections/hooks/?ref=arabroot.io)، وخطاف `before` يستطيع أن يضيف إلى السياق، وهذا ما سوف ينقذنا.
- **الأحداث Events:** المزود يخبر التطبيق بأنه جاهز أو في خطأ أو أن قيمه قديمة أو أن الإعداد تغير، كما في [قسم الأحداث](https://openfeature.dev/specification/sections/events/?ref=arabroot.io)، وإطلاق هذه الأحداث اختياري لكل مزود.
- **دورة حياة المزود Provider Lifecycle:** التهيئة عند التسجيل والإغلاق عند `OpenFeature.close()`، كما في [قسم المزودين](https://openfeature.dev/specification/sections/providers/?ref=arabroot.io)، والإغلاق الحقيقي لاتصالات ال SDK مسؤولية المزود.

ولاحظ الكلمات المتكررة في القائمة: «يقرر المزود» و«اختياري» و«مسؤولية المزود». فالمعيار عقد بين كودك والمزود، وكل بند فيه لا يحدد السلوك بدقة هو مكان قد يختلف فيه مزودان.

وأهم ما في المعيار للمطور هو كائن التفاصيل Evaluation Details الذي تعيده دوال `Details`، وفيه خمسة حقول: القيمة `value`، والسبب `reason`، والنسخة `variant`، ورمز الخطأ `errorCode` مع رسالته، وبيانات إضافية `flagMetadata`. والقاعدة في المعيار أن التقييم لا يرمي خطأ أبداً إلى كودك، وإنما يعيد القيمة الافتراضية مع رمز الخطأ، فإذا تعطلت الأداة أو أخطأت في الاسم يستمر المتجر بالقيمة التي كتبتها أنت. وهذه القاعدة وحدها سبب كاف لاستخدام المعيار حتى مع أداة واحدة، لأن أغلب ال SDKs لا تلتزم بها في كل الحالات، كما رأينا مع Flagsmith في مقال المفهوم عندما رفض التطبيق أن يبدأ.

## تجربة عملية Lab: كود واحد ومزودان

الآن سوف نشغل Unleash 8.3.1 وFlagsmith 2.288.2 بملفي Compose من المقالين السابقين في هذه السلسلة، وننشئ في كل منهما الأعلام الأربعة نفسها بالمعنى نفسه، ثم نكتب كود المتجر مرة واحدة على OpenFeature Server SDK 1.23.0، ونشغله مرتين لا يتغير بينهما إلا متغير بيئة. وتحتاج التجربة إلى Docker فقط.

### الأعلام الأربعة في الأداتين Flags

اختار الفريق أربعة أعلام تغطي الأنواع الأربعة في المعيار، وكتبها في الأداتين بالمعنى نفسه:

| ال Flag                   | النوع | المعنى                           | في Unleash                          | في Flagsmith                                  |
| ------------------------- | ----- | -------------------------------- | ----------------------------------- | --------------------------------------------- |
| new\_checkout             | منطقي | صفحة الدفع الجديدة لنصف العملاء  | استراتيجية 50%                      | مجموعة بنسبة 50%                              |
| checkout\_layout          | نص    | one\_page أو two\_steps بالتساوي | نسختان بحمولة نصية                  | قيمة متعددة Multivariate                      |
| free\_shipping\_threshold | رقم   | 150 ريالاً، وصفر للخطة المدفوعة  | نسخة بحمولة رقمية، وقيد plan IN pro | قيمة البيئة 150، وتجاوز مجموعة pro\_customers |
| checkout\_config          | كائن  | إعداد الدفع ب JSON               | نسخة بحمولة JSON                    | قيمة نصية فيها JSON                           |

ولاحظ في الجدول أن «النوع» في Unleash ليس صفة لل Flag، فال Flag في Unleash منطقي دائماً، والنص والرقم والكائن تأتي من حمولة Payload النسخة، أما في Flagsmith فكل ميزة لها قيمة يخمن نوعها كما رأينا في مقال Flagsmith. فالمزود هو الذي يقرر كيف يحول كلاً منهما إلى الأنواع الأربعة. وأنشأنا الأعلام في Unleash بسكربت Python على ال Admin API، والجزء الذي يعرف الحد للخطة المدفوعة كما يلي:

```python
pro = [{'contextName': 'plan', 'operator': 'IN', 'values': ['pro'], 'inverted': False, 'caseInsensitive': False}]
call('POST', P, {'name': 'free_shipping_threshold', 'type': 'operational', 'description': 'Free shipping threshold in SAR'})
strategy('free_shipping_threshold', 'pro customers', 100, [variant('pro', 'number', '0')], constraints=pro)
strategy('free_shipping_threshold', 'everyone', 100, [variant('standard', 'number', '150')])
```

```text
unleash flags: ['new_checkout', 'checkout_layout', 'free_shipping_threshold', 'checkout_config'] | backend token default:production.v2_…
```

أما في Flagsmith فكانت الأعلام موجودة من المقال السابق، فأزلنا فقط تجاوز التجربة على عشرة بالمئة حتى يتطابق المعنى في الأداتين.

### الملف الوحيد الذي يعرف الأداة flags.mjs

النسخة الأولى من الملف تختار المزود بمتغير البيئة `FLAG_PROVIDER`، وتسجله، وتعطي باقي الكود عميل OpenFeature فقط:

```javascript
// The only file that knows which flag tool the shop uses. FLAG_PROVIDER=unleash | flagsmith
import { OpenFeature } from '@openfeature/server-sdk';

async function unleashProvider() {
  const { UnleashProvider } = await import('@unleash/openfeature-node-provider');
  return new UnleashProvider({
    url: process.env.UNLEASH_URL, appName: 'shop-backend',
    customHeaders: { Authorization: process.env.UNLEASH_TOKEN },
  });
}

async function flagsmithProvider() {
  const { FlagsmithOpenFeatureProvider } = await import('@openfeature/flagsmith-provider');
  const { Flagsmith } = await import('flagsmith-nodejs');
  const flagsmith = new Flagsmith({
    environmentKey: process.env.FLAGSMITH_SERVER_KEY, apiUrl: process.env.FLAGSMITH_API_URL,
    enableLocalEvaluation: true, environmentRefreshIntervalSeconds: 10,
  });
  return new FlagsmithOpenFeatureProvider(flagsmith);
}

const name = process.env.FLAG_PROVIDER || 'unleash';
const provider = name === 'flagsmith' ? await flagsmithProvider() : await unleashProvider();
await OpenFeature.setProviderAndWait(provider);

export const flags = OpenFeature.getClient('shop');
export const providerName = `${name} (${provider.metadata.name})`;
export const close = () => OpenFeature.close();
```

في الكود أعلاه لاحظ أن الاستيراد ديناميكي `await import`، فلا تحمل مكتبة الأداة التي لا تستخدمها، وهذا يسمح أيضاً بأن تحذف مكتبة الأداة القديمة من `package.json` بعد النقل دون أن تلمس هذا الملف إلا مرة واحدة. والإصدارات التي استخدمناها:

```json
{
  "dependencies": {
    "@openfeature/server-sdk": "1.23.0",
    "@unleash/openfeature-node-provider": "1.0.1",
    "unleash-client": "6.12.2",
    "@openfeature/flagsmith-provider": "0.1.2",
    "flagsmith-nodejs": "8.1.2"
  }
}
```

والصورة التالية تبين الطبقات الثلاث، وما تغير بين التشغيلين:

![كود المتجر suite.mjs يستدعي getBooleanDetails لل Flag new_checkout بقيمة افتراضية false وسياق targetingKey وplan دون اسم أي أداة، ثم @openfeature/server-sdk 1.23.0 فيه واجهة التقييم Evaluation API والخطافات Hooks والأحداث Events وسياق التقييم والقيمة مع السبب وMulti-Provider مدمج، ثم الملف flags.mjs مع FLAG_PROVIDER وهو الملف الوحيد الذي يعرف الأداة وفيه ال Provider وخطاف السياق والإيقاف ومهلة البدء، ومنه سهمان إلى @unleash/openfeature-node-provider 1.0.1 مع unleash-client 6.12.2 إلى Unleash 8.3.1، و@openfeature/flagsmith-provider 0.1.2 مع flagsmith-nodejs 8.1.2 إلى Flagsmith 2.288.2، وفي مربع جانبي أن ما تغير بين التشغيلين هو FLAG_PROVIDER=unleash إلى FLAG_PROVIDER=flagsmith ولا سطر في كود المتجر ولكن النتائج لم تكن واحدة](https://arabroot.io/content/images/2026/11/openfeature-01-one-file.webp)

التبديل متغير بيئة واحد، والسؤال الحقيقي: هل يعطي المزودان الجواب نفسه؟

### كود المتجر suite.mjs

السكربت يجمع استدعاءات المتجر الحقيقية: صفحة الدفع والتصميم وحد الشحن لثلاثة عملاء، ثم الإعداد الكامل، ثم حالتين خاطئتين يجب أن نعرف كيف يتصرف كل مزود معهما: اسم Flag فيه خطأ إملائي، ورقم يطلب كنص:

```javascript
// The shop's flag calls, written once against OpenFeature. Run it with each provider and compare.
import { flags, providerName, close } from './flags.mjs';

const customers = [
  { targetingKey: 'user-2', plan: 'free' },
  { targetingKey: 'user-7', plan: 'free' },
  { targetingKey: 'user-8', plan: 'pro' },
];
const show = (d) => JSON.stringify({ value: d.value, variant: d.variant, reason: d.reason, errorCode: d.errorCode });

console.log('provider:', providerName);
for (const c of customers) {
  console.log(`-- ${c.targetingKey} plan=${c.plan}`);
  console.log('  new_checkout            ', show(await flags.getBooleanDetails('new_checkout', false, c)));
  console.log('  checkout_layout         ', show(await flags.getStringDetails('checkout_layout', 'one_page', c)));
  console.log('  free_shipping_threshold ', show(await flags.getNumberDetails('free_shipping_threshold', 200, c)));
}
const cfg = await flags.getObjectDetails('checkout_config', {}, customers[0]);
console.log('checkout_config.payment_methods', JSON.stringify(cfg.value.payment_methods), cfg.reason, cfg.errorCode ?? '');
console.log('typo new_chekout          ', show(await flags.getBooleanDetails('new_chekout', false, customers[0])));
console.log('missing flag as string    ', show(await flags.getStringDetails('new_chekout', 'x', customers[0])));
console.log('number asked as string    ', show(await flags.getStringDetails('free_shipping_threshold', 'x', customers[0])));
await close();
```

لاحظ أن السياق مسطح: `targetingKey` ومعه `plan` في المستوى نفسه، وهذا هو الشكل الذي تستخدمه أمثلة المعيار نفسه، وهو ما يكتبه أي مطور يقرأ توثيق OpenFeature أولاً.

### التشغيل الأول First Run: مزودان وجوابان

شغلنا السكربت مرتين في Container واحد متصل بشبكتي الأداتين، لا يختلفان إلا في `FLAG_PROVIDER`:

```text
$ docker exec -e FLAG_PROVIDER=unleash wr-ff-of-app node suite.mjs
provider: unleash (unleash-openfeature-node-provider)
-- user-2 plan=free
  new_checkout             {"value":true,"reason":"UNKNOWN"}
  checkout_layout          {"value":"two_steps","variant":"two_steps","reason":"SPLIT"}
  free_shipping_threshold  {"value":150,"variant":"standard","reason":"SPLIT"}
-- user-7 plan=free
  new_checkout             {"value":false,"reason":"UNKNOWN"}
  checkout_layout          {"value":"one_page","variant":"one_page","reason":"SPLIT"}
  free_shipping_threshold  {"value":150,"variant":"standard","reason":"SPLIT"}
-- user-8 plan=pro
  new_checkout             {"value":true,"reason":"UNKNOWN"}
  checkout_layout          {"value":"one_page","variant":"one_page","reason":"SPLIT"}
  free_shipping_threshold  {"value":0,"variant":"pro","reason":"SPLIT"}
checkout_config.payment_methods ["mada","apple_pay","cod","stc_pay"] SPLIT
typo new_chekout           {"value":false,"reason":"UNKNOWN"}
number asked as string     {"value":"x","reason":"ERROR","errorCode":"TYPE_MISMATCH"}
```

```text
$ docker exec -e FLAG_PROVIDER=flagsmith wr-ff-of-app node suite.mjs
provider: flagsmith (flagsmith-provider)
-- user-2 plan=free
  new_checkout             {"value":true,"reason":"TARGETING_MATCH"}
  checkout_layout          {"value":"two_steps","reason":"TARGETING_MATCH"}
  free_shipping_threshold  {"value":150,"reason":"TARGETING_MATCH"}
-- user-7 plan=free
  new_checkout             {"value":false,"reason":"DISABLED"}
  checkout_layout          {"value":"two_steps","reason":"TARGETING_MATCH"}
  free_shipping_threshold  {"value":150,"reason":"TARGETING_MATCH"}
-- user-8 plan=pro
  new_checkout             {"value":false,"reason":"DISABLED"}
  checkout_layout          {"value":"two_steps","reason":"TARGETING_MATCH"}
  free_shipping_threshold  {"value":150,"reason":"TARGETING_MATCH"}
checkout_config.payment_methods ["mada","apple_pay","cod","stc_pay"] TARGETING_MATCH
typo new_chekout           {"value":false,"reason":"ERROR","errorCode":"FLAG_NOT_FOUND"}
number asked as string     {"value":"150","reason":"TARGETING_MATCH"}
```

وبعد أن طبعت النسخة الثانية آخر سطر، لم تنته العملية، وبقيت معلقة حتى أوقفناها بعد دقيقتين. وسوف نعود إلى ذلك. أما الفروق في المخرج فهي كثيرة، والصورة التالية تجمعها مع ما أضفناه بعد ذلك:

![جدول من سبعة صفوف يقارن Unleash provider وFlagsmith provider: سبب القيمة المنطقية reason هو UNKNOWN في Unleash وTARGETING_MATCH أو DISABLED في Flagsmith، واسم النسخة variant هو one_page أو two_steps في Unleash وفارغ في Flagsmith، وFlag غير موجود كقيمة منطقية false مع UNKNOWN في Unleash وfalse مع FLAG_NOT_FOUND في Flagsmith، وFlag غير موجود كنص x مع DISABLED في Unleash وx مع FLAG_NOT_FOUND في Flagsmith، ورقم يطلب كنص x مع TYPE_MISMATCH في Unleash و150 كنص مع TARGETING_MATCH في Flagsmith، وplan في السياق مباشرة pro إلى 0 في Unleash وpro إلى 150 أي متجاهل في Flagsmith، وإيقاف OpenFeature.close ينتهي في Unleash ويتعلق بمؤقت التحديث في Flagsmith](https://arabroot.io/content/images/2026/11/openfeature-02-differences.webp)

الاستدعاء نفسه، وسبعة فروق في الجواب

وأخطر هذه الفروق ليس في الأسباب، وإنما في سطر العميل `user-8`: عميل الخطة المدفوعة حصل في Unleash على شحن مجاني من صفر ريال، وفي Flagsmith على حد 150، أي أن تبديل الأداة كان سوف يجعل أفضل عملاء المتجر يدفعون ثمن الشحن دون أن يتغير سطر في الكود ودون أي خطأ.

ولاحظ أيضاً أن عملاء `new_checkout` ليسوا أنفسهم في الأداتين: `user-8` يرى الصفحة الجديدة في Unleash ولا يراها في Flagsmith، و`user-7` يرى `one_page` في الأولى و`two_steps` في الثانية. وهذا ليس خطأ في أي مزود، وإنما نتيجة طبيعية لأن كل أداة تحسب الخانة بطريقتها، وسوف نقيس حجمه بعد قليل على ألف عميل. أما حقل `variant` فيظهر مع Unleash لأن قيمه تأتي من نسخ لها أسماء، ولا يظهر مع Flagsmith لأن مزوده لا يعيده، فإذا كان كود التحليل عندك يسجل اسم النسخة مع كل طلب، فسوف تجد العمود فارغاً بعد التبديل. وكل هذه الفروق ظهرت في أول تشغيل لسكربت من ثلاثين سطراً، وهذا وحده يقول إن أي نقل بين أداتين يبدأ بسكربت مثله، قبل أي تعديل في الإنتاج.

### مشكلة حقيقية Real Problem: الصفة plan اختفت

قرأنا ملف README لمزود Flagsmith، فوجدنا السبب في قسم سياق التقييم: المزود يرسل إلى Flagsmith الصفات Traits من الحقل `traits` داخل السياق فقط، أي أنه يتوقع `{ targetingKey, traits: { plan } }`. أما مزود Unleash فيفعل العكس، فيقول README الخاص به إن كل مفتاح غير معروف في السياق يصبح `properties.<key>`، وإن الكائنات المتداخلة تحذف لأن قيود Unleash لا تستطيع أن تقيمها. أي أن السياق الذي يعمل مع أحدهما لا يعمل مع الآخر:

- السياق المسطح `{ targetingKey, plan }`: يعمل مع Unleash، ويتجاهل Flagsmith الصفة.
- السياق المتداخل `{ targetingKey, traits: { plan } }`: يعمل مع Flagsmith، ويحذف Unleash الحقل كله.

والحل الخاطئ أن تغير كود المتجر إلى الشكل المتداخل، لأنك بذلك تكتب شكل Flagsmith في كل استدعاء، وتعود إلى الارتباط بالأداة الذي جئت لتهرب منه. والحل الصحيح خطاف `before` في `flags.mjs` نفسه، يعمل قبل كل تقييم، وينقل الصفات المسطحة إلى `traits` عندما يكون المزود Flagsmith فقط، كما تبين الصورة التالية:

![ما يمرره المتجر هو السياق المسطح targetingKey user-8 وplan pro بأسلوب OpenFeature، وسهم أخضر إلى مزود Unleash حيث targetingKey يصبح userId وplan يصبح properties.plan فيعطي free_shipping_threshold = 0، وسهم برتقالي إلى مزود Flagsmith حيث targetingKey يصبح identity والصفات تؤخذ من context.traits فقط فيتجاهل plan ويعطي 150، وفي الأسفل الإصلاح في flags.mjs فقط بخطاف before يعمل قبل كل تقييم ويضيف إلى السياق traits من باقي المفاتيح، وكود المتجر يبقى بسياق مسطح](https://arabroot.io/content/images/2026/11/openfeature-03-context.webp)

المعيار يعرف targetingKey فقط، وباقي السياق يقرؤه كل مزود بطريقته

```javascript
  // The shop passes a flat context ({ targetingKey, plan }); the Flagsmith provider reads traits from context.traits.
  OpenFeature.addHooks({
    before: ({ context }) => {
      const { targetingKey, traits, ...rest } = context;
      return { traits: { ...rest, ...traits } };
    },
  });
```

والخطاف يعيد كائناً يدمجه OpenFeature مع السياق قبل أن يصل إلى المزود، فلا يعدل السياق الأصلي، ولا يرى كود المتجر أي فرق. وبعد الإضافة صار سطر `user-8` في Flagsmith كما يجب:

```text
-- user-8 plan=pro
  new_checkout             {"value":false,"reason":"DISABLED"}
  checkout_layout          {"value":"two_steps","reason":"TARGETING_MATCH"}
  free_shipping_threshold  {"value":0,"reason":"TARGETING_MATCH"}
```

وهذا هو الدرس الأول عن OpenFeature: المعيار يوحد الدوال، والمزود يقرر شكل السياق، فاكتب سياقك بشكل واحد في كل الكود، واجعل الترجمة إلى ما يتوقعه كل مزود في ملف المزود، ولا تفترض أن مزودين يقرآن السياق نفسه بالطريقة نفسها.

### مشكلة ثانية Second Problem: العملية لا تنتهي عند الإيقاف

أما العملية التي بقيت معلقة مع Flagsmith، فالسبب أن مزود Flagsmith 0.1.2 لا يغلق ال SDK عند `OpenFeature.close()`، فيبقى مؤقت تحديث وثيقة البيئة كل عشر ثوان يعمل ويبقي العملية حية. وفي مقال المفهوم رأينا هذا مع ال SDK مباشرة، وكنا نتوقع أن يتولاه المزود، فالمعيار يقول إن الإغلاق يمر بالمزود، ولكن المزود هنا لا يطبقه. وفي سيرفر حقيقي معنى ذلك أن الإيقاف المنظم Graceful Shutdown عند كل نشر ينتظر حتى يقتل Docker العملية بالقوة. والإصلاح سطران في `flags.mjs` أيضاً:

```javascript
let shutdown = async () => {};
// …inside flagsmithProvider():
  shutdown = async () => flagsmith.close();   // the provider does not stop the SDK's polling timer itself
// …
export const close = async () => { await OpenFeature.close(); await shutdown(); };
```

```text
$ time docker exec -e FLAG_PROVIDER=flagsmith wr-ff-of-app timeout 60 node suite.mjs
…
real	0m0.773s
```

أما مزود Unleash فيغلق عميله مع إرسال آخر العدادات `destroyWithFlush`، كما قرأنا في كوده، ولذلك انتهت عمليته دون تدخل.

### الأسباب ورموز الخطأ Reasons and Error Codes

بقيت الفروق في الأسباب ورموز الخطأ، وهي لا تغير ما يراه العميل، ولكنها تغير ما تراه أنت في السجلات والتنبيهات. أضفنا إلى السكربت حالة ثالثة، اسماً خاطئاً يطلب كنص، وكانت أسطر الأخطاء كما يلي:

```text
--- unleash
typo new_chekout           {"value":false,"reason":"UNKNOWN"}
missing flag as string     {"value":"x","reason":"DISABLED"}
number asked as string     {"value":"x","reason":"ERROR","errorCode":"TYPE_MISMATCH"}
--- flagsmith
typo new_chekout           {"value":false,"reason":"ERROR","errorCode":"FLAG_NOT_FOUND"}
missing flag as string     {"value":"x","reason":"ERROR","errorCode":"FLAG_NOT_FOUND"}
number asked as string     {"value":"150","reason":"TARGETING_MATCH"}
```

في المخرج أعلاه لاحظ التالي:

- **الاسم الخاطئ:** Flagsmith يقول `FLAG_NOT_FOUND` بوضوح، أما Unleash فيعيد القيمة الافتراضية بسبب `UNKNOWN` للقيمة المنطقية و`DISABLED` للنص، أي أنه لا يفرق بين Flag مطفأ وFlag غير موجود. ويقول README مزود Unleash إن ال Flag غير الموجود يعيد `FLAG_NOT_FOUND`، ولكن ما رأيناه في الإصدار 1.0.1 مختلف، وقرأنا الكود فوجدنا أن التقييم المنطقي يستدعي `isEnabled` ويعيد `UNKNOWN` دائماً. فإذا كان تنبيهك في السجلات على `FLAG_NOT_FOUND`، فلن يعمل مع Unleash، وفحص ال Flags المنسية في CI الذي كتبناه في مقال المفهوم يبقى ضرورياً.
- **النوع الخاطئ:** Unleash يرفض الرقم إذا طلب كنص بالخطأ `TYPE_MISMATCH`، لأن نوع الحمولة رقم، أما Flagsmith فيعيد النص `"150"` دون خطأ. وكلاهما سلوك معقول، ولكن الكود الذي يعمل مع أحدهما قد يخطئ بصمت مع الآخر.
- **السبب في الحالة الطبيعية:** كل قيم Unleash المنطقية سببها `UNKNOWN`، وقيمه من النسخ سببها `SPLIT`، أما Flagsmith فيقول `TARGETING_MATCH` أو `DISABLED`، ولا يعيد اسم النسخة. فلوحة تعد التقييمات بحسب السبب أو النسخة سوف تتغير كلها عند التبديل.

والدرس الثاني: لا تبن منطقاً في الكود على السبب أو النسخة، واستخدمهما في السجلات فقط، وإذا احتجت إلى تنبيه على الأسماء الخاطئة فاجعله في CI، لأنه لا يعتمد على مزود.

### ماذا يحدث للعملاء عند التبديل؟ What If

بعد أن صار الكود يعطي القيم الصحيحة مع المزودين، بقي سؤال لم يسأله أحد في الاجتماع: إذا كانت صفحة الدفع الجديدة مفتوحة لخمسين بالمئة في Unleash، وفتحناها لخمسين بالمئة في Flagsmith، فهل هم العملاء أنفسهم؟ كتبنا سكربتاً يقيم ألف عميل بكل مزود، ويقارن القائمتين:

```text
unleash: new_checkout ON for 511 of 1000, two_steps for 509
flagsmith: new_checkout ON for 484 of 1000, two_steps for 489
same customers ON in both tools: 262; ON in unleash only: 249; ON in flagsmith only: 222
same checkout_layout in both tools: 496 of 1000
```

262 عميلاً فقط يرون الصفحة الجديدة في الأداتين، و249 كانوا يرونها في Unleash وسوف يعودون إلى القديمة، و222 لم يروها وسوف يرونها فجأة، أي أن 471 عميلاً من ألف تتغير صفحتهم لحظة التبديل. أما تصميم الصفحة فمتطابق عند 496 فقط، أي رمي عملة. والصورة التالية تبين ذلك:

![شريط لصفحة الدفع الجديدة لألف عميل والنسبة 50% في الأداتين: 262 في الأداتين، و249 في Unleash فقط، و222 في Flagsmith فقط، و267 في أي منهما لا، وتحته مربع أحمر: 471 عميلاً يتبدلون بين الصفحتين لحظة تغيير الأداة لأن كل أداة تحسب الخانة بهاش مختلف murmur3 في Unleash وهاش آخر في Flagsmith، ثم شريط للنسخة checkout_layout نفسها في الأداتين 496 ونسخة مختلفة 504، وتحته رمي عملة: أي تجربة جارية تفسد عند التبديل](https://arabroot.io/content/images/2026/11/openfeature-04-reshuffle.webp)

النسبة نفسها لا تعني العملاء أنفسهم

والسبب ما شرحناه في مقال Unleash: كل أداة تضع العميل في خانة بدالة هاش خاصة بها، فخانة العميل في Unleash لا علاقة لها بخانته في Flagsmith. والمعيار لا يستطيع أن يوحد ذلك، لأن الهاش داخل محرك الأداة وليس في المزود. والنتيجة العملية ثلاث قواعد:

- لا تنقل Flag في منتصف إطلاق تدريجي، وإنما انقله وهو على 0% أو 100%، حيث لا يهم الهاش.
- لا تنقل Flag تجربة جارية أبداً، لأن نصف العملاء سوف ينتقلون إلى المجموعة الأخرى وتفسد المقارنة كما رأينا في مقال GrowthBook.
- إذا كان لا بد من النقل في منتصف الإطلاق، فاجعل القرار يعتمد على قائمة ثابتة تصدرها من الأداة القديمة، ثم أعد الإطلاق التدريجي في الأداة الجديدة من البداية.

### النقل Flag بعد Flag: Multi-Provider

لا ينقل أحد كل الأعلام في يوم واحد، والطريقة الآمنة أن يسأل التطبيق الأداة الجديدة أولاً، فإذا لم يجد فيها ال Flag سأل القديمة. وهذا ما يقدمه المزود المتعدد Multi-Provider، وصار جزءاً من [Server SDK ل JavaScript](https://openfeature.dev/docs/reference/technologies/server/javascript/?ref=arabroot.io) نفسه بعد أن كان حزمة مستقلة، وأول استراتيجياته `FirstMatchStrategy`: أول مزود يعيد قيمة دون `FLAG_NOT_FOUND` يفوز. أنشأنا Flag اسمه `old_search` في Unleash فقط، وعندنا `cod_enabled` في Flagsmith فقط من المقال السابق، وجربنا الترتيبين:

```javascript
const order = (process.env.ORDER || 'flagsmith,unleash').split(',');
await OpenFeature.setProviderAndWait(new MultiProvider(order.map((n) => ({ provider: all[n], name: n })), new FirstMatchStrategy()));
const flags = OpenFeature.getClient();
for (const key of ['cod_enabled', 'old_search', 'new_checkout']) {
  const d = await flags.getBooleanDetails(key, false, { targetingKey: 'user-2' });
  console.log(`  ${key.padEnd(13)} value=${d.value} reason=${d.reason}`);
}
```

```text
order: flagsmith -> unleash
  cod_enabled   value=true reason=TARGETING_MATCH
  old_search    value=true reason=UNKNOWN
  new_checkout  value=true reason=TARGETING_MATCH
order: unleash -> flagsmith
  cod_enabled   value=false reason=UNKNOWN
  old_search    value=true reason=UNKNOWN
  new_checkout  value=true reason=UNKNOWN
```

بترتيب Flagsmith أولاً عمل كل شيء: `cod_enabled` من Flagsmith، و`old_search` من Unleash لأن Flagsmith قال إنه غير موجود. أما بالترتيب المعاكس فقد أصبح `cod_enabled` مطفأً، أي أن الدفع عند الاستلام اختفى من المتجر، والسبب الفرق الذي رأيناه في القسم السابق: مزود Unleash لا يقول «غير موجود» للقيم المنطقية، وإنما يعيد `false` بسبب `UNKNOWN`، فتعده الاستراتيجية جواباً وتتوقف عنده، ولا تسأل Flagsmith أبداً. والصورة التالية تبين الترتيبين:

![عمودان: ترتيب flagsmith ثم unleash يعطي cod_enabled true من Flagsmith لأنه فيه فقط، وold_search true من Unleash لأنه لم ينقل بعد فأعاد الأول FLAG_NOT_FOUND فسأل الثاني، وnew_checkout true من Flagsmith لأنه في الاثنين والأول يجيب، وترتيب unleash ثم flagsmith يعطي cod_enabled false مع UNKNOWN لأن مزود Unleash لا يقول FLAG_NOT_FOUND للقيم المنطقية، وold_search true، وnew_checkout true من Unleash، وفي الأسفل Multi-Provider مع FirstMatchStrategy للنقل Flag بعد Flag: ضع أولاً المزود الذي يقول بوضوح غير موجود واختبر كل Flag في الترتيبين قبل الإنتاج](https://arabroot.io/content/images/2026/11/openfeature-05-multi-provider.webp)

الترتيب جزء من الإعداد، وليس تفصيلاً

وفي حالة فريقنا الترتيب الصحيح هو الترتيب الطبيعي للنقل، الأداة الجديدة أولاً، لأن Flagsmith يقول «غير موجود» بوضوح. ولكن لو كان النقل من Flagsmith إلى Unleash، لكان الترتيب الطبيعي هو الترتيب الخاطئ، ولما ظهر أي خطأ، وإنما ميزات تختفي واحدة بعد أخرى كلما أضيف Flag إلى Unleash. لذلك اكتب اختباراً في CI يقيم كل Flag عبر المزود المتعدد ويقارنه بقيمته في الأداة القديمة وحدها قبل كل خطوة نقل.

### ماذا يقول المزود عن نفسه؟ Provider Events

المعيار يعرف أحداثاً يطلقها المزود، فيستطيع التطبيق أن يسجل أن القيم تغيرت أو أصبحت قديمة، فسجلنا مستمعاً لكل الأحداث، وشغلنا عملية تطبع قيمة `new_checkout` كل خمس ثوان، ثم أطفأنا ال Flag في اللوحة، ثم أوقفنا الخدمة. ومع Unleash:

```text
10:04:48 action: new_checkout production off
10:05:10 action: docker stop wr-ff-unleash-server
10:04:44 event PROVIDER_READY (Unleash client ready)
10:04:44 event PROVIDER_CONFIGURATION_CHANGED (Flag configuration changed)
10:04:44 started with unleash (unleash-openfeature-node-provider) | status READY
10:04:54 t=10s new_checkout(user-2)=true status=READY
10:04:59 event PROVIDER_CONFIGURATION_CHANGED (Flag configuration changed)
10:04:59 t=15s new_checkout(user-2)=false status=READY
…
10:05:41 event PROVIDER_STALE (Unleash Repository error: request to http://unleash:4242/api/client/fe)
10:05:44 t=60s new_checkout(user-2)=false status=STALE
```

ومع Flagsmith، بعد أن فتحنا ال Flag للجميع ثم أوقفنا الخدمة:

```text
10:06:26 action: new_checkout production enabled for everyone
10:06:46 action: docker stop wr-ff-flagsmith-api
10:06:18 event PROVIDER_READY
10:06:23 t=5s new_checkout(user-7)=false status=READY
10:06:28 t=10s new_checkout(user-7)=true status=READY
…
{"level":50,…,"err":{"type":"TypeError","message":"fetch failed: getaddrinfo ENOTFOUND api",…}
10:07:18 t=60s new_checkout(user-7)=true status=READY
```

مزود Unleash أطلق `PROVIDER_CONFIGURATION_CHANGED` مع كل تغيير، و`PROVIDER_STALE` بعد 31 ثانية من توقف الخدمة، فتستطيع أن تسجل في سجلاتك «القيم قديمة منذ…». أما مزود Flagsmith فلم يطلق أي حدث بعد الجاهزية، لا عند التغيير ولا عند التوقف، وبقيت حالته `READY` والخدمة متوقفة، والخطأ ظهر فقط في سجل مكتبة Flagsmith بصيغتها. والمعيار يجعل هذه الأحداث اختيارية، فكلا المزودين ملتزم به، ولكن من بنى مراقبته على أحداث Unleash سوف يفقدها كلها بعد التبديل.

### ماذا لو بدأ المتجر والخدمة متوقفة؟ What If

أوقفنا الخدمتين، وشغلنا عملية جديدة بالنسخة الثانية من `flags.mjs`، تسجل كم انتظرت وماذا أعاد أول تقييم:

```text
--- unleash down
started after 26713 ms with unleash (unleash-openfeature-node-provider), status READY
new_checkout(user-2): {"errorCode":"PROVIDER_NOT_READY","errorMessage":"Unleash provider has not yet synchronized flag data","value":false,"reason":"ERROR",…}
--- flagsmith down
setProviderAndWait threw after 22570 ms: Error: getEnvironmentFlags failed and no default flag handler was provided
```

المتجر انتظر قرابة نصف دقيقة في الحالتين قبل أن يبدأ، وهذه مدة تجعل فحص الجاهزية يفشل في أغلب الإعدادات. ومع Unleash كانت الحالة `READY` بينما التقييم نفسه يقول `PROVIDER_NOT_READY`، أي أن الحالة والتقييم لا يتفقان. ومع Flagsmith رمى `setProviderAndWait` خطأ، فلو لم نلتقطه لما بدأ المتجر أصلاً، وهي المشكلة التي رأيناها مع ال SDK مباشرة في مقال المفهوم. والإصلاح مهلة قصيرة في `flags.mjs`:

```javascript
// Wait at most 3 s for the provider. If the flag service is down, start anyway: every call returns its
// default value (errorCode PROVIDER_NOT_READY) until the provider becomes ready in the background.
const ready = OpenFeature.setProviderAndWait(provider)
  .then(() => 'ready')
  .catch((err) => { console.error(`[flags] ${name} provider failed to start: ${err.message}`); return 'error'; });
const startedAs = await Promise.race([ready, new Promise((r) => setTimeout(() => r('timeout'), 3000))]);
```

```text
--- unleash down (fixed flags.mjs)
started after 3155 ms with unleash (unleash-openfeature-node-provider, start: timeout), status NOT_READY
new_checkout(user-2): {"errorCode":"PROVIDER_NOT_READY","errorMessage":"provider has not yet initialized","value":false,"reason":"ERROR",…}
--- flagsmith down (fixed flags.mjs)
started after 3118 ms with flagsmith (flagsmith-provider, start: timeout), status NOT_READY
new_checkout(user-2): {"errorCode":"PROVIDER_NOT_READY","errorMessage":"provider has not yet initialized","value":false,"reason":"ERROR",…}
```

الآن يبدأ المتجر خلال ثلاث ثوان مع الأداتين، وكل Flag على قيمته الافتراضية، أي الصفحة القديمة. ثم سألنا السؤال الأخير: إذا عادت الخدمة، هل يلتقطها المتجر دون إعادة تشغيل؟ شغلنا عملية والخدمة متوقفة، ثم شغلنا الخدمة بعد خمس ثوان:

```text
10:09:26 docker start wr-ff-unleash-server
10:09:21 started with unleash (unleash-openfeature-node-provider, start: timeout)
10:09:31 status=READY value=false PROVIDER_NOT_READY
10:09:41 status=READY value=false PROVIDER_NOT_READY
10:09:51 status=READY value=true UNKNOWN
10:10:54 docker start wr-ff-flagsmith-api
10:10:49 started with flagsmith (flagsmith-provider, start: timeout)
[flags] flagsmith provider failed to start: getEnvironmentFlags failed and no default flag handler was provided
10:11:02 status=ERROR value=false GENERAL
10:11:12 status=ERROR value=true TARGETING_MATCH
…
10:12:12 status=ERROR value=true TARGETING_MATCH
```

التقطت العمليتان القيم بعد عودة الخدمة دون إعادة تشغيل، Unleash بعد نحو 25 ثانية وFlagsmith بعد نحو 18\. ولكن حالة مزود Flagsmith بقيت `ERROR` رغم أن القيم صحيحة، لأن التهيئة فشلت مرة، ومكتبة Flagsmith نجحت بعدها في الخلفية دون أن يعرف المزود. فإذا كان فحص الجاهزية في تطبيقك يقرأ حالة المزود، فسوف يبقى المتجر «غير جاهز» إلى الأبد مع Flagsmith. والصورة التالية تجمع ما رأيناه عن دورة الحياة:

![جدول يقارن المزودين: البدء والخدمة متوقفة انتظر Unleash 26.7 ثانية ثم READY ولكن PROVIDER_NOT_READY، ورمى Flagsmith خطأ بعد 22.6 ثانية لعدم وجود معالج للقيم الافتراضية، ومع مهلة 3 ثوان في flags.mjs بدأ Unleash في 3155 ms وFlagsmith في 3118 ms بالقيم الافتراضية، وعند عودة الخدمة عادت قيم Unleash بعد نحو 25 ثانية وقيم Flagsmith بعد نحو 18 ثانية وبقيت حالته ERROR، وعند تغير Flag في اللوحة أطلق Unleash PROVIDER_CONFIGURATION_CHANGED ولم يطلق Flagsmith أي حدث، وعند توقف الخدمة والعملية تعمل أطلق Unleash PROVIDER_STALE بعد 31 ثانية وبقي Flagsmith READY والأخطاء في سجل ال SDK، وفي الأسفل: لا تبن المراقبة على providerStatus وحده، راقب الخدمة نفسها وعد الأخطاء في خطاف error لكل تقييم](https://arabroot.io/content/images/2026/11/openfeature-06-lifecycle.webp)

كل مزود ملتزم بالمعيار، ولكل منهما قصة مختلفة عن حالته

### خطاف واحد للمقاييس Telemetry Hook

من أهم ما يقدمه المعيار أن السجلات والمقاييس تكتب مرة واحدة في خطاف، بدل أن تكتب لكل أداة بطريقتها. فكتبنا خطافاً يعد كل تقييم بحسب ال Flag والقيمة والسبب، وكل خطأ برمزه، كما يفعل أي مصدر مقاييس، وقيمنا `new_checkout` لمئتي عميل، ومعه Flag بخطأ إملائي في مسار من كل أربعة، كأن مطوراً كتب الاسم خطأ في صفحة واحدة:

```javascript
OpenFeature.addHooks({
  after: (hc, d) => bump(`${hc.flagKey} value=${d.value} reason=${d.reason}`),
  error: (hc, err) => bump(`${hc.flagKey} ERROR ${err.code ?? err.name}`),
});
```

```text
unleash (unleash-openfeature-node-provider, start: ready)
   108  new_checkout value=false reason=UNKNOWN
    92  new_checkout value=true reason=UNKNOWN
    50  new_chekout value=false reason=UNKNOWN
flagsmith (flagsmith-provider, start: ready)
    96  new_checkout value=false reason=DISABLED
   104  new_checkout value=true reason=TARGETING_MATCH
    50  new_chekout ERROR FLAG_NOT_FOUND
```

الخطاف نفسه، والكود نفسه، ولوحتان مختلفتان. مع Flagsmith ظهر الاسم الخاطئ في عداد الأخطاء 50 مرة، فتنبيه على «أي خطأ في ال Flags» كان سوف يكتشفه في أول دقيقة. ومع Unleash لم يظهر في الأخطاء أبداً، وإنما في سطر عادي بقيمة `false`، لا يفرقه شيء عن Flag مطفأ عمداً. فالخطاف يوحد طريقة الجمع، ولا يوحد ما يجمعه، وإذا كانت لوحتك تعتمد على السبب فاكتب في وصفها أي مزود صممت له، وأعد مراجعتها عند أي تبديل.

### كم تكلف الطبقة؟ Overhead

كل طبقة إضافية لها ثمن في السرعة، فقسنا مئة ألف تقييم لل Flag نفسه وللعملاء أنفسهم مرة بمكتبة Unleash مباشرة ومرة عبر OpenFeature، وكررنا القياس ثلاث مرات:

```text
raw unleash-client: 100000 evaluations in 81 ms (0.81 us each)
OpenFeature client: 100000 evaluations in 1436 ms (14.36 us each)
raw unleash-client: 100000 evaluations in 125 ms (1.25 us each)
OpenFeature client: 100000 evaluations in 1447 ms (14.47 us each)
raw unleash-client: 100000 evaluations in 79 ms (0.79 us each)
OpenFeature client: 100000 evaluations in 1549 ms (15.49 us each)
```

التقييم عبر OpenFeature أبطأ بنحو 15 مرة، من أقل من ميكروثانية إلى نحو 14 ميكروثانية، والسبب أن كل استدعاء يمر بالخطافات ويبني كائن التفاصيل وينتظر وعداً Promise، ويترجم المزود السياق في كل مرة. وهل هذا مهم؟ لطلب دفع يقيم خمسة أعلام، الفرق نحو 70 ميكروثانية، وهو لا شيء أمام استعلام قاعدة بيانات واحد يأخذ ملي ثانية. أما إذا كان عندك كود يقيم Flag داخل حلقة على عشرة آلاف منتج في كل طلب، فقيمه مرة واحدة خارج الحلقة، لأن 14 ميكروثانية في عشرة آلاف تصبح 140 ملي ثانية. والقاعدة: الطبقة رخيصة لكل طلب، وغالية لكل عنصر.

### اختبار المطابقة قبل النقل Parity Check

كل ما سبق يقول إن النقل يحتاج إلى دليل قبل أن يصل إلى العملاء، فكتبنا السكربت الذي يقترحه الفريق لخط CI أثناء النقل: يسجل المزودين معاً في OpenFeature، كل منهما في نطاق Domain باسمه، وهي ميزة في المعيار تسمح بأكثر من مزود في التطبيق نفسه، ثم يقيم كل Flag لمئتي عميل في الاثنين، ويقارن القيم فقط، وينتهي بالرمز 1 إذا اختلفت:

```javascript
await OpenFeature.setProviderAndWait('old', new UnleashProvider({ url: process.env.UNLEASH_URL, appName: 'parity', customHeaders: { Authorization: process.env.UNLEASH_TOKEN } }));
await OpenFeature.setProviderAndWait('new', new FlagsmithOpenFeatureProvider(flagsmith));
const old = OpenFeature.getClient('old'), neu = OpenFeature.getClient('new');
neu.addHooks({ before: ({ context }) => { const { targetingKey, traits, ...rest } = context; return { traits: { ...rest, ...traits } }; } });

const checks = [   // flags that are stable (0% or 100% for everyone, or settings): safe to move
  ['free_shipping_threshold', 'getNumberValue', 200],
  ['checkout_config', 'getObjectValue', {}],
  ['new_checkout', 'getBooleanValue', false],          // still a 50% rollout: expected to differ
];
```

```text
SAME  free_shipping_threshold  0 of 200 customers differ
DIFF  checkout_config          21 of 200 customers differ
DIFF  new_checkout             86 of 200 customers differ
exit code: 1
```

في المخرج أعلاه لاحظ التالي:

- **حد الشحن متطابق:** لكل العملاء المئتين، ومنهم عشرون بالخطة المدفوعة، وهذا Flag يمكن نقله الآن.
- **`new_checkout` مختلف لـ 86 عميلاً:** وهذا متوقع كما رأينا في قسم الخانات، لأنه إطلاق جار بنسبة 50%، فهو لا ينقل الآن.
- **`checkout_config` مختلف لـ 21 عميلاً:** وهذا ما لم نتوقعه، فقد ظننا أننا كتبنا القيمة نفسها في الأداتين. والعدد 21 هو عشرون عميلاً بالخطة المدفوعة وعميل واحد هو `user-42`، لأن Flagsmith يحمل منذ مقاله تجاوز المجموعة `pro_customers` وتجاوز العميل للدعم الفني على هذا الإعداد، ونسينا أن ننسخهما إلى Unleash.

وهذا هو بالضبط ما يصنع له اختبار المطابقة: التجاوزات المنسية لا تظهر في قائمة ال Flags، ولا في قراءة القيمة الأساسية في اللوحة، وإنما في عملاء بعينهم. ولو نقلنا `checkout_config` دون هذا الفحص، لرأى عملاء الخطة المدفوعة وعميل الدعم الفني إعداداً غير إعدادهم في اليوم التالي، دون أي خطأ في أي سجل.

### التنظيف Cleanup

نحذف Container التطبيق ثم الخدمتين مع بياناتهما، لأن [المقال التالي](https://arabroot.io/articles/unleash-%D8%A7%D9%85-flagsmith-%D8%A7%D9%85-growthbook-%D9%85%D9%82%D8%A7%D8%B1%D9%86%D8%A9-%D8%A8%D8%A7%D9%84%D8%A7%D8%B1%D9%82%D8%A7%D9%85/) يعيد تشغيل الأدوات الثلاث من البداية بالإعداد نفسه حتى تكون المقارنة عادلة:

```bash
docker rm -f wr-ff-of-app
docker compose -p wr-ff-unleash down -v
docker compose -p wr-ff-flagsmith down -v
```

## خطة نقل من أداة إلى أخرى Migration Plan

بعد التجربة كتب الفريق خطة نقل يستطيع أن ينفذها في أسابيع دون أن يشعر العملاء، وهي تصلح لأي أداتين، والترتيب فيها مهم:

1. **OpenFeature أولاً في الأداة الحالية:** استبدل استدعاءات ال SDK في الكود باستدعاءات OpenFeature والأداة القديمة نفسها، وانشر ذلك وحده. هذه أكبر خطوة في الكود، ولا تغير أي قيمة يراها العميل، فإذا ظهر فرق فسببه الكود وليس الأداة.
2. **اختبار مطابقة في CI:** سكربت مثل `parity.mjs` يقيم كل Flag لمجموعة ثابتة من العملاء بالأداة القديمة ثم بالجديدة، ويفشل إذا اختلفت القيمة. أما السبب والنسخة فيسجلهما للاطلاع فقط.
3. **خطاف السياق في ملف المزود:** اكتب سياقك مسطحاً كما يقترح المعيار، وترجمه لكل مزود في ملفه، كما فعلنا مع `traits`.
4. **المزود المتعدد بالترتيب الصحيح:** الأداة الجديدة أولاً إذا كانت تقول «غير موجود» بوضوح، واختبر ذلك بFlag موجود في الأداة القديمة فقط وFlag في الجديدة فقط.
5. **انقل الأعلام المستقرة أولاً:** ما هو على 0% أو 100%، والإعدادات الثابتة، ثم Kill Switches، واترك الإطلاقات الجارية حتى تنتهي في الأداة القديمة، ولا تنقل أي تجربة جارية.
6. **المراقبة لا تعتمد على المزود:** عد الأخطاء في خطاف `error`، وراقب الخدمتين بنقاط الصحة، ولا تعتمد على أحداث مزود قد لا يطلقها المزود الآخر.
7. **احذف الأداة القديمة أخيراً:** عندما يمر أسبوع دون أي تقييم يصل إلى المزود الثاني في المزود المتعدد، أزله من `flags.mjs`، ثم احذف مكتبته من `package.json`.

ولاحظ أن الخطوة الأولى وحدها تستحق أن تفعلها حتى لو لم تكن تنوي النقل، والسبب أنها تجعل الاختبارات تعمل بمزود في الذاكرة كما في مقال المفهوم، وتجعل السجلات بصيغة واحدة عبر خطاف واحد، وتجعل قرار الأداة قراراً قابلاً للتغيير.

ويبقى سؤالان يسألهما كل من يكتب خطة نقل: من يملك الملف، وكيف نتراجع؟ أما الملكية، فملف المزود مع خطافاته ومهلته هو جزء من المنصة الداخلية، كما شرحنا في [هندسة المنصات](https://arabroot.io/articles/%D9%87%D9%86%D8%AF%D8%B3%D8%A9-%D8%A7%D9%84%D9%85%D9%86%D8%B5%D8%A7%D8%AA-platform-engineering/)، فإذا كانت عندكم عشر خدمات، فلا يكتب كل فريق ملفه، وإنما تكون حزمة داخلية واحدة يصدرها فريق المنصة، وفيها ترجمة السياق والمهلة والإيقاف والخطاف الذي يعد الأخطاء، وكل خدمة تستوردها. وبذلك يصبح إصلاح مثل خطاف `traits` أو إغلاق مؤقت Flagsmith إصلاحاً واحداً يصل إلى كل الخدمات في نشرها التالي، لا عشرة إصلاحات يتذكرها عشرة فرق.

وأما التراجع، فالمزود المتعدد يجعله سهلاً إذا خطط له: ما دامت الأداة القديمة تعمل وفيها كل الأعلام، فالتراجع عن نقل Flag هو حذفه من الأداة الجديدة، فيعود المزود المتعدد إلى سؤال القديمة في دورة التحديث التالية. ولهذا لا تحذف أي Flag من الأداة القديمة قبل أن يمر عليه أسبوع في الجديدة دون مشاكل، ولا توقف الأداة القديمة قبل أن يمر أسبوع آخر دون أي تقييم يصل إليها. والثمن أن تدفع تشغيل أداتين لأسابيع، وهو ثمن صغير أمام ليلة يكتشف فيها الفريق أن الدفع عند الاستلام اختفى من المتجر ولا أحد يعرف لماذا.

## متى لا تحتاج OpenFeature؟ When Not

بعد كل ما رأيناه قد يبدو أن OpenFeature يضيف مشاكل بقدر ما يحل، والإجابة أنه يستحق تكلفته في حالات، ولا يستحقها في أخرى:

- **يستحقها:** عندما تكون الخدمات كثيرة واللغات أكثر من واحدة، فتريد أن يقرأ كل الفريق ال Flags بطريقة واحدة، أو عندما يكون قرار الأداة غير نهائي، كما في فريقنا الذي يجرب ثلاث أدوات، أو عندما تريد اختبارات بمزود في الذاكرة دون أي خدمة.
- **لا يستحقها:** عندما يكون عندك تطبيق واحد وأداة واحدة لا تنوي تغييرها، وتستخدم ميزات خاصة بها لا يغطيها المعيار، مثل جلب كل أعلام العميل في استدعاء واحد في Flagsmith، أو بيانات التقييم Impression Data في Unleash التي رأيناها في مقال Unleash.
- **يحتاج إلى حذر:** التجارب. فدالة `trackingCallback` في GrowthBook هي التي تسجل العرض كما رأينا في مقال GrowthBook، وواجهة التتبع Tracking في المعيار اختيارية، ويقول README مزود Unleash إنه لا يطبقها. فإذا كانت ال Flags عندك تجارب تقاس، فتحقق أن المزود الذي تختاره يسجل العرض بالطريقة التي تقرؤها أداة التحليل، قبل أن تنقل أي تجربة إليه.

والحل الوسط الذي اختاره فريق المتجر أن يمر كل كود المتجر بـ OpenFeature، وأن تبقى الميزات الخاصة بكل أداة، مثل تسجيل التجارب، داخل ملف المزود نفسه، فيعرف من يقرأ الكود أن هذا الجزء هو ما سوف يحتاج إلى تعديل يوم التبديل.

## بروتوكول بدل SDK: OFREP

كل ما رأيناه يمر بمزود مكتوب لكل أداة ولكل لغة، وجودة المزود هي جودة النقل. ولذلك يعمل مشروع OpenFeature على بروتوكول بعيد موحد اسمه OpenFeature Remote Evaluation Protocol، واختصاراً OFREP، كما في [مستودع البروتوكول](https://github.com/open-feature/protocol?ref=arabroot.io): واجهة HTTP واحدة تقيم Flag أو مجموعة أعلام لسياق معين، فإذا قدمتها الأداة يكفي التطبيق مزود OFREP واحد عام بدل مزود خاص لكل أداة. والفكرة تنقل جزءاً من المشكلة إلى الخادم، فشكل السياق والأسباب يصبحان جزءاً من البروتوكول، ولكنها تعني تقييماً بعيداً لكل طلب، بثمنه الذي قسناه في مقال Flagsmith، أو تخزيناً مؤقتاً للنتائج في المزود. وقبل أن تعتمد عليه، تحقق في توثيق أداتك هل تقدم واجهة OFREP، وبأي إصدار، وفي أي خطة.

## أخطاء شائعة Common Mistakes

- **افتراض أن المعيار يوحد النتيجة:** يوحد الدوال، والسياق والأسباب والأحداث تختلف بين المزودين.
- **كتابة شكل سياق أداة في كل الكود:** مثل `traits` لFlagsmith، فتعود إلى الارتباط بالأداة، والترجمة مكانها خطاف في ملف المزود.
- **منطق في الكود على `reason` أو `variant`:** يتغير مع المزود، فاستخدمهما في السجلات فقط.
- **تنبيه على `FLAG_NOT_FOUND` وحده:** مزود Unleash لا يعيده للقيم المنطقية، فافحص الأسماء في CI.
- **الثقة بأن `OpenFeature.close()` يغلق كل شيء:** مزود Flagsmith 0.1.2 يترك مؤقت ال SDK يعمل.
- **نقل Flag في منتصف إطلاق أو تجربة:** نصف العملاء تقريباً يتبدلون بين المسارين.
- **المزود المتعدد بترتيب غير مختبر:** مزود يعيد قيمة افتراضية بدل «غير موجود» يخفي كل من بعده.
- **`setProviderAndWait` دون مهلة:** نصف دقيقة انتظار عند كل بدء والخدمة متوقفة، أو خطأ يمنع البدء.
- **فحص الجاهزية على `providerStatus`:** قد يبقى `ERROR` والقيم صحيحة، أو `READY` والقيم افتراضية.

## قائمة تحقق قبل اعتماد OpenFeature Checklist

| البند                      | كيف تتحقق                                                       |
| -------------------------- | --------------------------------------------------------------- |
| ملف واحد يعرف الأداة       | البحث عن اسم مكتبة الأداة في الكود يعيد ملفاً واحداً            |
| السياق بشكل واحد           | كل الاستدعاءات تمرر targetingKey وصفات مسطحة، والترجمة في خطاف  |
| اختبار مطابقة بين المزودين | سكربت في CI يقارن القيم لمجموعة عملاء ثابتة ويفشل عند الاختلاف  |
| مهلة البدء                 | العملية تبدأ خلال ثوان والخدمة متوقفة، والقيم افتراضية          |
| الإيقاف ينتهي              | close() ينهي العملية دون انتظار، مع كل مزود                     |
| العودة دون إعادة تشغيل     | عملية بدأت والخدمة متوقفة تلتقط القيم بعد عودتها                |
| المراقبة مستقلة عن المزود  | عداد أخطاء في خطاف error، ومراقبة نقطة الصحة لكل خدمة           |
| ترتيب المزود المتعدد مختبر | Flag في الأداة القديمة فقط وFlag في الجديدة فقط يعيدان قيمتيهما |
| لا نقل لإطلاق جار أو تجربة | قائمة الأعلام المنقولة كلها على 0% أو 100%                      |

## الخلاصة Summary

وصلنا لنهاية الموضوع، وأهم ما فيه:

- OpenFeature يوحد الاستدعاء بين الكود وأداة ال Flags، فتبديل Unleash بFlagsmith في متجرنا كان متغير بيئة وملفاً واحداً، دون أي سطر في كود المتجر.
- ولكنه لا يوحد المعنى: سبعة فروق ظهرت للاستدعاء نفسه، في الأسباب والنسخ ورموز الخطأ والأنواع والسياق والإغلاق.
- أخطرها أن مزود Flagsmith يقرأ الصفات من `context.traits`، فتجاهل `plan` وأعطى عميل الخطة المدفوعة حد 150 بدل صفر، وخطاف `before` في ملف المزود أصلح ذلك.
- مزود Unleash لا يعيد `FLAG_NOT_FOUND` للقيم المنطقية، وهذا جعل المزود المتعدد بترتيب Unleash أولاً يخفي `cod_enabled`.
- اختبار المطابقة كشف تجاوزين منسيين في `checkout_config` لواحد وعشرين عميلاً من مئتين قبل أي نقل.
- تبديل الأداة يغير صفحة 471 عميلاً من ألف عند 50%، لأن الهاش داخل كل أداة، فلا تنقل إطلاقاً جارياً ولا تجربة.
- مزود Unleash يطلق أحداث التغيير والقيم القديمة، ومزود Flagsmith لا يطلق شيئاً بعد الجاهزية، وتبقى حالته `ERROR` بعد العودة.
- الطبقة أبطأ بنحو 15 مرة لكل تقييم، 14 ميكروثانية بدل أقل من واحدة، وهذا لا يهم لكل طلب ويهم داخل الحلقات.
- مهلة ثلاث ثوان عند البدء جعلت المتجر يبدأ مع الأداتين والخدمة متوقفة، ويلتقط القيم بعد عودتها.

وفي المقال القادم والأخير من هذه السلسلة بإذن الله نضع الأدوات الثلاث جنباً إلى جنب على المتجر نفسه، ونقيس ما يهم عند الاختيار. والمقالات المرتبطة بهذا المقال:

[![](https://arabroot.io/content/images/2026/10/feature-flags-cover-cover.webp)دليلFeature Flags: انشر الكود وفعل الميزة لاحقاًكيف يفصل ال Feature Flag بين نشر الكود وإطلاق الميزة، وكيف تطلقها لجزء من المستخدمين أولاً وتوقفها فوراً إذا تعطلت.](https://arabroot.io/articles/%D9%85%D9%81%D9%87%D9%88%D9%85-feature-flags-%D9%88%D8%A7%D9%84%D8%A7%D8%B7%D9%84%D8%A7%D9%82-%D8%A7%D9%84%D8%AA%D8%AF%D8%B1%D9%8A%D8%AC%D9%8A-gradual-rollout/)[![](https://arabroot.io/content/images/2026/10/terraform-opentofu-cover-cover.webp)دليلTerraform أم OpenTofu؟ قصة تغيير الترخيص وما يعنيه لكلماذا غير Terraform رخصته في 2023 فولد منه OpenTofu، وأين يختلف المشروعان اليوم، وكيف تختار بينهما.](https://arabroot.io/articles/terraform-%D8%A7%D9%85-opentofu-%D9%82%D8%B5%D8%A9-%D8%AA%D8%BA%D9%8A%D9%8A%D8%B1-%D8%A7%D9%84%D8%AA%D8%B1%D8%AE%D9%8A%D8%B5/)[![](https://arabroot.io/content/images/2026/10/testing-types-cover-cover.webp)دليلأنواع الاختبارات للمبتدئين: من Unit إلى E2E مع Playwrightما الذي يكشفه كل نوع من الاختبارات وما الذي يفوته، وكم اختباراً تكتب من كل نوع، وأين يعمل كل منها في خط CI.](https://arabroot.io/articles/%D8%A7%D9%86%D9%88%D8%A7%D8%B9-%D8%A7%D9%84%D8%A7%D8%AE%D8%AA%D8%A8%D8%A7%D8%B1%D8%A7%D8%AA-%D9%84%D9%84%D9%85%D8%A8%D8%AA%D8%AF%D8%A6%D9%8A%D9%86-unit-%D9%88-integration-%D9%88-e2e/)[![](https://arabroot.io/content/images/2026/10/secure-pipeline-cover-cover.webp)دليلخط CI/CD آمن من البداية للنهاية على Gitea Actionsكيف تجمع فحوص الأمن في خط واحد لا يستطيع طلب الدمج تجاوزه، ثم ترسل إلى الإنتاج نفس ال Docker Image الموقعة التي فحصتها.](https://arabroot.io/articles/%D8%AE%D8%B7-ci-cd-%D8%A7%D9%85%D9%86-%D9%85%D9%86-%D8%A7%D9%84%D8%A8%D8%AF%D8%A7%D9%8A%D8%A9-%D9%84%D9%84%D9%86%D9%87%D8%A7%D9%8A%D8%A9/)

## تدريب عملي Practice

1. شغل Unleash وFlagsmith بملفات Compose من المقالين السابقين، وأنشئ فيهما Flag واحداً بالمعنى نفسه، ثم اكتب سكربت مطابقة يقيمه لمئة عميل بالمزودين ويطبع الفروق في القيمة والسبب.
2. أضف إلى `flags.mjs` خطاف `error` يعد الأخطاء بحسب `errorCode`، ثم أوقف الخدمة، وقارن ما يعده الخطاف مع كل مزود.
3. جرب المزود المتعدد بالاستراتيجية `FirstSuccessfulStrategy` بدل `FirstMatchStrategy`، وقارن ما يحدث في الترتيبين ل `cod_enabled`.

## سجل التحديثات Changelog

- نوفمبر 2026: كتابة المقال وتنفيذ التجربة على OpenFeature Server SDK 1.23.0 مع مزود Unleash الرسمي 1.0.1 (unleash-client 6.12.2، Unleash 8.3.1) ومزود Flagsmith 0.1.2 (flagsmith-nodejs 8.1.2، Flagsmith 2.288.2)، على Node.js 22.23.4 وDocker Engine 29.8.0.