התאמת API ותאימות חוזה

TL; DR

תאימות היא משמעת, לא מזל. לשמור על מדיניות גירסה ברורה (SemVer), לשנות מתמטיקה (מה ”שובר”, מה שלא), מבחני חוזה, סכימות, ונהלי שקיעה. עבור כסף ותאימות - REST/gRPC קפדנית עם vN, עבור אגרגציות UI - GraphQL אבולוציונית עם '@ disured'. תמיד: תנועה כנרית, תאימות לאחור, מחזור שחרור אחד, מדריכי נדידה, טלמטריה בשטח.

1) מושגים ומטרות בסיסיים

התאמה לאחור (BC): לקוחות ישנים מתאימים לשרת החדש.
FFC: לקוחות חדשים מתאימים לשרת הישן (מוגבל).
תאימות חוט: הפורמט על התייל אינו נשבר (חשוב במיוחד עבור gRPC/Protobuf).
סימוור: "מייג 'ור. מינורי. Patch '- לשבור את החוזה = להעלות מייג' ור.

המטרה היא למזער שינויים מפריעים ולספק חלונות נדידה צפויים.

2) שינוי מטריקס: מה שאתה יכול ולא יכול

3) מדיניות לסגנונות API שונים

3. 1 מנוחה

גרסה ב ־ URI ("/v1/... ) או תחום ('api-v1. '). גרסת כותרת למקרים פנימיים בלבד.
הוסף, אל תמחק: שדות חדשים - אוקי, סימן ישן כ ”מנותק” בתרשים ועזוב לפחות למחזור אחד.
סטטוסים/שגיאות: אל תשנו את הקודים והמבנה. קוד/שגיאה. הודעה/טעות. פרטים ".
אידמפוטנטיות אינה משתנה: אל תהפוך ”פוסט” מאובטח עם ”מפתח אידמפוטנטי” לאתגר ”שונה מבחינה התנהגותית”.

3. 2 GRPC/Protobuf

מספרי שדה הם קדושים: אל תשתמש שוב במספרים שנמחקו, סמן כ ”שמורים”.
רק הוספת שדות אופציונליים/רפיט חדשים; "חובה קשה" - באמצעות אימות, לא מחדש ".
חבילות גרסה: 'תשלומים. v1 ',' תשלומים. v2 '.
תאימות שירות: RPCs חדשים * שיטה חדשה; אנחנו לא משנים את ההתנהגות של הישן.

proto message Payout {
reserved 4 ;//field deleted, number reserved string id = 1;
string currency = 2;
int64 amount_minor = 3;
// v2: optional string comment = 5;
}

3. 3 GraphQL

אבולוציה ללא v2: הוספת שדות/סוגים; מחיקה - דרך '@ decreted (סיבה) "עם ההכרזה של החלון.
שאילתות מתמידות: ללקוחות ציבוריים, להשתמש בלבן של שאילתות - קל יותר לשלוט בתאימות.
שטח ברמת AuthZ וטלמטריה: יודעים אילו שדות משמשים למעשה לפני מחיקה.

graphql type Payout {
id: ID!
amountMinor: Long!
currency: String!
comment: String @deprecated(reason: "Use note")
note: String
}

3. 4 חוברות אינטרנט

גרסה במסלול ('/webhooks/v1/piples ') ומעטפת אירוע קבועה (' event _ id', 'type', 'ts',' data ').
שמור חתימות/NMAS ללא שינוי; אלגוריתמים חדשים כאפשרות עם דגל.
הרחבות - רק דרך הנתונים של השדות החדשים. ובלי למחוק את הישנים.

4) שער API וניתוב גרסה

ניתוב מבוסס חוקים: על ידי קידומת '/v1 ', על ידי כותרת' X-Api-Version ', על ידי תחום.
Shadow/Canary: לשקף חלק מתנועת הייצור בגרסה החדשה ”אל הצללים”, להשוות את התשובות.
Rate/Quotas לכל גרסה: מגן על לקוחות מבוגרים במהלך הגירה.

• שקיעה: - תאריך כיבוי גרסה
• הפחתה: נכון - הגרסה הופכת למיושנת
• קישור: rel = ”ירידה” - על changelog/nigering המדריך

nginx location ~ ^/v2/ {
proxy_pass http://api_v2;
}
location ~ ^/v1/ {
add_header Deprecation "true";
add_header Sunset "Thu, 01 May 2026 00:00:00 GMT";
proxy_pass http://api_v1;
}

5) רישומי מזימות וחוזים

סכימת OpenAPI/JSON (ראשי תיבות של OpenAPI/JSON Schem תיאורי פרוטובוף (Protobuf): רישום SDL ל ־ GraphQL.
בדיקת CI: לינטרים + ”בדיקת שבירת שינויים” ביחסי ציבור.
חוזים המונעים על ידי צרכנים (CDC): בדיקות צרכניות (Pact/analog) - הגנה מפני הפסקות לא בולטות.
Changelog: ניתן לקריאה במכונה (לדוגמה, Changelog. md' + לשחרר הערות ברישום).

6) התפתחות שדות: כללי אגודל

אל תשנה את הפורמט (UUID↔int) ללא שדה חדש '_ v2' ותקופת מעבר.
זמן/מטבע: שמור על ISO-8601/epoch UTC ומטבע amount_minor +; אין קנה מידה (אגורות/סנט).
Enum: הוסף ערכים - בסדר; אל תשנה את המשמעות של הישנים. עבור REST, תן ערכים מחרוזת, לא קלט.
Pagination: מבוסס סמן יציב יותר; אל תשנה את הסמנטיקה של הסמן.

7) הידלדלות ונוהל ”שקיעה”

