تصميم البروتوكول أولاً

ما هو البروتوكول أولاً

البروتوكول أولاً هو نهج يتم فيه تصميم وإصلاح عقد التفاعل بين المكونات (الخدمات والعملاء والشركاء الخارجيين) قبل التنفيذ. يخضع الرمز والتخزين والبنية التحتية والوثائق للعقد ويتم إنشاؤها تلقائيًا منه، وليس العكس.

على عكس الكود أولاً، حيث يكون واجهة برمجة التطبيقات مجرد نتيجة ثانوية للشفرة، يجعل البروتوكول أولاً البروتوكول قطعة أثرية أساسية: فهو يمتلك مفاهيم المجال ونماذج البيانات والحالات والأخطاء ودلالات الخصوصية و SLO/SLI وحتى سياسة الإصدار.

لماذا تحتاجه ؟

اتساق الوصلات البينية وإمكانية التنبؤ بها على نطاق المنظمة.
السرعة على متن الطائرة (SDK/التوليد الذاتي المستقر/العميل، والأخطاء والرموز الموحدة).
تطور موثوق (توافق المخططات، عقود الاختبار، سياسة النسخ الواضحة).
التركيز على المنتج: ناقش السلوك وتكامل SLA و UX قبل كتابة الرمز.
التشغيل الآلي: يجمع CI/CD القطع الأثرية (العملاء، وأذرع الخادم، وأجهزة التحقق من الصحة) من مصدر واحد للحقيقة.
الأمن والامتثال: الحقوق، والإخفاء PII، وسياسات الاحتفاظ مكرسة في العقد.

النهج الأساسي

1. المصدر الوحيد للحقيقة (SSOT) - المواصفات المقروءة آليًا:

REST: OpenAPI/JSON Schema.
الأحداث والبث: AsyncAPI، Avro/JSON Schema.
RPC: Protobuf (gRPC)، Thrift، Smithy.
الرسم البياني QL: توجيهات/سياسات SDL +.
2. ترتيبات ما قبل التنفيذ: مسرد النطاق، رموز الخطأ، دلالات الخصوصية، المواعيد النهائية، إعادة التصوير، التفريغ.
3. التوليد الذاتي: العملاء/كرات الخادم، الأنواع، SDKs، عقود الاختبار، moks، مجموعات ساعي البريد، Terraform/OpenAPI Gateway config.
4. الحوكمة: البطانات/السياسات (التسمية، الاستعداد، المرشحات، الأخطاء)، المراجعة عبر نقابة API، استشارات التغيير للإصدارات الرئيسية.
5. التوافق: التحقق الصارم من الانتشار «المضاف فقط»، والتحرير الدلالي، والاختبارات التي يحركها المستهلك/الكناري.
6. قابلية الملاحظة على مستوى العقد: يتم توضيح معرفات الارتباط ونماذج الخطأ وميزانيات التأخير في البروتوكول.

كيف تبدو العملية (هيكل عظمي)

1. البدء: إحاطة المنتج → رحلات المستخدمين → واجهة برمجة التطبيقات/بروتوكول PRD (الموارد/الأساليب/الأحداث، جيش تحرير السودان/جيش تحرير السودان، الأخطاء، الحدود).
2. النمذجة: مسودة المواصفات (OpenAPI/AsyncAPI/Proto) + مخططات البيانات، قاموس المصطلحات.
3. العقود وتكامل UX: أمثلة الحمولة، وعقود الخطأ، وخرائط الحالة، وقواعد الإصدار.
4. المراجعة والحوكمة: الخطوط/المعايير، مناقشة ثوابت المجال، قفل MGC (عقد الضمان الأدنى).
5. التوليد التلقائي للقطع الأثرية: SDKs، الطعنات، إصلاحات الاختبار، كسور البنية التحتية (البوابات، نطاقات IAM).
6. اختبارات التنفيذ والعقود: يخضع الموردون والمستهلكون لفحوصات التوافق في CI.
7. إمكانية الرصد و SLO: تتبع معرف الارتباط، كتالوج الخطأ، ميزانيات الاسترجاع/المهلة.
8. الإصدارات والتطور: المضاف أولاً، سياسة الرفض، الكناري، أعلام القدرة A/B.

بروتوكولات وأساليب التفاعل

REST/HTTP

