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

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



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

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

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


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

एनोटेशन क्यों?

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

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


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

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

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

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

सामान्य तौर पर, माइक्रोसर्विस के लिए अनुबंधों के आवेदन में रचनात्मकता के लिए क्षेत्र बहुत बड़ा है ... कम से कम सैद्धांतिक रूप से

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

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

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

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

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

यदि एक के लिए नहीं, लेकिन ...

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

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

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

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

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

क्या मुझे चुनने की आवश्यकता है?

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

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

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

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

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

निष्कर्ष

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

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

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

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