तो क्या यह RAML या OAS (स्वैगर) है?

माइक्रोसर्विसेज की गतिशील दुनिया में, कुछ भी बदल सकता है - किसी भी घटक को विभिन्न रूपरेखाओं और वास्तुकला का उपयोग करके एक अलग भाषा में फिर से लिखा जा सकता है। केवल अनुबंध अपरिवर्तित रहना चाहिए ताकि आंतरिक कायापलट की परवाह किए बिना, माइक्रोसर्विस को कुछ स्थायी आधार पर बाहर से बातचीत की जा सके। और आज हम अनुबंधों का वर्णन करने के लिए एक प्रारूप चुनने और हमें मिली कलाकृतियों को साझा करने की अपनी समस्या के बारे में बात करेंगे।

पोस्ट तैयार अन्ना मेलेखोवा и व्लादिमीर लापाटिन

माइक्रोसर्विसेज। एक्रोनिस साइबर क्लाउड विकसित करते समय हमें एहसास हुआ कि हम उनसे बच नहीं सकते। और अनुबंध को औपचारिक रूप दिए बिना माइक्रोसर्विस को डिज़ाइन करना असंभव है, जो माइक्रोसर्विस के इंटरफ़ेस का प्रतिनिधित्व करता है।

लेकिन जब किसी उत्पाद में एक से अधिक घटक होते हैं, और अनुबंध विकास एक नियमित गतिविधि बन जाती है, तो आप मदद नहीं कर सकते, लेकिन प्रक्रिया अनुकूलन के बारे में सोचना शुरू कर सकते हैं। यह स्पष्ट हो जाता है कि इंटरफ़ेस (अनुबंध) और कार्यान्वयन (माइक्रोसर्विस) को एक-दूसरे से मेल खाना चाहिए, कि विभिन्न घटकों को एक ही तरह से समान कार्य करना चाहिए, और इन सभी निर्णयों के केंद्रीकृत निर्णय के बिना, प्रत्येक टीम को मजबूर होना पड़ेगा उन्हें पाने के लिए बार-बार समय खर्च करें।

अमेज़ॅन माइक्रोसर्विसेज आरेख से ट्वीट वर्नर वोगेलिस, सीटीओ अमेज़ॅन
दुविधा क्या है? वास्तव में, माइक्रोसर्विसेज से इंटरैक्ट करने के दो तरीके हैं - Google से HTTP रेस्ट और gRPC। Google की प्रौद्योगिकी स्टैक में फंसने की इच्छा न रखते हुए, हमने HTTP रेस्ट को चुना। HTTP REST अनुबंध एनोटेशन को अक्सर दो प्रारूपों में से एक में वर्णित किया जाता है: RAML और OAS, जिन्हें पहले स्वैगर के नाम से जाना जाता था। इसलिए, प्रत्येक विकास टीम को मानकों में से एक को चुनने की आवश्यकता का सामना करना पड़ता है। लेकिन जैसा कि पता चला है, यह चुनाव करना बहुत कठिन हो सकता है।

एनोटेशन की आवश्यकता क्यों है?

एनोटेशन की आवश्यकता है ताकि बाहरी उपयोगकर्ता आसानी से यह पता लगा सके कि HTTP इंटरफ़ेस के माध्यम से आपकी सेवा के साथ क्या किया जा सकता है। अर्थात्, बुनियादी स्तर पर, एनोटेशन में कम से कम उपलब्ध संसाधनों की एक सूची, उनके HTTP तरीके, अनुरोध निकाय, मापदंडों की एक सूची, आवश्यक और समर्थित हेडर का एक संकेत, साथ ही रिटर्न कोड और प्रतिक्रिया प्रारूप शामिल होने चाहिए। अनुबंध एनोटेशन का एक अत्यंत महत्वपूर्ण तत्व उनका मौखिक विवरण है ("यदि आप इस क्वेरी पैरामीटर को अनुरोध में जोड़ते हैं तो क्या होगा?", "किस स्थिति में कोड 400 वापस किया जाएगा?")