المعايير: نموذج الموارد، «GET/POST/PATCH/DELETE»، التثبيت (المؤشر)، المرشحات، الفرز.
الحقول والمخططات: مخطط JSON، تنسيقات ("وقت التاريخ"، "uuid')، الثوابت (regex/enum/min-max).
الأخطاء: تنسيق واحد («نوع»، «رمز»، «عنوان»، «تفاصيل»، «تتبع _ معرف»)، رسم خرائط لأكوام HTTP.
التحكم في التغيير: ETag/If-Match، المفاتيح الخفية لـ POST، الدلالات الصريحة 409/422.

gRPC/RPC

Protobuf: ترقيم ثابت للعلامة، «اختياري»، عدم السماح بإعادة استخدام الحقول المحذوفة.
المواعيد النهائية والأولويات في العقد ؛ الأوضاع المستقرة (موافق، INVALID_ARGUMENT، FAILED_PRECONDITION، إلخ).
البث: مواصفات طلب الرسالة، الضغط الخلفي، المقطورات النهائية.

الحدث مدفوع (كافكا/ناتس/إس إن إس/إس كيو إس)

AsyncAPI: الموضوعات/القنوات، مفاتيح التقسيم، اتفاقيات مفتاح التفريغ، الاحتفاظ، دلالات مرة واحدة بالضبط "مقابل" مرة واحدة على الأقل. "

الحدث الأساسي والإثراء: حمولة وتمديدات دنيا منفصلة ؛ النسخة 'event _ type '/' schema _ version'.
الخصوصية: 'event _ id', 'production _ id', policy on retrays and deuplication.

الرسم البياني QL

SDL كعقد، توجيهات للنقض، قيود على العمق والتعقيد، عقد رموز الخطأ/التمديدات.

التكامل مع المبادئ المعمارية

الهرم العكسي/المسار النقدي أولاً: في المواصفات، إبراز MGC (الحد الأدنى الإلزامي)، الامتدادات - من خلال '؟ تشمل = '/القدرات.
الطرق المعبدة: مجموعة من نماذج المواصفات الجاهزة (الدفع، KYC، التدقيق، البحث، الملفات) + البطانات.
API Gateways & Service Mesh: السياسات القائمة على العقود (حدود الأسعار، ونطاقات auth، والإعادة، وقواطع الدوائر).

التحديث والتطور

• طفيفة = حقول/قنوات مضافة فقط.
• Major = كسر التغييرات (الحذف، إعادة التسمية، تغيير الدلالات).
• سياسة الرفض: نوافذ الدعم، رؤوس «غروب الشمس»، أحداث الإخطار.
• العقود التي يحركها المستهلك (CDC): التحقق من أن واجهة برمجة التطبيقات الحالية ترضي مستهلكين معينين.
• دليل المخطط: سجل المخطط/سجل القطع الأثرية مع قواعد التاريخ والتوافق (BACKWARD/FORWARD/FULL).

السلامة والامتثال

المصادقة/الإذن كجزء من العقد (النطاقات OAuth2/OIDC، وامتحانات النقل، ومطالبات الفريق العامل المشترك).
PII/PCI: الإخفاء، وتنسيقات الترميز، والحقول ذات أوضاع التخزين الخاصة/TTL.
سياسات مراجعة الحسابات: الخصائص المطلوبة ('فاعل'، 'موضوع'، 'إجراء'، 'حدث _ في'، 'تتبع _ هوية').
الحدود: رؤوس حدود الأسعار، والحصص، وأحجام الرسائل، والمواعيد النهائية.

قابلية رصد العقد

الارتباط/معرف الطلب: مطلوب في المواصفات.
كتالوج الخطأ - قائمة ثابتة للرموز و SLAs لحلها.
SLI/SLO: p50/p95، نسبة الاستجابات الناجحة، نسبة الأحداث المتوافقة، نسبة التكرارات الحمقاء.

الاختبار والجودة

اختبارات العقد (المزود ↔ المستهلك)، مخطط diff في CI، توليد خوادم وهمية.
العينات الذهبية: أمثلة مرجعية للطلبات/الردود، تركيبات e2e.
حقن الفوضى/الكمون: فحص المهلة/إعادة الدفع، تحلل الامتدادات عند حفظ MGC.

نماذج نطاق العينة

الدفع (REST + الأحداث)

«البريد/المدفوعات» → «201 تم إنشاؤها» مع «الدفع _ معرف»، «الحالة = المأذون به».
دفع الحدث. المأذون به. v1 '(ядро): «{payment_id، المبلغ، العملة، الطريقة، occurred_at}».
مدفوعات التمديد. إثراء. v1 ': معدل الخطر، geo، بصمة الجهاز.
الأخطاء: «422» (التحقق)، «402» (الدفع المطلوب)، «409» (مكرر).
وجيش تحرير السودان: الإذن ≤ 800 السيدة p95 ؛ حدث النواة ≤ 2c lag p95.

طوابير KYC (gRPC +)

RPC 'StartVerification (user_id)' → 'operation _ id'.
أحداث التقدم في الموضوع 'kyc. (). v1 '(' معلقة '→' معتمدة/مرفوضة ').
ينص العقد على حقول PII، وفترة الصلاحية، والإخفاء، ورموز الفشل السببي.

التدقيق (حدث فقط)

'استحسان. المسجلة. v1 '(ядро):' فاعل '،' موضوع '،' إجراء '،' حدث _ at'، 'تتبع _ id'.
الإثراء: IP، الجهاز، geo - حدث/خيط منفصل، لا يحجب النواة.

الأدوات والأتمتة (مكدس تقريبي)

Спеки: OpenAPI/AsyncAPI/Protobuf/Avro/GraphQL SDL.
Линтеры: Spectral, OpenAPI Diff, Buf (protobuf), Confluent SR compatibility checks.
Генерация: مولد OpenAPI، بوف/إي، رسم بياني QL Codegen، مولد AsyncAPI.
البوابة: Kong/Apigee/Azure/GCP GW، المبعوث.
Тесты: Pact/CDC، Dredd، Schemathesis، Hoverfly، MockServer.
السجل: دليل المخططات + سجل المخطط/سجل القطع الأثرية.
الوثائق: Redocly/Stoplight/Swagger-UI/GraphiQL/Explorer.

الأنماط المضادة

الرمز أولاً عن طريق الصدفة: «MVP أولاً على وحدات التحكم»، المواصفات اللاحقة للوقائع، التناقض بين التوثيق والسلوك.
Swagger-wash: OpenAPI رسمي بدون قواعد حقيقية (أخطاء، حدود، SLAs، إصدارات).
كسر التوافق: تمت إزالة الحقل/النوع المتغير بدون نسخة رئيسية ؛ إعادة استخدام علامات protobuf.
استجابة «سميكة» بدون ترقيم/مرشحات ؛ الافتقار إلى الخصوصية.
الأمن خارج العقد: auth/Scopes موصوفة في الويكي، ولكن ليس في المواصفات.

العلاقة بتنظيم العملية

نقابة API: أمناء المعايير، مراجعات التغيير، التدريب.
مستندات التصميم: لكل واجهة برمجة التطبيقات - PRD، ADR (الحلول)، SLA، مصفوفة المخاطر.
إدارة التغيير: عملية RFC، ملاحظات الإصدار، أدلة الهجرة، الجدول الزمني للانحراف.
Paved Road & Complates: مولدات إطار الخدمة من المواصفات (الهيكل العظمي للمعالج، التحقق، تسجيل الأشجار).

قوائم مرجعية

قبل البدء

• هناك مسرد PRD ومسرد نطاق.
• نمط مختار (REST/gRPC/Event/GraphQL) وتنسيق المخطط.
• MGCs، الأخطاء، SLA/SLOs، قواعد الخصوصية المحددة.

قيد التطوير

• المواصفات تمرر البطانات والاستعراض.
• تم تكوين التوليد التلقائي SDK/Stable/Fixture.
• اختبارات العقد (CDC) مدرجة في CI ؛ كتل المخطط diff غير متوافقة التغييرات.

قبل الإصدار

• توثيق المدمج مع أمثلة ورموز خطأ.
• يمكن ملاحظته تعاقديًا: معرف الارتباط، كتالوج الخطأ، لوحات معلومات SLI.
• يتم الإعلان عن سياسة التحرير والاستنكار.

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

كيف يختلف البروتوكول أولاً عن واجهة برمجة التطبيقات أولاً ؟

غالبًا ما يتم استخدام المصطلحات بالتبادل. في هذه المادة في إطار البروتوكول أولاً، نؤكد على صرامة العقد وتغطية جميع الأنماط (REST/RPC/Events/GraphQL)، بما في ذلك SLA والسلامة وقابلية الملاحظة.

هل سيؤدي هذا إلى إبطاء التطور ؟

قد تكون البداية أطول قليلاً، ولكن بعد ذلك نفوز بالتكامل والاستقرار وسرعات التطوير الموازية (التوليد التلقائي، SDKs المستقرة).

ماذا تفعل بالتجارب السريعة ؟

استخدم نسخ «مشروع» من المخططات (مسودة)، والأعلام المميزة وصناديق الرمل، ولكن لا تتخطى البطانات وقواعد التوافق الأساسية.

المجموع

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