הגדרת בדיקת תאימות API בצינור CI/CD

תאימות API נשברת בשקט: היכן צוואר הבקבוק ב-CI/CD

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

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

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

תאימות לאחור הופרה, אבל אין אות: הבנייה ירוקה, הבדיקות עברו, המדדים נופלים מאוחר יותר ולא במקום שבו מחפשים. האבחון עובר לניתוח לוגים בצד הלקוח, ולא ב-CI/CD pipeline שבו נעשתה הטעות.

המחיר של תקלה כזו מורכב משלושה חלקים: זמן לאיתור הסיבה האמיתית בין כמה שחרורים, rollback דחוף או patch תחת לחץ, ובדיקה ידנית של חוזים בין צוותים, שנאלצים לעשות בדיעבד.

ככל שיותר שירותים תלויים ב-API אחד, כך רדיוס ההשפעה רחב יותר: breaking change אחד שהוחמץ גורר אחריו מפל של תיקונים אצל כל הצרכנים.

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

מה נותנת בדיקת תאימות API בצינור הבנייה

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

מה בדיוק תופסת השוואת מפרטים

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

מצבי בדיקה והמחיר שלהם

המצב קובע מה הצינור עושה כאשר נמצא פער. אזהרה נוחה בשלב ההרצה הראשונית של הכלל: הצוות רואה פערים, אבל הבנייה ממשיכה. חסימת בנייה — מצב עבודה לענפים יציבים: שינוי בלתי תואם просто לא עובר הלאה. השוואה לענף יציב מסננת עריכות מקריות ששוברות חוזה שכבר שוחרר.

OpenAPI Diff — אחד הכלים שנותן דוח קריא למכונה על פערים ומשתלב בשלב הבנייה ללא הגדרה ידנית.

כיצד אנו מטמיעים בדיקת תאימות בצינור העבודה

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

1. מלאי חוזים. אוספים מפרטים (OpenAPI, סכימות gRPC, AsyncAPI), מתאימים אותם למאגרי קוד ומוצאים חוזים נסתרים שקיימים רק בקוד או בהתכתבות. התוצר — מרשם שירותים עם ציון הבעלים והצרכנים.
2. סיווג שינויים. מחלקים תיקונים לשוברים ולתואמים לאחור: מחיקת שדה, צמצום טיפוס, שינוי חובה, שינוי שם מתודה. זה הבסיס לכללים — בלעדיו הבדיקה או מפספסת שברים, או חוסמת הכול.
3. הגדרת כללים וספים. קובעים מה נחשב להפרה ומה לאזהרה, מגדירים חריגים לשדות מיושנים ותקופות החיים שלהם. את הכללים שמים במאגר הקוד לצד הקוד, כדי שינוהלו בגרסאות יחד איתו.
4. הטמעה בצינור העבודה. משווים את המפרט הנוכחי לגרסת הבסיס מהענף הראשי, ומחזירים את התוצאה כסטטוס בדיקה. בשינוי שובר הבנייה נופלת עם ציון השדה הספציפי והצרכן שזה ישפיע עליו.
5. הרצת ניסיון על שינויים אמיתיים. מריצים את הכלל על כמה תיקונים שעברו ועל שבר שהוכנס בכוונה — מוודאים שאין התראות שווא ושהבדיקה תופסת את מה שלשמו הוצבה.
6. תיעוד ומסירה. מוסרים לצוות תיאור כללים, הוראות עקיפה לחריגים מודעים ונוהל עדכון גרסת הבסיס של המפרט.

לאחר המסירה הבדיקה מתקיימת ללא מעורבותנו: שירותים חדשים מתחברים לפי התבנית המתוארת, ומקרים שנויים במחלוקת נבחנים לפי כללים מעוגנים, ולא בהתכתבות. תארו את המשימה שלכם — נחזור עם הערכה ותוכנית עבודה.

במה שונה בדיקה בשלב הבנייה מבדיקה בסביבה?

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

הזזה שמאלה — זה על העברת בדיקת התאימות של ה-API לשלב המוקדם ביותר שבו בכלל אפשר לבצע אותה. בבנייה זמינים רק ארטיפקטים ומפרט, אבל המשוב מגיע תוך דקות ולא דורש תשתית מורמת.

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

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

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

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

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

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

מקרה בוחן: איך הסרנו שינויים שוברים מהשחרורים

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

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

מה השתנה במספרים

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

בנפרד הגדרנו דוח אי-התאמות: הוא מראה איזה צרכן בדיוק נפגע ואיזה שדה השתנה. זה הסיר את ההתכתבות "אצלי הכל נשבר" — בכניסה רואים מיד את הגורם ואת היקף התיקון. הבדיקה נבנתה על בסיס OpenAPI והשוואת גרסאות מפרטים בצינור.

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

ספקות לפני הטמעה: הרשאות, מיגרציה, חזרה לאחור

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

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

כיצד מבוצעת חזרה לאחור של שינויים? הכלל חי בגיטהאב כקובץ תצורה רגיל. חזרה לאחור היא revert של קומיט שמחזיר את התנהגות הבדיקה הקודמת בהרצה אחת של הצינור, ללא בנייה מחדש של סביבות.

מה אם הצרכנים כבר שבורים? הדוח מראה אילו שדות ומתודות בדיוק נפגעו ומי מהצרכנים משתמש בהם — התיקונים מבוצעים ממוקד, ולא "לפי העין".

לאחר המסירה הלקוח מקבל לידיו:

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

תארו את המשימה שלכם — נחזור עם הערכה ותוכנית הטמעה לצינור שלכם.

לוחות זמנים ליישום בדיקת תאימות לפי שלבים

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

להלן — משך משוער של השלבים; הוא תלוי במספר השירותים, בתדירות המהדורות ובמידת התיעוד של החוזה הנוכחי.

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

האם אפשר להאיץ? כן, אם החוזה כבר מתואר באופן קריא למכונה — שלבי הקיבוע וסינון הרעש מתקצרים בחצי. מה אם יש הרבה שירותים? השלבים מתבצעים במקביל לפי קבוצות שירותים, משך הזמן הכולל גדל לא באופן ליניארי, אלא לפי השרשרת הארוכה ביותר של תלויות.

תארו את המשימה שלכם — נחזור עם הערכה ותוכנית המותאמת לקונטור שלכם.