हालाँकि, जब बड़ी संख्या में माइक्रोसर्विसेज विकसित करने की बात आती है, तो आप लिखित एनोटेशन से अतिरिक्त मूल्य निकालना चाहते हैं। उदाहरण के लिए, RAML/Swagger के आधार पर, आप बड़ी संख्या में प्रोग्रामिंग भाषाओं में क्लाइंट और सर्वर दोनों कोड उत्पन्न कर सकते हैं। आप स्वचालित रूप से माइक्रोसर्विस के लिए दस्तावेज़ प्राप्त कर सकते हैं और इसे अपने डेवलपर-पोर्टल पर अपलोड कर सकते हैं :)।

संरचित अनुबंध विवरण का उदाहरण

अनुबंध विवरण के आधार पर माइक्रोसर्विसेज का परीक्षण करने की प्रथा कम आम है। यदि आपने एनोटेशन और घटक दोनों लिखे हैं, तो आप एक ऑटोटेस्ट बना सकते हैं जो विभिन्न प्रकार के इनपुट डेटा के साथ सेवा की पर्याप्तता की जांच करता है। क्या सेवा एक प्रतिक्रिया कोड लौटाती है जिसका वर्णन एनोटेशन में नहीं किया गया है? क्या यह स्पष्ट रूप से गलत डेटा को सही ढंग से संसाधित करने में सक्षम होगा?

इसके अलावा, न केवल अनुबंधों का उच्च गुणवत्ता वाला कार्यान्वयन, बल्कि एनोटेशन को विज़ुअलाइज़ करने के उपकरण भी माइक्रोसर्विस के साथ काम को सरल बनाना संभव बनाते हैं। अर्थात्, यदि आर्किटेक्ट ने अनुबंध को उच्च-गुणवत्ता वाले तरीके से वर्णित किया है, तो उसके आधार पर, डिजाइनर और डेवलपर्स अतिरिक्त समय लागत के बिना अन्य उत्पादों में सेवा को लागू करेंगे।

अतिरिक्त टूल सक्षम करने के लिए, RAML और OAS दोनों में मानक द्वारा प्रदान नहीं किए गए मेटाडेटा को जोड़ने की क्षमता है (उदाहरण के लिए, OAS में यह इसी प्रकार किया जाता है).

सामान्य तौर पर, माइक्रोसर्विसेज के लिए अनुबंधों का उपयोग करने में रचनात्मकता की गुंजाइश बहुत बड़ी है... कम से कम सिद्धांत में।

हाथी की तुलना साँप से

वर्तमान में, Acronis में प्राथमिकता वाला विकास क्षेत्र Acronis साइबर प्लेटफ़ॉर्म का विकास है। Acronis साइबर प्लेटफ़ॉर्म Acronis साइबर क्लाउड और एजेंट भाग के साथ तृतीय-पक्ष सेवाओं के एकीकरण के नए बिंदु हैं। यद्यपि हम RAML में वर्णित अपने आंतरिक एपीआई से खुश थे, एपीआई को प्रकाशित करने की आवश्यकता ने फिर से विकल्प का प्रश्न उठाया: हमारे काम के लिए कौन सा एनोटेशन मानक उपयोग करना सबसे अच्छा है?

प्रारंभ में, ऐसा लगा कि दो समाधान थे - सबसे आम विकास RAML और स्वैगर (या OAS) थे। लेकिन वास्तव में यह पता चला कि कम से कम 2 विकल्प नहीं हैं, बल्कि 3 या अधिक हैं।