1. הודעה (T-90/60): changelog, דואר לשותפים, 'Desprection/Sunset' כותרות.
2. זמן שכפול: V1 ו-V2 פועלים במקביל; V1 מצויד באזהרות בתגובות/יומנים.
3. טלמטריה שימוש: מי עוד קורא V1? אנשי קשר נקודתיים.
4. מקפיא V1: רק תיקוני באגים/אין תכונה.
5. Sunset-410 נעלם או עמוד בלוק הוראות נדידה.

8) שחרור ללא כאב: הנחת אסטרטגיות

ניתוב כחול/ירוק או משוקלל: 1-5-25-50-100% תנועה.
חלון תאימות: לפחות 1-2 שחרור מינורי, לעתים קרובות יותר 6-12 חודשים עבור API חיצוני.
מאפיין דגלים לכלול שדות לוגיקה/סניפים חדשים ללא שדרוג.
קריאה/כתיבה-פיצול: קודם הוסף תמיכה לקריאת שדה חדש, ואז תתחיל לכתוב אותו.

9) בדיקת יכולת בין-אופרטיבית (סוויטת אימון)

מבחני זהב לתגובות מגרסאות ישנות יותר.
בדיקות מעגלים: אין פריצה במודיעה.
ההפקה החוזרת פועלת על היערכות עבור V2 (צל).
תסריטי גב/קדימה: לקוח חדש בשרת הישן ולהפך (שבו FC תקף).
בדיקות חוזה של פתקי אינטרנט: אימות של חתימה, תבנית, זמן.

10) מדדים ו ־ SLOs של תהליך הווסינינג

% מהלקוחות ב-MINOR האחרון (80% לפני שקיעה).
שגיאות תאימות/לא זמינות לכל שחרור (מטרה 0).
שיתוף קריאות מורשת (ירידה לשקיעה).
זמן נדידת הלקוח (median/p95).
דלתא Latency/regression delta בין גרסאות (לא יותר גרוע מבסיסי).

11) דוגמאות של חפצים

yaml components:
schemas:
Payout:
type: object properties:
id: { type: string, format: uuid }
amount_minor: { type: integer }
currency: { type: string }
comment:
type: string deprecated: true description: "Use note"
note: { type: string }

proto syntax = "proto3";
package payouts. v1;
message Payout { reserved 5; string id=1; int64 amount_minor=2; string currency=3; }

graphql type Query { payout(id: ID!): Payout }

12) ורסינציה של ערוצים סמוכים

SDK/CLI: תלות בגרסת SEMVER + API, תאימות שנקבעה ב ־ README.
אירועים/זרמים (WS/Kafka): גרסה באנבלופה. גרסה "; תכונות חדשות - אופציונליות; דדופ וקורות חיים עובדים אותו הדבר בין הגרסאות.
דיווח/CSV: גרסה בשם קובץ/כותרת; הוספת עמודות ימינה לא משנה את הסדר/סוגים.

13) ממשל ותפקידים

בעל חוזה (בעל דומיין), Steward API (חוקים וקווים), מנהל שחרור (Sunset/Communications).
תהליך שבירת שינויים: הצדקה עסקית, תוכנית הגירה, חפצים, תאריכים.
ספריית API מאוחדת: שם ניתן לראות דיאגרמות, גרסאות, לוח שנה של שקיעה, מגע.

14) אנטי דפוסים

הפסקות ”שקט”: לשנות את מצב/שגיאה/סוג שדה ללא גרסה.
שימוש חוזר במספרי פרוטובוף הורס שידור חוזר ולקוחות ישנים.
GraphQL ללא טלמטריה שדה - הסרת מגע.
Global v2 בסך הכל - megamigration במקום אבולוציה נקודתית.
הגרסה בפרמטר השאילתות של API הציבורי היא תוכנית לא ברורה ופגיעה.
אין מדריכי נדידה ודוגמאות - שותפים דוכן, מועדים משובשים.

15) בדיקת-רשימה של הגרסה החדשה

[ סכימת ] מעודכנת (OpenAPI/Protobuf/SDL), תיקונים ובדיקות שבירה עברו.

[ ] אינטגרציה ובדיקות חוזה (CDC).

[ ] SDK/דגימת קוד/מדריך הגירה ו Changelog מוכן.

[ ] Deprecation/Sunset מאופשר (גרסה ישנה) + כיצד להגר דף.

[ ] קנרית/צל תוכנית, התראות ולוחות מחוונים להשוואת מדדים.

[ ] התאימות לאחור נשמרת לתקופה מוסכמת.

[ ] תוכנית Rollback ומטריצת סיכון הסכימו.

תקציר

API יציב הוא תהליך, לא "אחת ולתמיד. "לחיות לפי הכללים: SemVer + avolution + complose evolution + circuit protection + Sunset process. סגנונות נפרדים (REST/gRPC/GraphQL) ומדיניותם, גרסאות מסלול ל-API של השער, גלגול קנריות, מדידת האפקט. כך תימנעו מ ”שבירת הפתעות”, להאיץ את שילוב השותפים ולשמור על יכולת חיזוי לתחומים כספיים וקריטיים.