كيفية توثيق واجهات Kafka البرمجية: المواضيع والمخططات والعقود

لا يحتوي موضوع Kafka على نقطة نهاية يمكن قراءتها، لذا يجب تدوين عقد البيانات الخاص به كتابيًا. إليك ما يجب توثيقه لكل موضوع، وكيفية التعبير عن ذلك باستخدام AsyncAPI، وكيف تجعل وكيل البرمجة الخاص بك يحافظ على توافق الوثائق مع الواقع.

Ashley Innocent

Ashley Innocent

16 نوفمبر 2026

كيفية توثيق واجهات Kafka البرمجية: المواضيع والمخططات والعقود

Apidog للمؤسسات

النشر على الخوادم المحلية

SSO و RBAC

متوافق مع SOC 2

استكشف Apidog للمؤسسات

لتوثيق واجهات Kafka برمجية التطبيق (APIs)، اكتب عقدًا (contract) لكل موضوع (topic). يجب أن يذكر اسم الموضوع، ومفتاح الحدث، ومخطط الحمولة (payload schema)، والترويسات (headers)، وضمانات الترتيب والتسليم، ومجموعات المستهلكين، ومدة الاحتفاظ، والمالك. ثم خزّن هذا العقد بجوار وثائق واجهات HTTP الخاصة بك، ليقرأ المنتجون والمستهلكون مصدرًا واحدًا للحقيقة بدلًا من هندسة الرسائل عكسيًا من مجموعة حية.

يغطي هذا الدليل كل جزء من أجزاء العقد، وكيفية كتابته بتنسيق AsyncAPI، وكيفية تطوير المخططات بأمان، وكيفية جعل وكيلك البرمجي يقوم بالعمل باستخدام Apidog CLI.

إذا كنت جديدًا على التصميم الموجّه بالأحداث (event-driven)، ابدأ بدليل كيفية بناء واجهات برمجية موجّهة بالأحداث ودليل Webhooks والمعمارية الموجّهة بالأحداث.

ما هي واجهة Kafka البرمجية؟

واجهة Kafka البرمجية هي مجموعة المواضيع وصيغ الرسائل وقواعد التسليم التي تستخدمها الخدمات لتبادل الأحداث عبر مجموعة Apache Kafka. على عكس واجهة REST، لا يستدعي أحد نقطة نهاية وينتظر استجابة. يكتب المنتجون السجلات في المواضيع، ويقرأها المستهلكون وفق جدولهم الزمني الخاص، ويكمن العقد في بنية تلك السجلات ومعناها.

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

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

ما يجب توثيقه لكل موضوع Kafka

كل موضوع يحتاج إلى الحقائق الأساسية نفسها. استخدم هذا الجدول كقائمة تحقق:

حقل العقد ما يجب تدوينه مثال
اسم الموضوع الاسم الكامل وقاعدة التسمية orders.order-placed.v1
الغرض جملة واحدة توضح معنى الحدث «طلب اجتاز الدفع وجاهز للشحن»
مفتاح الحدث أي حقل هو المفتاح، ولماذا customerId، بحيث تبقى طلبات العميل الواحد مرتبة
مخطط الحمولة كل حقل ونوعه واعلامه الإلزامي وصيغته JSON Schema أو Avro أو Protobuf
الترويسات اسم ونوع ومعنى كل ترويسة traceparent، schema-version
الأقسام والترتيب عدد الأقسام ووعد الترتيب 12 قسمًا، مرتبة حسب customerId
دلالات التسليم مرة واحدة على الأقل، منتج أصلي (idempotent)، المعاملات مرة واحدة على الأقل؛ يجب على المستهلكين إزالة التكرار بناءً على orderId
مجموعات المستهلكين المجموعات المعروفة وما تفعله كل منها billing-service، email-notifier
الاحتفاظ مدة بقاء السجلات قابلة للقراءة 7 أيام
الملكية الفريق المالك وجهة الاتصال وسياسة الإصدارات فريق الدفع (Checkout)، #checkout-events

سطرا الترتيب والتسليم هما الأهم: لا يمكن للقراء استنتاجهما من رسالة نموذجية.