एक ओर RAML है - एक शक्तिशाली और कुशल भाषा। यह पदानुक्रम और विरासत को अच्छी तरह से लागू करता है, इसलिए यह प्रारूप बड़ी कंपनियों के लिए अधिक उपयुक्त है जिन्हें बहुत सारे विवरणों की आवश्यकता होती है - अर्थात, एक उत्पाद नहीं, बल्कि कई माइक्रोसर्विसेज जिनमें अनुबंध के सामान्य भाग होते हैं - प्रमाणीकरण योजनाएं, समान डेटा प्रकार, त्रुटि निकाय .

लेकिन RAML का डेवलपर, Mulesoft, ओपन एपीआई कंसोर्टियम में शामिल हो गया है, जो विकास कर रहा है अकड़. इसलिए, RAML ने अपना विकास निलंबित कर दिया। घटना के प्रारूप की कल्पना करने के लिए, कल्पना करें कि मुख्य लिनक्स घटकों के अनुरक्षक माइक्रोसॉफ्ट के लिए काम करना छोड़ देते हैं। यह स्थिति स्वैगर का उपयोग करने के लिए आवश्यक शर्तें बनाती है, जो गतिशील रूप से विकसित हो रही है और नवीनतम - तीसरे संस्करण में - लचीलेपन और कार्यक्षमता के मामले में व्यावहारिक रूप से RAML के बराबर है।

अगर एक बात के लिए नहीं लेकिन...

जैसा कि यह पता चला है, सभी ओपन-सोर्स उपयोगिताओं को OAS 3.0 में अपडेट नहीं किया गया है। गो में माइक्रोसर्विसेज के लिए, सबसे महत्वपूर्ण बात अनुकूलन की कमी होगी गो-स्वैगर मानक के नवीनतम संस्करण के लिए. हालाँकि, स्वैगर 2 और स्वैगर 3 के बीच अंतर है विशाल. उदाहरण के लिए, तीसरे संस्करण में डेवलपर्स:

• प्रमाणीकरण योजनाओं का बेहतर विवरण
• पूरा कर लिया है JSON स्कीमा समर्थन
• उदाहरण जोड़ने की क्षमता उन्नत की गई

स्थिति हास्यास्पद है: मानक चुनते समय, आपको RAML, स्वैगर 2 और स्वैगर 3 को अलग-अलग विकल्पों के रूप में विचार करने की आवश्यकता है। हालाँकि, केवल स्वैगर 2 में ओपनसोर्स टूल के लिए अच्छा समर्थन है। RAML बहुत लचीला है...और जटिल है, और स्वैगर 3 को समुदाय द्वारा खराब समर्थन प्राप्त है, इसलिए आपको मालिकाना उपकरण या व्यावसायिक समाधान का उपयोग करना होगा, जो काफी महंगे होते हैं।

इसके अलावा, अगर स्वैगर में कई अच्छी सुविधाएं हैं, जैसे कि एक रेडीमेड पोर्टल editor.swagger.io, जिस पर आप एक एनोटेशन अपलोड कर सकते हैं और विस्तृत विवरण, लिंक और कनेक्शन के साथ इसका विज़ुअलाइज़ेशन प्राप्त कर सकते हैं, फिर अधिक मौलिक और कम अनुकूल RAML के लिए ऐसा कोई अवसर नहीं है। हां, आप GitHub पर परियोजनाओं के बीच कुछ खोज सकते हैं, वहां एक एनालॉग ढूंढ सकते हैं और इसे स्वयं तैनात कर सकते हैं। हालाँकि, किसी भी स्थिति में, किसी को पोर्टल का रखरखाव करना होगा, जो बुनियादी उपयोग या परीक्षण आवश्यकताओं के लिए इतना सुविधाजनक नहीं है। इसके अलावा, स्वैगर अधिक "असैद्धांतिक" या अधिक उदार है - इसे कोड में टिप्पणियों से उत्पन्न किया जा सकता है, जो निश्चित रूप से एपीआई पहले सिद्धांत के खिलाफ जाता है और किसी भी RAML उपयोगिता द्वारा समर्थित नहीं है।

