ויסות סמנטי

Semantic Versioning (SemVer) - חוזה על האופן שבו מספר הגרסה משקף את אופי השינויים. תבנית: מייג 'ור. מינורי. תיקון -PRERELEASE + לבנות.

• סרן - שינויים לא מתאימים (שבירה).
• תוספות/תוספות תואמות הדדיות קלות.
• תיקון - אחורה תואם באג/תיקוני אבטחה.

מטרה: אבולוציה צפויה של API, אירועים, תרשימי נתונים, SDKs ותצורות ללא התמוטטות צרכנים פתאומית.

1) מספרי אמנה

X.Y.Z[-alpha.1    -rc.1][+build.sha]

שחרור מראש (”- alpha”, ”- beta”, ”- rc”) - אסיפות לא יציבות; אל תבטיח תאימות.
בניית metadata (”+ sha”) - אינה משפיעה על סדר ההשוואה, שימושית לאיתור.
עד 1. 0. 0 כל שינוי יכול להיחשב לשבירה (אבל עדיף לציית לחוקים מההתחלה).

2) מה לשקול שבירה/מינור/תיקון

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

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

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

3) ויסות חפצים

3. 1 מנוחה

וריאציות: "URI/v1/"..., כותרות (" קבל: יישום/vnd. Acme. משחק + json; גרסה = 1 '), פרמטר.
המלצה: גרסה ב-URI לאפליקציות ציבוריות; למשא ומתן פנימי באמצעות הכותרת c.
מינור: הוסף שדות אופציונליים, מסננים/משאבים חדשים; אל תשנה את התשובות הקיימות.
תיקונים, עידון הגדרה, מיון יציב.

3. 2 GRPC

משנה חתימות/סוגים (חבילה/שירות חדש: acme. ארנק. v2 '.
שדות חדשים מתויגים כאופציונליים; השרת חייב להתעלם מהלא נודע.
איננו מוחקים את השדות: "desprict + reserve a number", מחק - רק ברה "מ הבא.

3. 3 GraphQL

מינור: שדות חדשים/סוגים/שאילתה; הסרה דרך חלון הנדידה, הסרה מלאה, מייג 'ור.
שינוי בס "ג בלתי ניתן לבחירה - MAJOR.

3. 4 אירועים ונושאים (קפקא/SQS)

סכימות ב ־ Schema Registry: אבולוציה של תוסף (הוספת שדות עם ברירות מחדל).
גרסה לא תואמת חדשה = נושא/נושא חדש ('bt. v2 '.
מפתח המחיצה לא ניתן לשינוי בתוך מייג 'ור.

3. דיאגרמות 5 DB

1. הוסף טור (nullable/defreduction) @ action: inmenu

2. מלא את הילוך אחורי #

3. תרגם מספר קריאות

4. הסר ישן (מייג 'ור בלבד).

שינוי סוג/PK/ייחודיות - MAJOR, תחת הפישפלאג וכניסה כפולה.

3. 6 SDK/CLI

שיטות/חתימות ציבוריות הן אותם כללים.
עבור אוטוגנרציה (OpenAPI/Proto) - גרסה של שם האצווה וחפצים.

4) מדיניות קיפוח ומחזור חיים

כל שינוי שבירה מקדים על ידי דפריקציה (בדרך כלל 90-180 ימים לחיצוניות, 30-60 לפנים).
תקשורת: changelog, דואר אלקטרוני/ספרי אינטרנט לשותפים, באנרים בפורטל מפתח.
מצב ריצה כפולה: לשמור 'v1' ו 'v2' במקביל, לפקח על נתח התנועה 'v1'.
כותרות שקיעה (השאר): ”שקיעה: 2026-03-31”, קישור: <url> ריל = ”ירידה”.

5) משא ומתן גרסה

הלקוח שולח את הגרסה הרצויה + הגרסה הנתמכת המקסימלית (לדוגמה, 'קבל-גרסה: 1,2').
השרת מגיב ב-Content-Version: 2 &posship if if הוא יכול לקדם.
בפרוטוקולים דו כיווניים (WebSocket, gRPC) - החלפת מסגרות Hello עם ”personed _ grases”.

6) אינטגרציית מתאם ספקים (ACL)

הספק החיצוני משנה את התרשים - בתוך המתאם אנו שומרים את v1/v2 mappers ומשחררים את MINOR עבור האירוע הפנימי, תוך שמירה על חוזה התחום שלנו.
אם שינויים חיצוניים עושים את דרכם פנימה, זהו המייג 'ור של אירוע התחום שלנו ונושא חדש.

7) Changelog ולהתחייב תוויות

