אז האם זה RAML או OAS (Swagger)?

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

הוכן פוסט אנה מלכובה и ולדימיר לאפטין

שירותי מיקרו. כשפיתחנו את Acronis Cyber ​​​​Cloud, הבנו שאנחנו לא יכולים לברוח מהם. ותכנון מיקרו-שירות בלתי אפשרי ללא יצירת החוזה, המייצג את הממשק של המיקרו-שירות.

אבל כאשר מוצר מכיל יותר ממרכיב אחד, ופיתוח חוזים הופך לפעילות קבועה, אי אפשר שלא להתחיל לחשוב על אופטימיזציה של תהליכים. ברור שהממשק (החוזה) והיישום (microservice) חייבים להתאים זה לזה, שרכיבים שונים חייבים לעשות את אותם דברים באותו אופן, ושבלי קבלת החלטות מרוכזת של כל ההחלטות הללו, כל צוות ייאלץ לעשות לבזבז זמן שוב ושוב כדי להשיג אותם.

דיאגרמת שירותי מיקרו של אמזון מ צִיוּץ ורנר ווגליס, CTO של אמזון
מהי הדילמה? דה פקטו, ישנן שתי דרכים ליצור אינטראקציה עם שירותי מיקרו - HTTP Rest ו-gRPC מגוגל. לא מתוך רצון להיתפס לערימת הטכנולוגיה של גוגל, בחרנו ב-HTTP Rest. הערות חוזי HTTP REST מתוארות לרוב באחד משני פורמטים: RAML ו-OAS, שנקראו בעבר Swagger. לכן, כל צוות פיתוח עומד בפני הצורך לבחור באחד מהסטנדרטים. אבל כפי שמתברר, בחירה זו יכולה להיות קשה מאוד.

מדוע יש צורך בביאורים?

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

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

דוגמה לתיאור חוזה מובנה

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

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

כדי לאפשר כלים נוספים, גם ל-RAML וגם ל-OAS יש את היכולת להוסיף מטא נתונים שאינם מסופקים בתקן (לדוגמה, כך זה נעשה ב-OAS).

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

השוואה של קיפוד עם נחש

נכון לעכשיו, אזור הפיתוח המועדף ב-Acronis הוא פיתוח פלטפורמת הסייבר של Acronis. Acronis Cyber ​​​​Platform היא נקודות אינטגרציה חדשות של שירותי צד שלישי עם Acronis Cyber ​​​​Cloud וחלק הסוכן. למרות שהיינו מרוצים מממשקי ה-API הפנימיים שלנו המתוארים ב-RAML, הצורך לפרסם את ה-API שוב העלה את שאלת הבחירה: באיזה תקן הערות הכי טוב להשתמש לעבודה שלנו?

בתחילה נראה היה שיש שני פתרונות - הפיתוחים הנפוצים ביותר היו RAML ו-Swagger (או OAS). אבל למעשה התברר שיש לפחות לא 2 חלופות, אלא 3 או יותר.

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

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

אם לא לאחד אבל...

כפי שמתברר, לא כל כלי השירות בקוד פתוח עודכנו ל-OAS 3.0. עבור שירותי מיקרו ב-Go, הדבר הקריטי ביותר יהיה חוסר ההתאמה הולך-סוואגר עבור הגרסה העדכנית ביותר של התקן. עם זאת, ההבדל בין Swagger 2 ל- Swagger 3 הוא עָצוּם. לדוגמה, בגרסה השלישית המפתחים:

• תיאור משופר של סכימות אימות
• הושלם תמיכה ב-JSON Schema
• שדרג את היכולת להוסיף דוגמאות

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

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

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

האם צריך לבחור?

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

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

1. oas-raml-converter הוא כלי עזר שאינו נתמך כרגע. במהלך העבודה איתו, גילינו שיש לו מספר בעיות עם רכיבי RAML מורכבים ש"מתפרסים" על פני מספר רב של קבצים. תוכנית זו כתובה ב-JavaScript ומבצעת מעבר רקורסיבי של עץ תחביר. עקב הקלדה דינמית, קשה להבין את הקוד הזה, אז החלטנו לא לבזבז זמן בכתיבת תיקונים עבור כלי עזר גוסס.
2. webapi-parser - כלי של אותה חברה שמתיימרת להיות מוכנה להמיר כל דבר ועניין, ולכל כיוון. עד כה, הוכרזה תמיכה עבור RAML 0.8, RAML 1.0 ו-Swagger 2.0. עם זאת, בזמן המחקר שלנו, השירות היה עדיין מְאוֹד לח ולא שמיש. מפתחים יוצרים סוג של IR, מה שמאפשר להם להוסיף במהירות תקנים חדשים בעתיד. אבל בינתיים זה פשוט לא עובד.

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

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

מסקנה

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

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

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

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

רק משתמשים רשומים יכולים להשתתף בסקר. להתחברבבקשה.

באיזו שפה אתה משתמש כדי להעיר חוזי שירות מיקרו?

• RAML 0.8

• RAML 1.0

• סוואגר 2

• OAS3 (aka)

• תכנית אב

• אחר

• לא משתמש

100 משתמשים הצביעו. 24 משתמשים נמנעו.

מקור: www.habr.com