एक समय में हमने अधिक लचीली भाषा के रूप में RAML के साथ काम करना शुरू किया और परिणामस्वरूप हमें बहुत सारे काम स्वयं करने पड़े। उदाहरण के लिए, परियोजनाओं में से एक उपयोगिता का उपयोग करती है रामलफिकेशन यूनिट परीक्षणों में, जो केवल RAML 0.8 का समर्थन करता है। इसलिए हमें बैसाखी जोड़नी पड़ी ताकि उपयोगिता RAML संस्करण 1.0 को "खा" सके।

क्या आपको चुनने की ज़रूरत है?

RAML के लिए समाधानों के पारिस्थितिकी तंत्र को पूरा करने पर काम करने के बाद, हम इस निष्कर्ष पर पहुंचे कि हमें RAML को स्वैगर 2 में परिवर्तित करने और इसमें सभी स्वचालन, सत्यापन, परीक्षण और उसके बाद के अनुकूलन को पूरा करने की आवश्यकता है। यह RAML के लचीलेपन और स्वैगर के सामुदायिक टूलींग समर्थन दोनों का लाभ उठाने का एक अच्छा तरीका है।

इस समस्या को हल करने के लिए, दो ओपनसोर्स उपकरण हैं जो अनुबंध रूपांतरण प्रदान करना चाहिए:

1. ओएस-रैमएल-कन्वर्टर वर्तमान में असमर्थित उपयोगिता है. इसके साथ काम करते समय, हमने पाया कि इसमें जटिल रैमएल के साथ कई समस्याएं हैं जो बड़ी संख्या में फाइलों में "फैली हुई" हैं। यह प्रोग्राम जावास्क्रिप्ट में लिखा गया है और एक सिंटैक्स ट्री का पुनरावर्ती ट्रैवर्सल करता है। गतिशील टाइपिंग के कारण, इस कोड को समझना मुश्किल हो जाता है, इसलिए हमने एक ख़त्म हो रही उपयोगिता के लिए पैच लिखने में समय बर्बाद न करने का निर्णय लिया।
2. वेबपि-पार्सर - उसी कंपनी का एक उपकरण जो किसी भी चीज़ और हर चीज़ को और किसी भी दिशा में बदलने के लिए तैयार होने का दावा करता है। आज तक, RAML 0.8, RAML 1.0 और स्वैगर 2.0 के लिए समर्थन की घोषणा की गई है। हालाँकि, हमारे शोध के समय उपयोगिता अभी भी थी अत्यंत नम और अनुपयोगी. डेवलपर्स एक तरह का निर्माण करते हैं IR, जिससे उन्हें भविष्य में शीघ्रता से नए मानक जोड़ने की अनुमति मिलती है। लेकिन अभी तक यह काम नहीं कर पाया है।

और ये सभी कठिनाइयां नहीं हैं जिनका हमने सामना किया। हमारी पाइपलाइन में एक कदम यह सत्यापित करना है कि रिपॉजिटरी से RAML विनिर्देश के सापेक्ष सही है। हमने कई उपयोगिताएँ आज़माईं। आश्चर्य की बात यह है कि उन सभी ने अलग-अलग स्थानों पर और पूरी तरह से अलग-अलग बुरे शब्दों के साथ हमारी टिप्पणियों पर शपथ ली। और हमेशा मुद्दे पर नहीं :)।

अंत में, हमने अब एक पुराने प्रोजेक्ट पर समझौता कर लिया, जिसमें कई समस्याएं भी हैं (कभी-कभी यह अचानक क्रैश हो जाता है, रेगुलर एक्सप्रेशन के साथ काम करते समय समस्याएं होती हैं)। इस प्रकार, हमें मुफ़्त टूल के आधार पर सत्यापन और रूपांतरण की समस्याओं को हल करने का कोई तरीका नहीं मिला, और एक वाणिज्यिक उपयोगिता का उपयोग करने का निर्णय लिया। भविष्य में, जैसे-जैसे ओपनसोर्स उपकरण अधिक परिपक्व होते जाएंगे, इस समस्या को हल करना आसान हो सकता है। इस बीच, "परिष्करण" के लिए श्रम और समय की लागत हमें व्यावसायिक सेवा की लागत से अधिक महत्वपूर्ण लगी।