• ”feat:”..
• 'fix:... '/' chore ',' docs', 'perf' (אין חוזה) * טלאי
• "Feate '- '/' לתקן': '/' refactor ':' או 'BREKING TRANSLATORY:' IN MAJOR '

[2.3.0] - 2025-10-31
Added
- GET /v1/games?capabilities=jackpot (optional)
Changed
- GraphQL: field Game.volatility @deprecated, use Game.riskProfile

8) שחרור אוטומציה

CI: אימות מעגל (OpenAPI/Protobuf/Avro/JSON-Schema), איתור שבירת דיפוזיה. יותר ויותר

SemVer-bot: Analysis Convention Commits # מחשבת בליטה (major/minor/tach), מציבה תג, יוצרת צ 'אנגלוג.
CD: פריסה ושחרור נפרדים (פישפלאגים/תצורה מפעילים את הגרסה החדשה).
בקרה: אל תפרסם ”האחרון” על PRO עד Canary מוצלח ו SLOs מוסכם.

9) סמנטיקה לתצורות ומדיניות

לתצורה (YAML/JSON) יש גם גרסה: ”schema _ version: 3”.
שדות אופציונליים חדשים/כללים מייג 'ור - שינוי מבנה/חובה.
תמיכה v2/v3 באימות; קונדיטור נודד עם דו "ח אי-התאמה.

10) בדיקת תאימות

בדיקות חוזה מונעות על ידי צרכן (pact): לכל אינטגרציה.
בדיקות סכימה-אבולוציה: להריץ מטען ישן על סכימה חדשה ולהיפך.
משחק את תנועת ההפקה 'v1' עד 'v2' בצל.
מבוסס רכוש: התנגדות לשדות לא מוכרים/אינום.

11) יכולת תצפית לפי גרסה

תגית metrics/logs: ”api _ version”, ”schema _ version”, ”event _ version”.
לוחות מחוונים: שיתוף תנועה על ידי גרסאות, שגיאה/איחור על ידי 'v1/v2'.
התראות: אם 'v1' לא יורד כמתוכנן; 4xx/5xx גידול לאחר 'v2' שחרור.

12) תבניות נדידה ללא זמן השבתה

Extreme # Migrate # Contract (Intraction).
כתיבה כפולה + השווה בין חילוקי דעות לפני החלפת הקריאה.
השוואת צל לדירוג/כללים.
קנרית על ידי דייר/אזור; דגלי תכונה עבור גלגיליות מהירות.
חלונות Read-compat/Write-compat: הגרסה החדשה קוראת נתונים ישנים, אך כותבת בפורמט חדש.

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

”גרסה בכל תחום” במקום להעביר את המשאב/אירוע.
שינויי שבירה חבויים תחת MINOR (לדוגמה, שינוי ברירת המחדל).
הסרה של מדוכאים ללא מדדי חלון וצריכה.
”Forever v1”: אין תוכנית להסיר גרסאות ישנות של חובות טכניים ופגיעות.
ערבב את הגרסה העסקית ואת גרסת תמונת המכולה.

14) בדיקת מדיניות וריאציות

[ ] פורמט גרסה קבועה ומקורות אמת (Registry/Portal).

[ ] הרשימה המאושרת של קריטריוני שבירה על ידי חפצים (REST/gRPC/GraphQL/Events/DB).

[ תהליך ]: תזמון, תקשורת, שקיעה/באנרים, הפעלה כפולה.

[ ] האוטומטי diff בודק ומתחייב קונבנציונלי.

[ גרסה ] ולוחות מחוונים לצריכה התראה.

[ ] ספרי משחק נדידה (להרחיב/להגר/חוזה, דו-כתיבה, צל).

[ ] קונפיג 'ים וSDKs יש גרסאות ומקרה משלהם.

[ תיעוד ] ”איך לבחור גרסה” ללקוחות ו ”איך לשדרג” לצוותים.

15) דוגמאות של ורסינציה (מקרי iGaming)

'Bettsoled v1&fosposate everent =' v2 ': הוסף' void _ reason '(אופציונלי) ו' מס '. סכום (אופציונלי) מינורי. שונה שם "תשלום" = "win _ suml' - מייג 'ור, נושא חדש.
מנוחה '/ארנקים/העברה ': מסנן מוסף'? דייר _ id = - מינורי. שינוי קוד השגיאה ”409” ”# 422” - MAJOR.

GraphQL: מסומן 'Player. גיל כמו '@ distrated' לטובת 'Player. Geage 'Group - שחרור מינורי, מחיקה במייג' ור לאחר תקופה X

DB: הוסף טור "bonus _ ger _ left 'nulable - MINOR. נעשה לא מבוטל ונמחק ”בונוס שמאלה” - MAJOR (באמצעות הרחבת/חוזה).

מסקנה

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