בדיקת חוזה API

1) מדוע בדיקת חוזה

החוזה תופס את ציפיות הלקוחות ומבטיח: מסלולים/שיטות, כותרות, סכימות גוף, סטטוסים, סמנטיקה שגיאות ואילוצים. המטרה היא לתפוס שינויים בלתי מתאימים לפני האינטגרציה ושחרור גרסאות בצורה בטוחה, ללא E2E כבדות.

2) גישות

CDC: הלקוח יוצר ציפיות (Pact and analogues); המפרנס מאמת אותם באופן קבוע.
מפרט: חוזה כמקור אמת יחיד (OpenAPI/Protobuf/GraphQL SDL); מבחנים מאשרים מימוש בניגוד למפרט.
מבוסס אירוע: Schemas (Avro/JSON Schema/Protobuf) + broker/registry adventibility rules.

3) מפרט HTTP/REST

1. חוזה: OpenAPI 3. x (דיאגרמות, דוגמאות, קודים).
2. ניתוח מוך וסטאט: סגנון, שדות דרושים, קודים אחידים.
3. אימות יישום: מחולל בדיקות אנטי-OpenAPI (schemathesis/Dredd action) + נגטיבים ידניים.
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. הברוקר מחשב את מטריצת התאימות.

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

החוזה הוא '. פרוטו' עם חבילת/שירות וסיפוח.
תאימות: אל תשתמש שוב בתגים, רק תוסיף חדשים עם אפשרות, אל תמחק שדות בשימוש; מספרי מילואים.
בדיקות: דור דקירת שרת/לקוח, מקרה אוטומטי מושכר + שלילי (שדות לא ידועים, גבולות גודל).

6) חוזי אירועים (קפקא/NATS/...)

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) תאימות וגרסאות

התאמה לאחור (מינימום מומלץ): הוסף שדות אופציונליים, אל תשבור את הקיימים.
צרכנים מתעלמים משדות לא ידועים.
מלא: שניהם.
Versioning: "path (/v1)", "קבל: application/vnd. מותג. v2 + json ',' פרוטו חבילת v2 '.
מדיניות סטייה: חלון פלט (לדוגמה, 90 יום), כותרות אזהרה/אירועים.

8) שליליות וטעויות הן גם חוזה

קודי תקן: 400/401/403/404/409/422/429/5xx, שדות חובה "קוד", "הודעה", "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) נתונים המנוהלים על ידי חוזה

דוגמאות - חיים, מאומתים במודיעה.
אבזרים למרכז לבקרת מחלות הם מינימליים, דטרמיניסטיים.
דור נתונים - מבוסס רכוש עבור מספרים/תאריכים; אבל לא לשבור את היציבות של תמונות.

10) צינור ב ־ CI/CD (התייחסות)

1. מוך/תוקף: OpenAPI/Proto/Avro (”תוקף”, סגנון).
2. Publish: חוזה כחפץ (תיווך/רישום).
3. לאמת: הספק מריץ מנות/מפרט CDC.
4. לא ניתן לשחרר ללא מטריצה ירוקה.
5. Diff-מאמת שהשינויים הם diff סמנטי.
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-linters, פרוטובוף-מוך, avro-כלים.
CDC: Pact family/broker, Spring Cloud Contract, Hoverfly (רשומות HTTP/הילוכים חוזרים).
רצי מפרט: תרשים/גישה דמוית דרד, מבחן דוור + סכימת JSON.
Diff: Semantic-diff OpenAPI/Proto/Avro (מזהה שינויים שבירה).
מכולות: Testcontainers כדי להעלות את שולחן הספק/חוזה.

12) תרופות אנטי ־ פטריות

”מזח מיוחד” בנפרד מהקוד * desynchronization. שמור על החוזה ליד השירות.
מוקי של שירות צד שלישי במקום חוזה = שבריריות במהלך עדכונים.
תגובות אקראיות/דור מבלי להתחייב לתכנית הפתיתים.
שינוי סוגים/שדות חובה ללא גירסה.
הרחבות שקטות ללא הודעה/הטבעה.
אין חוזים שליליים וקודי שגיאה.

13) פרטים של iGaming/Finance

נוסח שדות כסף: ”כמות” - עשרוני עם קנה מידה, מטבע - ISO-4217, אינווריאנטים של סכומים.
חוזי תשלום/webhook: HMAC/mTLS, anti-retry (חלון X-Timestamp), idempotency, ”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 CDC ספק אימות (פסאודו)

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

15) רשימת מוכנות למומחים

[ חוזים ] במאגר, מודיע תוקף ומפרסם חפצים.

[ ] לבקרת מחלות אפשרה אינטגרציה קריטית; עבודות ברוקר/מטריקס ”יכול-i-פריסה”.

[ מדיניות התאימות ] (HTTP/gRPC/Events) מתועדת; חיוג אוטומטי סמנטי.

[ ] חוזים שליליים: שגיאות, גבולות גודל, אידמפוטנטיות, ”Retry-After”.

[ נתוני מבחן ] דטרמיניסטיים; תמונות של דוגמאות נתמכות.

[ ] ורסיונינג ופחת: מועדים, הודעות, כותרות.

[ ] לאירועים - רישום סכמות ומצב תאימות; היצרן/צרכן בוחן את שתי הגרסאות.

[ ] חפצים: JUnit/HTML, diff/לוודא דיווחים, תאימות מטריצה.

[ ] נוהל אירוע: rollback חוזה מהיר/דגל תכונה, הודעה לאינטגרטורים.

16) TL; DR

תפוס ציפיות בחוזים והפעל אותן באופן אוטומטי: CDC עבור ציפיות הלקוחות, בדיקות מפרט כדי להתאים את היישום, סכימת אירועים. שמור על מדיניות תאימות קפדנית וחוזים שליליים (שגיאות, גבולות, אידמפוטנטיות). אתה לא יכול לשחרר ללא מטריצה ירוקה-i-לפרוס ו סמנטי-diff בלי לשבור שינויים.