निष्कर्ष

इस सब के बाद, हम अपना अनुभव साझा करना चाहते थे और ध्यान देना चाहते थे कि अनुबंधों का वर्णन करने के लिए एक उपकरण चुनने से पहले, आपको यह स्पष्ट रूप से परिभाषित करना होगा कि आप इससे क्या चाहते हैं और आप किस बजट में निवेश करने को तैयार हैं। यदि हम ओपनसोर्स के बारे में भूल जाते हैं, तो पहले से ही बड़ी संख्या में सेवाएँ और उत्पाद मौजूद हैं जो आपको जाँचने, परिवर्तित करने और सत्यापित करने में मदद करेंगे। लेकिन वे महँगे हैं, और कभी-कभी बहुत महँगे भी। एक बड़ी कंपनी के लिए ऐसी लागतें सहनीय होती हैं, लेकिन एक स्टार्टअप के लिए ये एक बड़ा बोझ बन सकती हैं।

उन उपकरणों का सेट निर्धारित करें जिनका आप बाद में उपयोग करेंगे। उदाहरण के लिए, यदि आपको केवल एक अनुबंध प्रदर्शित करने की आवश्यकता है, तो स्वैगर 2 का उपयोग करना आसान होगा, जिसमें एक सुंदर एपीआई है, क्योंकि रैमएल में आपको स्वयं सेवा का निर्माण और रखरखाव करना होगा।
आपके पास जितने अधिक कार्य होंगे, टूल की आवश्यकता उतनी ही व्यापक होगी, और वे अलग-अलग प्लेटफार्मों के लिए अलग-अलग हैं, और भविष्य में आपकी लागत को कम करने वाला विकल्प चुनने के लिए तुरंत उपलब्ध संस्करणों से खुद को परिचित करना बेहतर है।

लेकिन यह पहचानने योग्य है कि आज मौजूद सभी पारिस्थितिक तंत्र अपूर्ण हैं। इसलिए, यदि कंपनी में ऐसे प्रशंसक हैं जो RAML में काम करना पसंद करते हैं क्योंकि "यह आपको विचारों को अधिक लचीले ढंग से व्यक्त करने की अनुमति देता है," या, इसके विपरीत, स्वैगर को पसंद करते हैं क्योंकि "यह अधिक स्पष्ट है," तो उन्हें काम पर छोड़ देना सबसे अच्छा है वे इसके आदी हैं और इसे चाहते हैं, क्योंकि किसी भी प्रारूप के टूल को फ़ाइल के साथ संशोधन की आवश्यकता होती है।

जहां तक ​​हमारे अनुभव की बात है, निम्नलिखित पोस्ट में हम इस बारे में बात करेंगे कि हम अपने रैमएल-स्वैगर आर्किटेक्चर के आधार पर कौन सी स्थिर और गतिशील जांच करते हैं, साथ ही हम अनुबंधों से कौन से दस्तावेज़ तैयार करते हैं, और यह सब कैसे काम करता है।

केवल पंजीकृत उपयोगकर्ता ही सर्वेक्षण में भाग ले सकते हैं। साइन इन करेंकृपया।

माइक्रोसर्विस अनुबंधों को एनोटेट करने के लिए आप किस भाषा का उपयोग करते हैं?

• आरएएमएल 0.8

• आरएएमएल 1.0

• स्वैगर 2

• OAS3 (उर्फ)

• खाका

• अन्य

• का उपयोग नहीं

100 उपयोगकर्ताओं ने मतदान किया। 24 उपयोगकर्ता अनुपस्थित रहे।

स्रोत: www.habr.com