اختبار عقد API

1) لماذا اختبار العقد

يلتقط العقد توقعات العملاء ووعود المزود: الطرق/الأساليب، والرؤوس، ومخططات الجسم، والحالات، ودلالات الأخطاء، والقيود. الهدف هو التقاط التغييرات غير المتوافقة قبل التكامل وإصدار الإصدارات بأمان، دون E2E ثقيلة.

2) النهج

العقود التي يحركها المستهلك (CDC): يشكل العميل التوقعات (الميثاق والنظائر) ؛ يقوم مقدم الخدمة بالتحقق منها بانتظام.
المواصفات: عقد كمصدر وحيد للحقيقة (OpenAPI/Protobuf/GraphQL SDL) ؛ تثبت صحة التنفيذ مقابل المواصفات.
قائمة على الحدث: مخططات الرسائل (Avro/JSON Schema/Protobuf) + قواعد توافق الوسيط/السجل.

3) تدفق مواصفات HTTP/REST

1. العقد: OpenAPI 3. x (مخططات، أمثلة، رموز).
2. تحليل الوبر والإحصائيات: الأسلوب، الحقول المطلوبة، الرموز الموحدة.
3. التحقق من صحة التنفيذ: مولد اختبار OpenAPI (نهج التخطيط/Dredd) + السلبيات اليدوية.
4. اللقطات: التقاط استجابات العينات، دلالات ETag، رؤوس الغباء.

yaml paths:
/v1/payments:
post:
responses:
"201": { $ref: "#/components/responses/PaymentCreated" }
"409": { description: Duplicate by Idempotency-Key }
"422": { description: Schema/Business validation failed }

4) CDC (نهج الميثاق)

1. يكتب المستهلك اختبارًا، ويولد ملف اتفاقية (توقعات).

2. منشور في وسيط (قطعة أثرية).

3. يقوم المزود في CI برفع الخدمة (أو رف العقد)، والتحقق من الاتفاقية.

4. يحسب السمسار مصفوفة التوافق can-i-puble.

js pact
.given("wallet exists")
.uponReceiving("get wallet")
.withRequest({ method:"GET", path:"/v1/wallets/w123", headers:{ "Authorization": term({generate:"Bearer x", matcher:/^Bearer\s.+/}) }})
.willRespondWith({
status: 200,
headers: { "Content-Type": "application/json" },
body: like({ id:"w123", currency: "EUR", balance: 0 })
});

5) عقود gRPC/Protobuf

العقد هو «.proto» مع إصدار الحزم/الخدمة.
التوافق: لا تعيد استخدام العلامات، ولا تضف إلا علامات جديدة ذات طابع اختياري، ولا تحذف الحقول المستخدمة ؛ أرقام الاحتياطي.
الاختبارات: توليد طعنات الخادم/العميل، تأجير حالة تم إنشاؤها تلقائيًا + سلبيات (حقول غير معروفة، حدود الحجم).

6) عقود الأحداث (كافكا/ناتس/...)

Схемы: Avro/JSON Schema/Protobuf в Schema Registry.
سياسة التوافق «متخلفة» (غالبًا ما تكون كافية) أو «ممتلئة».
اختبارات المنتجين: تثبت صحة الرسالة مقابل المخطط ؛ اختبارات المستهلك: تقبل الإصدارات القديمة والجديدة.
الثوابت: مفاتيح الخصوصية، النظام/التكرار، دلالات التثبيت.

json
{"type":"record","name":"PayoutCreated","fields":[
{"name":"payoutId","type":"string"},
{"name":"amount","type":"double"},
{"name":"currency","type":{"type":"string","logicalType":"iso-4217"}}
]}

7) التوافق والنسخ

متوافق مع الخلف (الحد الأدنى الموصى به): إضافة حقول اختيارية، لا تكسر الحقول الموجودة.
متوافقة إلى الأمام: يتجاهل المستهلكون المجالات غير المعروفة.
ممتلئ: كلاهما.
الإصدار: "المسار (/v1)"، "قبول: الطلب/vnd. العلامة التجارية. v2 + json ', «proto package v2».
سياسة الانحراف: نافذة الإنتاج (على سبيل المثال، 90 يومًا)، الترويسات/الأحداث التحذيرية.

8) السلبية والأخطاء هي أيضا عقد

توحيد الرموز: 400/401/403/404/409/422/429/5xx، الحقول الإلزامية 'code'، 'message'، 'trace _ id'.
الأحجام/الحدود جزء من العقد (413/414/431).
الخصوصية: سلوك التكرار (409 مقابل 201 نفس الهوية).
العناوين: «Retry-After» في 429/503، «Idempotency-Key»، «Content-Language»، إلخ.

json
{ "code":"validation_error", "message":"amount must be ≥ 1", "trace_id":"..." }

9) البيانات التي يديرها العقد