مخطط عقد موضوع Kafka: يكتب منتج أحداثًا بمفاتيح إلى موضوع مقسّم يقرأه مجموعتا مستهلكين، مع حقول العقد بجانبه

كيفية توثيق واجهات Kafka البرمجية في 6 خطوات

  1. اسرد كل موضوع ومالكه. اسحب قائمة المواضيع من مجموعتك وحدّد من يكتب في كل واحد منها.
  2. حدّد المفتاح. دوّن أي حقل هو المفتاح وما يعنيه ذلك بالنسبة للترتيب.
  3. اكتب مخطط الحمولة. صِف كل حقل بتنسيق JSON Schema أو Avro أو Protobuf.
  4. صِف الترويسات والبيانات الوصفية. أدرج ترويسات التتبع وإصدار المخطط ونوع المحتوى.
  5. اذكر الضمانات. وثّق دلالات التسليم ونطاق الترتيب ومدة الاحتفاظ ومجموعات المستهلكين.
  6. انشره في المكان الذي يبحث فيه الناس. ضع العقد بجوار وثائق واجهات HTTP الخاصة بك وطبّق عليه إصدارات كما تفعل مع الشيفرة.

الخطوتان 1 و2: المواضيع والمفاتيح

نمط تسمية مثل <domain>.<event>.<version> يخبر القراء بمن يملك الموضوع وأي إصدار يقرؤون. ثم وثّق المفتاح، لأنه يحدد القسم. تذكر وثائق Kafka أن «الأحداث التي تحمل مفتاح الحدث نفسه (مثل معرّف عميل أو مركبة) تُكتب في القسم نفسه»، وأن المستهلكين يقرؤون أحداث القسم «بالترتيب نفسه الذي كُتبت به».

لذا يجب أن يقول عقدك «مرتب حسب customerId»، لا «مرتب» فحسب. يعد Kafka بالترتيب داخل القسم فقط، وليس أبدًا عبر الموضوع بأكمله.

الخطوة 3: مخطط الحمولة

الحمولة هي الجزء الذي يبني المستهلكون شيفرةimgهم على أساسه، لذا صِفها حقلاً بحقل. إليك مخطط JSON Schema لحدث order-placed:

{
  "type": "object",
  "required": ["orderId", "customerId", "totalCents", "currency", "placedAt"],
  "properties": {
    "orderId": { "type": "string", "description": "Unique order ID; use it to deduplicate" },
    "customerId": { "type": "string", "description": "Also the record key" },
    "totalCents": { "type": "integer", "minimum": 0 },
    "currency": { "type": "string", "enum": ["USD", "EUR", "GBP"] },
    "placedAt": { "type": "string", "format": "date-time" },
    "couponCode": { "type": ["string", "null"] }
  }
}

الوصف «use it to deduplicate» يخبر المستهلك ما يجب فعله بالحقل، وليس نوعه فقط. جديد على هذا التنسيق؟ اقرأ ما هو JSON Schema.

الخطوتان 4 و5: الترويسات والضمانات

اسرد كل ترويسة (سياق التتبع، إصدار المخطط، نوع المحتوى) واذكر ما إذا كان يمكن للمستهلكين الاعتماد عليها. ثم دوّن ضمانة التسليم بمصطلحات Kafka نفسها. تشير وثائق تصميم Kafka إلى أن «Kafka يضمن التسليم مرة واحدة على الأقل افتراضيًا»، أي أن الرسائل «لا تُفقد أبدًا ولكن قد يُعاد تسليمها». إذا كان منتجك يستخدم الخيار الأصلي (idempotent) أو المعاملات، فاذكر ذلك. وإذا لم يكن كذلك، فأخبر المستهلكين بإزالة التكرار، وسمِّ الحقل الذي يجب إزالة التكرار بناءً عليه.

وثّق مجموعات المستهلكين أيضًا. داخل كل مجموعة مشتركة، يُستهلك القسم «بواسطة مستهلك واحد فقط» في كل لحظة. يخبر ذلك القراء بمدى إمكانية توسّع المجموعة أفقيًا: مستهلك نشط واحد لكل قسم.

اكتب العقد بتنسيق AsyncAPI

