تست قرارداد API

1) چرا تست قرارداد

این قرارداد انتظارات مشتری و وعده های ارائه دهنده را شامل می شود: مسیرها/روش ها، هدر ها، طرح های بدن، وضعیت ها، معانی خطا و محدودیت ها. هدف این است که برای گرفتن تغییرات ناسازگار قبل از ادغام و انتشار نسخه با خیال راحت، بدون E2E سنگین.

2) روش ها

قراردادهای مصرف کننده محور (CDC): مشتری انتظارات را شکل می دهد (پیمان و آنالوگ) ؛ ارائه دهنده به طور مرتب آنها را بررسی می کند.
مشخصات: قرارداد به عنوان یک منبع واحد حقیقت (OpenAPI/Protobuf/GraphQL SDL) ؛ تست ها پیاده سازی در برابر مشخصات را تأیید می کنند.
مبتنی بر رویداد: طرح های پیام (Avro/JSON Schema/Protobuf) + قوانین سازگاری کارگزار/رجیستری.

3) جریان مشخصات HTTP/REST

1. قرارداد: OpenAPI 3. x (نمودارها، مثالها، کدها).
2. تجزیه و تحلیل خطوط و آمار: سبک، زمینه های مورد نیاز، کدهای یکنواخت.
3. اعتبار سنجی پیاده سازی: ژنراتور تست anti-OpenAPI (رویکرد schemathesis/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-deploy را محاسبه می کند.

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 'with package/service versioning» است.

سازگاری: برچسب ها را دوباره استفاده نکنید، فقط موارد جدید را با اختیاری اضافه کنید، فیلدهای مورد استفاده را حذف نکنید. شماره های رزرو

تست ها: تولید سرور/مشتری، اجاره مورد خودکار + منفی (زمینه های ناشناخته، محدودیت اندازه).

6) قراردادهای رویداد (کافکا/NATS/...)

Схемы: Avro/JSON Schema/Protobuf в رجیستری طرح.
سیاست سازگاری «BACKWARD» (اغلب به اندازه کافی) یا «FULL» است.
تست های تولید کننده: پیام را در برابر طرح تأیید می کند ؛ تست های مصرف کننده: نسخه های قدیمی و جدید را می پذیرد.
ثابت: کلید idempotence، نظم/تکرارپذیری، معانی deduplication.

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، فیلدهای اجباری «کد»، «پیام»، «ردیابی _ شناسه».
اندازه ها/محدودیت ها بخشی از قرارداد هستند (413/414/431).
Idempotency: رفتار تکرار (409 در مقابل 201 همان id).

عنوان ها: «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. Lint/validate: OpenAPI/Proto/Avro ('validate', style- линер).
2. انتشار: قرارداد به عنوان مصنوع (کارگزار/رجیستری).
3. تأیید: ارائه دهنده آزمایش های بسته/مشخصات CDC را اجرا می کند.
4. دروازه can-i-deploy: بدون ماتریس سبز مجاز نیست.
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) ابزار (توسط کلاس کار)

Lint/validators: openapi-linters، protobuf-lint، avro-tools.
CDC: خانواده/کارگزار پیمان، قرارداد Spring Cloud، Hoverfly (پرونده های HTTP/تکرار).
دونده مشخصات: schemathesis/روش Dredd مانند، آزمون پستچی + طرح JSON.
تفاوت: معنایی-تفاوت OpenAPI/Proto/آورو (تشخیص تغییرات شکستن).
ظروف: Testcontainers به بالا بردن ارائه دهنده/میز قرارداد.

12) ضد گلوله

«اسکله ویژه» به طور جداگانه از کد → desynchronization. قرارداد را نزدیک محل کار نگه دارید.
Moki از یک سرویس شخص ثالث به جای یک قرارداد → شکنندگی در طول به روز رسانی.
پاسخ های تصادفی/تولید بدون اتصال به طرح → پوسته پوسته شدن.
تغییر انواع/زمینه های اجباری بدون نسخه.
پسوندهای خاموش بدون اطلاع رسانی/کاهش.
بدون قرارداد منفی و کد خطا.

13) ویژگی های iGaming/امور مالی

زمینه های پول را رسمی کنید: «مقدار» - اعشار با مقیاس، ارز - ISO-4217، مقادیر متغیر.
قراردادهای پرداخت/webhook: HMAC/mTLS، ضد پخش (پنجره «X-Timestamp»)، idempotency، «Retry-After».
منطقه/مستاجران: سرصفحه های اجباری «X-Tenant/X-Region»، محلی سازی پیام ها.
رویدادها: سیاهههای مربوط به بدون تغییر (ممیزی)، کلید های deduplication، تضمین تحویل (حداقل یک بار + دستگیره های idemotent).

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 تأیید ارائه دهنده CDC (شبه)

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

15) تولید لیست آمادگی

• قراردادها در مخزن، CI مصنوعات را تأیید و منتشر می کند.
• CDC برای ادغام بحرانی فعال است ؛ broker/matrix «can-i-deploy» کار می کند.
• سیاست سازگاری (HTTP/gRPC/رویدادها) مستند شده است ؛ خودکار معناشناسی-تفاوت.
• قراردادهای منفی: خطاها، محدودیت اندازه، idempointence، 'Retry-After'.
• داده های آزمون قطعی است ؛ عکس های فوری از مثال ها پشتیبانی می شود.
• نسخه و استهلاک: مهلت، اطلاعیه ها، هدر.
• برای رویدادها - رجیستری طرح و حالت سازگاری ؛ تولید کننده/مصرف کننده هر دو نسخه را آزمایش می کند.
• مصنوعات: JUnit/HTML، گزارش های diff/verify، ماتریس سازگاری.
• روش حادثه: سریع rollback قرارداد/پرچم ویژگی، اطلاع رسانی به انتگرال.

16) TL ؛ دکتر متخصص

انتظارات را در قراردادها ثبت کنید و آنها را به صورت خودکار اجرا کنید: CDC برای انتظارات مشتری، تست مشخصات برای مطابقت با پیاده سازی، ثبت طرح برای رویدادها. سیاست های سازگاری دقیق و قراردادهای منفی (خطاها، محدودیت ها، idempotence) را حفظ کنید. شما نمیتوانید بدون ماتریس سبز can-i-deploy و semantic-diff بدون شکستن تغییرات آزاد کنید.