أمثلة - مباشر، تم التحقق من صحته في CI.
تركيبات CDC ضئيلة وحتمية.
توليد البيانات - على أساس الممتلكات للأرقام/التواريخ ؛ ولكن ليس لكسر استقرار اللقطات.

10) خط الأنابيب في CI/CD (مرجع)

1. الوبر/التحقق: OpenAPI/Proto/Avro («التحقق من صحة»، أسلوب - линер).
2. Publish: Contract as artifact (broker/registry).
3. تحقق: يقوم المزود بتشغيل حزم CDC/اختبارات المواصفات.
4. بوابة can-i-publoy: لا يسمح بالإطلاق بدون مصفوفة خضراء.
5. يتحقق Diff-Verifies من أن التغييرات دلالية.
6. التقرير: JUnit/HTML، قائمة الانتهاكات/التعاريف.

yaml jobs:
lint:...
publish-contract: needs: [lint]
verify-provider: needs: [publish-contract]
can-i-deploy:
if: always()
steps: [run: pact-broker can-i-deploy...]

11) الأدوات (حسب فئة المهام)

الوبر/المصدقات: بطانات openapi، protobuf-lint، أدوات أفرو.
CDC: Pact family/broker، Spring Cloud Contract، Hoverfly (سجلات/إعادة HTTP).
عدائي المواصفات: مخطط/نهج يشبه Dredd، اختبار Postman + JSON Schema.
Diff: semantic-diff OpenAPI/Proto/Avro (يكتشف تغييرات كسر).
الحاويات: Testcontainers لرفع المزود/مكتب العقد.

12) أنتيباترن

«حوض خاص» منفصل عن الرمز → عدم التزامن. إبقاء العقد بالقرب من الخدمة.
Moki من خدمة طرف ثالث بدلاً من عقد → الهشاشة أثناء التحديثات.
استجابات/توليد عشوائي دون ارتباط بمخطط التقشر →.
الأنواع المتغيرة/الحقول الإلزامية بدون نسخة.
تمديدات صامتة دون إخطار/تخفيض.
لا توجد عقود سلبية ورموز خطأ.

13) تفاصيل iGaming/Finance

إضفاء الطابع الرسمي على مجالات المال: «المبلغ» - الفاصلة العشرية مع الحجم والعملة - ISO-4217، ثوابت المبالغ.
عقود الدفع/الخطاف الشبكي: HMAC/mTLS، مكافحة إعادة التشغيل (نافذة «X-Timestamp»)، الخصوصية، «Retry-After».
المنطقة/المستأجرون: الرؤوس الإلزامية «X-Tenant/X-Region»، توطين الرسائل.
الأحداث: عدم تغيير السجلات (التدقيق)، مفاتيح التفريغ، ضمانات التسليم (مرة واحدة على الأقل + المعالجات الخفية).

14) أمثلة على «الهياكل العظمية» للاختبارات

14. 1 أسلوب التخطيط (زائف)

bash schemathesis run openapi. yaml --checks all --hypothesis-deadline=200

14. 2 ساعي البريد كعداء المواصفات

js pm. test ("Scheme/v1/wallets/{ id} is valid," () => {
const schema = pm. collectionVariables. get("wallet_get_schema");
pm. expect(ajv. validate(JSON. parse(schema), pm. response. json())). to. be. true;
});

14. 3 التحقق من مزود مركز السيطرة على الأمراض (Pseudo)

bash pact-broker can-i-deploy --pacticipant wallets --version $SHA --to-environment staging

15) قائمة التحقق من الاستعداد

• العقود في المستودع، تصادق CI على القطع الأثرية وتنشرها.
• تمكين مراكز مكافحة الأمراض والوقاية منها من عمليات التكامل الحاسمة ؛ السمسار/المصفوفة «can-i-publie».
• توثيق سياسة التوافق (HTTP/gRPC/Events) ؛ الدلالي التلقائي.
• العقود السلبية: أخطاء، حدود الحجم، الغباء، «إعادة التجربة بعد».
• بيانات الاختبار حتمية ؛ تم دعم لقطات من الأمثلة.
• الإصدار والاستنكار: المواعيد النهائية والإشعارات والرؤوس.
• بالنسبة للأحداث - سجل المخطط وطريقة التوافق ؛ يقوم المنتج/المستهلك باختبار كلا الإصدارين.
• القطع الأثرية: JUnit/HTML، تقارير diff/التحقق، مصفوفة التوافق.
• إجراء الحادث: التراجع السريع عن العقد/علم الميزة، والإخطار إلى شركات التكامل.

16) TL ؛ د

التقاط التوقعات في العقود وتشغيلها تلقائيًا: مركز السيطرة على الأمراض لتوقعات العملاء، واختبارات المواصفات لمطابقة التنفيذ، وتسجيل المخطط للأحداث. الاحتفاظ بسياسات توافق صارمة وعقود سلبية (أخطاء وحدود وحماقة). لا يمكنك الإطلاق بدون مصفوفة خضراء can-i-pospoit و semantic-diff دون كسر التغييرات.