تحتاج الأدوات إلى تنسيق قابل للقراءة آليًا، وهو بالنسبة إلى Kafka عادةً AsyncAPI، وهي مواصفة «تُستخدم لوصف الواجهات البرمجية الموجّهة بالرسائل بتنسيق قابل للقراءة آليًا». وهي تؤدي الدور الذي يؤديه OpenAPI لواجهات REST.

تحتوي وثيقة AsyncAPI 3.0 على info وservers وchannels وoperations وcomponents. يرتبط القناة (channel) بموضوع من خلال address الخاص بها، ولكل عملية action قيمتها send أو receive:

asyncapi: 3.0.0
info:
  title: Orders events
  version: 1.0.0
channels:
  orderPlaced:
    address: orders.order-placed.v1
    messages:
      orderPlaced:
        $ref: '#/components/messages/orderPlaced'
operations:
  publishOrderPlaced:
    action: send
    channel:
      $ref: '#/channels/orderPlaced'
components:
  messages:
    orderPlaced:
      payload:
        $ref: './schemas/order-placed.json'

يوفّر AsyncAPI أيضًا روابط (bindings) خاصة بـ Kafka على مستوى الخادم والقناة والعملية والرسالة. وهي المكان الذي تُوضع فيه التفاصيل الخاصة بـ Kafka التي لا تستطيع الحقول العامة التعبير عنها. احتفظ بالمواصفة في مستودع المنتج، بحيث يغيّر طلب السحب (pull request) الذي يعدّل حدثًا عقده أيضًا.

تطوير مخططات Kafka: وثّق قاعدة التوافق

مخططك سيتغير حتمًا. يجب أن يذكر العقد أي التغييرات آمنة. إذا كنت تستخدم سجل مخططات (schema registry)، فوثّق وضع التوافق الخاص به. تسرد وثائق تطوير المخططات من Confluent هذه الأوضاع، وتلاحظ أن «نوع التوافق الافتراضي في Confluent Schema Registry هو BACKWARD»:

الوضع من يمكنه قراءة ماذا
BACKWARD يمكن للمستهلكين على المخطط الجديد قراءة البيانات المكتوبة بالمخطط السابق
BACKWARD_TRANSITIVE يمكن للمستهلكين على المخطط الجديد قراءة البيانات من جميع المخططات السابقة
FORWARD يمكن للمستهلكين على المخطط السابق قراءة البيانات المكتوبة بالمخطط الجديد
FORWARD_TRANSITIVE يمكن للمستهلكين على أي مخطط سابق قراءة البيانات المكتوبة بالمخطط الجديد
FULL متوافق للخلف وللأمام مع المخطط السابق
FULL_TRANSITIVE متوافق للخلف وللأمام مع جميع المخططات السابقة
NONE فحوصات التوافق معطّلة

عمليًا، في وضع BACKWARD يمكنك إضافة حقول اختيارية وإزالة الحقول التي لها قيم افتراضية. إعادة تسمية حقل إلزامي أو تغيير نوعه تكسر المستهلكين. عندما تحتاج إلى تغيير كاسر، انشر إصدارًا جديدًا من الموضوع (orders.order-placed.v2)، ووثّق كليهما، وحدّد تاريخًا لإيقاف القديم.

اجعل وكيلك البرمجي يوثّق واجهات Kafka البرمجية باستخدام Apidog CLI

العقود المكتوبة يدويًا تنحرف بمجرد أن يغيّر أحدهم منتجًا. يستطيع وكيلك البرمجي قراءة شيفرة المنتج، وكتابة المخططات، وإبقاء الوثائق متزامنة بينما تتولى أنت المراجعة. يمنح Apidog CLI‏ Claude Code أو Codex أو Cursor أو أي وكيل طرفية الأوامر اللازمة لذلك في مشروع Apidog.

ثبّت واجهة السطر البرمجي، وسجّل الدخول، وأضف مهارة Apidog ليعرف وكيلك الأوامر:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install

يمكنك أيضًا تسليم الإعداد إلى الوكيل: أخبره أن يقرأ دليل تثبيت Apidog CLI وأن يجهّز نفسه بنفسه.

ثم أعطِ وكيلك أمرًا واحدًا:

