תאימות API ועדכונים
1) יסודות תאימות
expositive-first: הוסף חדש ללא שבירה ישנה (שדות אופציונליים חדשים/נקודות קצה, ערכי enum חדשים).
חוזים יציבים: ”מה שמובטח במפרט עובד;” התנהגות מתועדת.
אחורנית> קדימה: עדיפות תאימות לאחור; קדימה מותרת דרך קוראים סובלניים.
המסמכים הם עיקריים: מקור האמת היחיד הוא גרסת הרישום של התוכנית (OpenAPI/ASyncAPI/Proto).
אבולוציה מפורשת: לפרוץ - רק דרך גרסה מרכזית חדשה ומדריך נדידה.
2) טקסונומיה של שינויים
2. 1 תואם (MINOR/PATCH)
הוסף שדות/כותרות אופציונליים, נקודות קצה חדשות, פרמטרים שאילתה עם ברירות מחדל.
הגדלת הגבולות (”page _ size”, TTL), הבהרת שגיאות ללא שינוי בקודים/סמנטיקה.
הוסף את ערכי האנום אם הלקוחות מתעלמים מן ה ”לא ידוע” (קורא סובלני).
2. 2 דו משמעי (התנהגות)
שינוי ברירות מחדל, סדר מיון, פסקי זמן דקים, מכסות - יכול ”לשבור” היגיון עסקי. דורש הכרזת RFC + וקנריות.
2. 3 שבירה (מייג 'ור)
שינוי שם/מחיקת שדות, שינוי סוג/פורמט, החלפת קודי שגיאה, אי-התאמה הפוכה של תוכניות חוזים/אימות.
3) מדיניות Versioning
אסטרטגיה: ”path versioning” ('/v1 ', '/v2').
קטן/תיקון: ”להוסיף, לא לשבור”.
כותרות מיושנות (אופציונלי): ”X-API-Version-Date” לשינויים קלים.
סוגי מדיה (Op.): "קבל: יישום/vnd. Acme. v1 + json 'עבור גרנולציה עדינה.
4) הפחתה ושקיעה
4. כותרות תקשורת 1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </guides/reports-v2>; rel="successor-version"4. 2 פקודת משיכה
1. הכרזה בפורטל/רשימת הדואר/הערות שחרור SDK.
2. חלון האזהרה הוא 90-180 ימים.
3. סטטוסים בלוח המחוונים של האימוץ.
4. אחרי השקיעה - 410 נעלם או ”לקרוא בלבד” מצב לתקופת חסד, אם הוסכם.
5) נדידה ודו ־ קיום של גרסאות
כתיבה כפולה/קריאה כפולה במעבר ופיוס עם דוחות.
מתאם (זמני): המרות שער של pagralox הישן * תוכניות חדשות; תקופת החיים של המתאם מוגבלת.
עזרה SDK: שחרור התומך בשתי הגרסאות, עם אזהרות צמצום (1 זמן לכל תהליך).
דגלים: הכללה של סמנטיקה חדשה לפי רשימת המפתחות/דיירים.
6) תאימות לאחור וקדימה
6. 1 אחורה (לקוחות ישנים ↔ שרת חדש)
אל תשנה את סוג הפורמטים/חובה.
שדות חדשים הם רק אופציונליים.
שגיאות - old 'reror _ code', הוסף קודים חדשים, אל תחליף.
6. 2 קדימה (לקוחות חדשים ↔ שרת ישן)
בדוק את היכולות באמצעות 'אפשרויות '/' גרסאות'.
על הלקוח להיות סובלני לגבי תכונות חסרות.
7) חוזים ובדיקות אוטומטיות
רישום: סכימת חנויות; יחסי ציבור חופרים * דוחות שבירה/אי שבירה.
לינטר: שמות/סוגים, אידמפוטנטיות, עבודת אלילים, קודים יציבים.
CDC (Consumer-Drived Contracts): בדיקות אינטגרטור ב-CI של הספק (Pact and analogs).
שער: יחסי ציבור חסומים בעת שבירה ללא בליטה/RFC.
yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml8) הארכה כנרית והפוך
קנרית: 10% * 25% * 50% * 100% מהתנועה; גלגול אוטומטי של דלדול SLO (5xx/latency/429).
מפתחות בטא: גישה לגרסאות חדשות על ידי רשימת allowlist.
הקפאת שחרור: תקצוב שגיאה במהלך בעירה.
ניתוח קבלה: שיתוף של תנועה/לקוחות על הגרסה החדשה, זמן נדידה.
9) תאימות לפרטים: שגיאות, הפגנות, אידמפוטנטיות
9. 1 שגיאות
אל תשנה סטטוסים של HTTP בתסריטים קיימים.
'error _ code' - יציב; קודים חדשים רק מוסיפים.
אפליקציה/בעיה + json 'הוא פורמט יחיד.
9. 2 pagination
עבור לסמן/keyset = מינור אם ה ־ offset/limit הישן נתמך.
תיעוד הסוג '(updated_at,id) ויציבות הסמן.
9. 3 אידמפוטנטיות
לכתיבה - 'Idempotency-Key' + '409 IDEMP_REPLAY' במקרה של קונפליקט.
הגירה לא צריכה לשנות את הסמנטיקה של אידמפוטנטיות.
10) טרנספורמציית שער (כאשר מתאים)
מיפוי שדות v1 + v2, נרמול שגיאות, המרת תבניות תאריך/כסף.
מעקות בטיחות: שינויים הם שקופים וניתנים להשגה; לא להסתיר שבירה, אבל להשתמש כגשר מוגבל בזמן.
11) תקשורת ופורטל
Changelog exploset (”הוסף/שונה/נדחה/הוסר/קבוע”).
כרטיס גרסה: מצב (beta/GA/decreted), תאריך שקיעה, קישורים למדריכים.
פתקי אינטרנט של הודעה: שימו לב, גרסה. שוחרר, 'תכנית. שינוי ".
SDK משחרר הערות + פורטל באנר.
12) מדדי הצלחה
שיעור אימוץ v2 (לכל בקשה/לקוח).
תקריות הפוכות.
מיקס שגיאות (4xx/5xx/429 מניות) לפני השחרור.
זמן לאמץ חציוני.
טעינת תמיכה (כרטיסים/שבוע).
עלות לשרת.
13) תבניות ודוגמאות
13. 1 כותרות גירסה וירידות
X-API-Version: v1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </v2/reports>; rel="successor-version"13. מדיניות גרסה 2 (מקטע YAML)
yaml versioning:
strategy: "path"
compatibility:
minor: "additive-only"
patch: "bugfix/perf, no schema change"
deprecation:
min_notice_days: 120 rollout:
canary_steps: [10,25,50,100]
rollback_checks: ["5xx_rate","p95_latency","429_rate","adoption"]13. 3 אפי שדה OpenAPI תואם
yaml components:
schemas:
Report:
type: object required: [id, createdAt]
properties:
id: { type: string }
createdAt: { type: string, format: date-time }
cursor: { type: string, description: "optional for v1. 2+" } # additive14) שחרור רשימה (מינור/מייג 'ור)
מינור
[ ] DIFF:[ תיעוד ]/SDK מעודכן (דוגמאות/קודקים)[ ] Canary + auto-SLO rollback[ תוכנית התקשורת ], עמוד השער[ ] אימוץ ולוחות מחוונים וטעויותמייג 'ור
[ ] RFC/ADR, תאריך שקיעה ו 90 חלון -180 ימים[ ] v1↔v2 מדריך הגשר והנדידה[ ] כתיבה כפולה/קריאה ופיוס[ ] SDK עם שני התראות API +[ ] פיילוט עם משלבי מפתח15) תוכנית יישום (3 איטרציות)
1. קרן (2 שבועות):
רישום של מזימות, מצעים ודיפ אוטומטי במודיעה; מדיניות תאימות; כותרות ”ירידה/שקיעה”.
2. שחרור מנוהל (3-4 שבועות):
קנריות, דגלים, התראות SLO; פורטל גרסה; SDK משחרר עם תמיכה בסניפים 2.
3. אוטומציה וסולם (רציף):
בדיקות CDC של צרכנים ב CI, תחזית שקיעה על מגמות אימוץ, הודעות אוטומטיות ותזכורות.
16) מיני ־ FAQ
אני יכול לשנות את סוג השדה בלי מייג 'ור?
לא, זה לא אפילו ”סטרוקה * צ 'יסלו” נשבר. הזן שדה חדש, הישן הוא פחת.
האם אתה יכול להוסיף ערכים?
כן, אם לקוחות הם קוראים סובלניים. אחרת - קודם התראה ובטא.
כמה עולה להחזיק את הגרסה הישנה?
עד כה, האימוץ של 95% החדשים נשמר. תקן את המועד האחרון במדיניות.
סך הכל
תאימות API היא דיסציפלינה: גישה תוספתית, מזימות רשמיות ודיפתיות, שחרור כנרית, צמצום ברור והגירה מנוהלת. תאחד מדיניות שינוי, תבדוק אוטומטית ותקשורת, תמדוד אימוץ - והעדכונים שלך יפסיקו לשבור לקוחות, ומהירות האבולוציה תגדל בלי לאבד אמינות.