התאמת חוזה API
מדוע תאימות חוזה
תאימות חוזה היא היכולת של API להתפתח מבלי לשבור אינטגרציות קיימות. במערכות גדלות, API משתנה לעיתים קרובות יותר מאשר קוד לקוח; תאימות מאפשרת לך לשחרר תכונות באופן איטרטיבי, מבלי לארגן ”מהלכים גדולים”.
הרעיון המרכזי: החוזה הוא ראשוני, השינויים מתבצעים בהתאם לכללי התאימות ונבחנים באופן אוטומטי.
מושגים בסיסיים
מפרט ממשק פורמלי: משאבים/שיטות/אירועים, סכימות נתונים, קודי שגיאה, גבולות, SLAs, דרישות אבטחה.
ספק - הבעלים של API. צרכן - לקוח/אינטגרציה.
- הספק החדש עובד עם צרכנים ותיקים.
- קדימה: הספק הישן עובד עם צרכנים חדשים (בדרך כלל על ידי ”קוראים סובלניים”).
- מלא: הן אחורה והן קדימה (האפשרות החזקה ביותר) נצפות.
- תוספות - להוסיף אלמנטים אופציונליים בלי לשבור קיימים.
מדיניות Versioning
ורסיונינג סמנטי (מומלץ):- שינויים שבירת מייג 'ור (רק כאשר שורת API חדשה משתחררת: '/v2', 'שירות'. v2 '.
- שינויים מינוריים ־ תוספים (שדות אופציונליים/שיטות חדשות).
- תיקון ללא שינוי בחוזה.
- מדיניות דחייה: הכרזה על אלמנטים מיושנים, חלון תמיכה (שקיעה), אזהרות בכותרות/מטא-נתונים, תוכנית נסיגה.
בטוח נגד שינויים מסוכנים
מאובטח (בדרך כלל אחורה-תואם)
הוסף שדה אופציונלי ל JSON/Protobuf/Avro.
הוסף נקודת סוף חדשה/שיטה/אירוע.
הרחבת אנום עם ערכים חדשים אם הצרכנים סובלניים כלפי ערכים לא ידועים.
העלאת גבולות (לדוגמה, ”MaxPrits”) מבלי להדק את המינימום.
מוסיף נול עם ברירות מחדל נכונות.
ערוך תיאור/דוגמה לטקסט.
מסוכן (שובר תאימות)
שינוי שם/מחיקת שדות, שינוי סוג או חובה.
סטטוס קוד/שגיאה סמנטית משתנה (לדוגמה, היה '200', הפך '204 &pospos או' 404 ').
שינוי הפורמט של מזהים (UUID # int).
הידוק אימות (מינימומים/תבניות מחמירים יותר) ללא גירסה.
שינוי הסדר והמבנה בזרמים/אירועים gRPC.
השתמש מחדש במספרי תג בפרוטובוף עבור שדות חדשים.
אינטראקציה על ידי סגנון אינטראקציה
REST/HTTP + JSON Schema
תוספות: אנחנו מסמנים שדות חדשים כ ”אופציונליים ”/” בלתי ניתנים להשגה”.
קורא סובלני אצל הלקוח: התעלם משדות לא ידועים; לא להסתמך על סדר.
Versioning: major - בדרך ('/v2 ') או בסוג המדיה (' application/vnd. דוגמא. v2 + json '.
עבור עדכונים בטוחים ללא מירוצים.
שגיאות: פורמט יחיד ("סוג", "קוד", "שם", "פרט", "trace _ id'), לא משנים את הערך של" קוד "ללא מייג 'ור.
עבודת אלילים: המלצרים עדיפים על קיזוז; הוסף שדות ”הבא _ הסמן”, אל תשנה את המשמעות של אלה הקיימים.
gRPC/Protobuf
מספר התגים לא השתנה. אין אפשרות להשתמש מחדש בתוויות שנמחקו.
השדות החדשים הם 'אופציונליים '/' חוזרים' עם ברירות מחדל סבירות בשרת.
אל תשנה את הסדר והודעות החובה בזרימה-RPC.
סטטוסים של שגיאה הם יציבים (”INVALID _ ARGATION”, ”Afflied _ PRECONDITION” וכו '); סמנטיקה חדשה היא גרסה חדשה של השיטה/שירות.
מונע אירועים (קפקא/NATS/PULSAR) + Avro/JSON Schema
שמות אירועים: 'תחום. פעולה. וי מייג 'ור.
שדות חדשים הם אופציונליים; לבודד ליבה והעשרה (”enriched”).
סכימה נרשמת: כללי תאימות (BACWARD/FORWARD/FULL) בנושא/אירוע.
סיומת האנום תקפה לקורא סובלני בצד הצרכן.
החלוקה/סדר שינוי מפתח עבור צבירה = שבירת שינויים.
GraphQL
הוספת שדות/סוגים היא בטוחה; למחוק/לשנות שם - רק דרך @ disrated וחלון הנדידה.
אל תשנה סוגים/לא ניתנים לבחירה ללא מייג 'ור.
בקרת מורכבות/גבולות עומק הם חלק מהחוזה.
תבניות אבולוציה בת קיימא
התוסף-ראשון: להתרחב בלי לשבור.
משא ומתן יכולות: לקוחות מדווחים כי הם תומכים (כותרות/פרמטרים/הסכמים), השרת מתאם.
גבולות חוזה: תיקון MGC (חוזה אחריות מינימלית) והרחבות נפרדות (מודל פירמידה הפוך).
סובלנות כברירת מחדל: לקוחות מתעלמים מערכים לא נחוצים ומטפלים נכון בערכים לא ידועים (fallback).
דו ־ כתיבה/פולט כפול: עבור שינויים גדולים, שחררו את v1 ו ־ v2 במקביל לזמן מה.
כותרות שקיעה/אירועים: הודע מראש בעת הסרת הגרסאות.
ממשל ואוטומציה
צינורות API:- OpenAPI/Spectral: שמות, פגינציה, קודי שגיאה, תבניות שדה.
- Buf/Protobuf: ביטול שימוש חוזר בתגים, סימון חבילות.
- AsyncAPI/Schema Registry: סכימה ברמה CI.
- קטלוג חוזה (SSOT): סכימה מרכזית/גירסה רשומה עם היסטוריה מפוזרת.
- גילדה/ועדה שמאמצת כללים, תבניות ושינויי ביקורת.
- ניהול שינוי: RFC/ADR, הערות שחרור, מדריכי נדידה.
בדיקת תאימות
Schema-diff in CI: בלוק שובר עוגות (OpenAPI-diff, Buf breaking, SR computability).
חוזים מונעים על ידי צרכנים (CDC): Pact/דומה - ספק נגד חוזים ספציפיים לצרכן.
דוגמאות זהב: שאילתות התייחסות/תגובות ואירועים לנסיגה.
E2E קנרית: מתגלגלת לנתח של קבוצות צרכני תנועה/יחידים.
כאוס/איחור: Timeout/Retray לבדוק - שינוי Latency-SLO נחשב שינוי חוזה.
נדידה ופחת
1. הכרז על הפחת: סמן את הפריט, ציין את מונח השקיעה וחלופי.
2. לשמור על תקופת תאימות: דו-כתיבה/פולט כפול, גשרים, מתאמים.
3. לאסוף טלמטריה: מי עוד משתמש הישן?
4. תקשורת: דואר, הערות שחרור, דוכני מבחן.
5. הסרה: לאחר שפג תוקפו של החלון - הסרה עם שחרור קבוע.
דוגמאות לשינויים
מנוחה
זה היה:json
{ "id":"p1", "status":"authorized" }json
{ "id":"p1", "status":"authorized", "risk_score": 0. 12 }לקוחות שמתעלמים משדות לא ידועים לא נשברים.
Protobuf
proto message Payment {
string id = 1;
string status = 2; // don't change tag numbers optional double risk_score = 3; // additive
}אירוע
"פאיימנט. מורשה. v1 '(ליבה) +' תשלום. מועשר. v1 '(העשרה). צרכני נתיב קריטי קוראים את הליבה ואינם תלויים בהעשרה.
Antipatterns
סוואגר-לשטוף: יש באופן רשמי מפרט, אבל ההתנהגות של השירות הוא מסוכסך עם זה.
שבירה על ידי התגנבות: שינוי סוג/מצב/פורמט ללא גרסה חדשה וחלון נדידה.
אירועי CDC גולמי כחוזה ציבורי: דלף מזימות DB, בלתי אפשרי של אבולוציה.
לקוח קשיח: טיפות בשדות/ערכים לא ידועים; היעדר קורא סובלני.
שימוש מחדש בתגיות פרוטובוף: שחיתות נתונים שקטה.
Latency כ ”לא חוזה”: p95 התארך באופן בלתי צפוי - צרכנים מתפרקים בזמן.
רשימת תאימות (לפני המיזוג)
[ ] שינויים הם תוסף (או גרסה עיקרית).[ ] המחאות לינטרס/דיף עברו, כללי התאימות ירוקים.[ שגיאות/קודים/סטטוסים ] לא שינו את הסמנטיקה.[ ] אנום הורחב מבלי לאסור ערכים ישנים; לקוחות - סובלניים.[ ] הגבולות של MGC הם ללא שינוי.[ ] דגימות מעודכנות/תיעוד/SDK.[ ] למייג 'ור - כתיבה כפולה/תוכנית פלטה כפולה, שקיעה-תאריך, תקשורת-תכנית.[ ] בדיקות CDC/Golden/E2E עברו.FAQ
במה שונה התאימות לאחור מתאימות קדימה?
שרתים חדשים אינם שוברים לקוחות ישנים. לקוחות חדשים אינם פורצים אל השרתים הישנים (באמצעות קורא סובלני ומחדל מסודר).
מתי אתה עושה '/v2 '?
כאשר אינווריאנטים/סמנטיקה משתנים, שדות/שיטות נמחקים, נדרש מודל אבטחה חדש - קל יותר וישר יותר להתחיל קו חדש.
אתה יכול לחיות בלי סכימה רישום/לינטרס?
תיאורטית - כן, למעשה - אלה נסיגות תכופות והתמוטטויות ”נסתרות”. האוטומציה משתלמת.
ניתן להרחיב את אנום?
כן, אם הלקוחות מטפלים נכון בערכים לא ידועים (גיבוי/התעלמות). אחרת - גדול.
סך הכל
התאמת חוזה היא כללים + דיסציפלינה + אוטומציה. עיצוב תוסף, שינויים בשבירת גרסאות, הפעלת קורא סובלני, אוטומטית בדיקת דיפולס ו-CDC, תוכנית פחת. בדרך זו API יכול להתפתח במהירות ואינטגרציה יכולה להישאר יציבה.