Read the Kafka producers in ./services/orders. For every topic they write to,
create an Apidog data schema in project <projectId> for the message payload,
then create one Markdown doc per topic with the key, headers, ordering,
delivery guarantee, consumer groups, retention and owner. Validate every
payload before you write it.

يتحقق الوكيل من بنية الحمولة، ويتحقق من صحة ملفه، ثم يكتب المخطط وصفحة العقد:

apidog cli-schema get schema-create
apidog cli-schema validate schema-create --file order-placed.schema.json
apidog schema create --project <projectId> --file order-placed.schema.json
apidog cli-schema get doc-create
apidog doc create --project <projectId> --file order-placed.doc.json
apidog schema list --project <projectId>

يخزّن الأمر apidog schema create الحمولة كمخطط بيانات قابل لإعادة الاستخدام. يمكن لنقاط نهاية HTTP لديك الإشارة إلى النموذج نفسه، بحيث يغطي النموذج Order المعرّف مرة واحدة استجابة REST وحدث Kafka معًا. يكتب الأمر apidog doc create وثيقة Markdown في شجرة المشروع، وهي تحتوي على عقد الموضوع من الجدول أعلاه. عندما يتغير منتج، أعد تشغيل الأمر وسيستخدم الوكيل الأمر apidog schema update. للاطلاع على شرح أطول للعمل الموجّه بالوكلاء في التوثيق، راجع كيفية توثيق الواجهات البرمجية من واجهة السطر البرمجي وApidog CLI في Claude Code.

مخطط سير العمل: يقرأ وكيل برمجي شيفرة المنتج ويشغّل apidog schema create وapidog doc create في مشروع Apidog واحد

خطوة واحدة تبقى داخل التطبيق. توثّق ميزة Custom Protocol API في Apidog نقاط نهاية Kafka بجوار نقاط نهاية HTTP: اختر New Other Protocol APIs، ثم Other Custom Protocol API، واختر Kafka كبروتوكول، واملأ عنوان URI (الموضوع)، والاسم، والحالة، والمشرفين، والوسوم، والوصف. تشارك هذه الإدخالات شجرة المجلدات والبحث والمشاركة السريعة (Quick Share) مع وثائق HTTP لديك. لا تملك واجهة السطر البرمجي أمرًا لنقاط نهاية البروتوكول المخصص حتى الآن، لذا فهذا هو الجزء الوحيد الذي تنشئه يدويًا.

تغطي النسخة المجانية من Apidog حتى 4 مستخدمين، بحيث يمكن لفريق صغير الاحتفاظ بوثائق REST وKafka الخاصة به في مشروع واحد دون أي تكلفة.

الأسئلة الشائعة

هل هناك OpenAPI لـ Kafka؟

تؤدي AsyncAPI هذا الدور. فهي تصف الخوادم والقنوات (المواضيع) والعمليات وحمولات الرسائل بصيغة YAML أو JSON، مع روابط خاصة بـ Kafka.

هل أحتاج إلى سجل مخططات لتوثيق واجهات Kafka البرمجية؟

لا، لكنه مفيد. الوثائق تذكر القواعد؛ أما السجل فيفرضها وقت الكتابة. إذا كنت تشغّل واحدًا، فوثّق وضع التوافق الخاص به.

ما الفرق بين توثيق موضوع Kafka وتوثيق نقطة نهاية REST؟

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

هل يمكن لـ Apidog اختبار رسائل Kafka؟

توثّق Apidog نقاط نهاية Kafka من خلال Custom Protocol API، لكنها لا ترسل أو تستهلك رسائل Kafka. استخدمها للاحتفاظ بالعقد ومخططات الحمولة، واختبر شيفرة المنتج والمستهلك باستخدام مكتبة عميل Kafka لديك.

ما مدى تكرار تحديث توثيق Kafka؟

كلما غيّر منتجٌ رسالةً. اربط ذلك بمراجعة الشيفرة: طلب السحب الذي يغيّر الحدث يحدّث العقد، أو يعيد وكيلك توليده باستخدام Apidog CLI.

ممارسة تصميم API في Apidog

اكتشف طريقة أسهل لبناء واستخدام واجهات برمجة التطبيقات