त्यसोभए यो RAML हो वा OAS (Swagger)?

माइक्रोसर्भिसेसको गतिशील संसारमा, जुनसुकै कुरा पनि परिवर्तन हुन सक्छ—कुनै पनि कम्पोनेन्टलाई फरक भाषामा, फरक फ्रेमवर्क र वास्तुकला प्रयोग गरेर पुन: लेख्न सकिन्छ। केवल अनुबंधहरू अपरिवर्तित रहनु पर्छ ताकि माइक्रोसर्भिसलाई आन्तरिक मेटामोर्फोसहरू बिना कुनै स्थायी आधारमा बाहिरबाट अन्तरक्रिया गर्न सकिन्छ। र आज हामी सम्झौताहरू वर्णन गर्नको लागि ढाँचा छनौट गर्ने हाम्रो समस्याको बारेमा कुरा गर्नेछौं र हामीले फेला परेका कलाकृतिहरू साझा गर्नेछौं।

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

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

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

Amazon microservices रेखाचित्र बाट ट्वीट वर्नर भोगेलिस, सीटीओ अमेजन
दुविधा के हो? वास्तवमा, त्यहाँ माइक्रोसेवाहरू अन्तरक्रिया गर्ने दुई तरिकाहरू छन् - HTTP आराम र Google बाट gRPC। गुगलको टेक्नोलोजी स्ट्याकमा फस्न चाहँदैनन्, हामीले HTTP आराम रोज्यौं। HTTP REST अनुबंध एनोटेसनहरू प्रायः दुई ढाँचाहरू मध्ये एउटामा वर्णन गरिन्छ: RAML र OAS, पहिले Swagger भनेर चिनिन्थ्यो। त्यसकारण, प्रत्येक विकास टोलीले मानकहरू मध्ये एउटा छनोट गर्न आवश्यक छ। तर यो बाहिर जान्छ, यो छनौट गर्न धेरै गाह्रो हुन सक्छ।

एनोटेशन किन आवश्यक छ?

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

यद्यपि, जब यो ठूलो संख्यामा माइक्रोसेवाहरू विकास गर्ने कुरा आउँछ, तपाइँ लिखित एनोटेसनहरूबाट थप मूल्य निकाल्न चाहनुहुन्छ। उदाहरणका लागि, RAML/Swagger मा आधारित, तपाइँ प्रोग्रामिङ भाषाहरूको ठूलो संख्यामा ग्राहक र सर्भर कोड दुवै उत्पन्न गर्न सक्नुहुन्छ। तपाईले माइक्रोसर्भिसको लागि स्वचालित रूपमा कागजातहरू प्राप्त गर्न सक्नुहुन्छ र यसलाई आफ्नो विकासकर्ता-पोर्टलमा अपलोड गर्न सक्नुहुन्छ :)।

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

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

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

थप उपकरणहरू सक्षम गर्न, दुबै RAML र OAS सँग मानक (उदाहरणका लागि, यो OAS मा कसरी गरिन्छ).

सामान्यतया, लघु सेवाका लागि अनुबंधहरू प्रयोग गर्ने रचनात्मकताको दायरा ठूलो छ... कमसेकम सिद्धान्तमा।

सर्पसँग हेजहगको तुलना

हाल, Acronis मा प्राथमिकता विकास क्षेत्र Acronis साइबर प्लेटफर्म को विकास हो। Acronis साइबर प्लेटफर्म एक्रोनिस साइबर क्लाउड र एजेन्ट भागको साथ तेस्रो-पक्ष सेवाहरूको एकीकरणको नयाँ बिन्दु हो। यद्यपि हामी RAML मा वर्णन गरिएको हाम्रो आन्तरिक API हरूसँग खुसी थियौं, API लाई प्रकाशित गर्न आवश्यकले फेरि छनौटको प्रश्न खडा गर्‍यो: हाम्रो कामको लागि कुन एनोटेसन मानक प्रयोग गर्न उत्तम छ?

सुरुमा, यस्तो लाग्थ्यो कि त्यहाँ दुई समाधानहरू थिए - सबैभन्दा सामान्य घटनाक्रमहरू RAML र Swagger (वा OAS) थिए। तर वास्तवमा यो बाहिरियो कि त्यहाँ कम्तिमा 2 विकल्पहरू छैनन्, तर 3 वा बढी छन्।

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

तर RAML को विकासकर्ता, Mulesoft, Open API कन्सोर्टियममा सामेल भएको छ, जुन विकास भइरहेको छ। स्वैगर। त्यसैले RAML ले आफ्नो विकास स्थगित गर्यो। घटनाको ढाँचा कल्पना गर्न, कल्पना गर्नुहोस् कि मुख्य लिनक्स कम्पोनेन्टहरूको मर्मतकर्ताहरूले Microsoft को लागि काम गर्न छोडे। यो अवस्थाले स्वेगर प्रयोग गर्नका लागि आवश्यक शर्तहरू सिर्जना गर्दछ, जुन गतिशील रूपमा विकास हुँदैछ र पछिल्लो - तेस्रो संस्करणमा - लचिलोपन र कार्यक्षमताको सन्दर्भमा व्यावहारिक रूपमा RAML सँग मिल्छ।

यदि एक कुराको लागि होइन भने ...

यो बाहिर जान्छ, सबै खुला स्रोत उपयोगिताहरू OAS 3.0 मा अद्यावधिक गरिएको छैन। गो मा माइक्रोसर्भिसेसहरूको लागि, सबैभन्दा महत्त्वपूर्ण कुरा अनुकूलनको कमी हुनेछ हिड्ने मानक को नवीनतम संस्करण को लागी। यद्यपि स्वागर २ र स्वागर ३ बीचको भिन्नता छ विशाल। उदाहरणका लागि, तेस्रो संस्करणमा विकासकर्ताहरू:

• प्रमाणीकरण योजनाहरूको सुधारिएको विवरण
• समाप्त JSON स्कीमा समर्थन
• उदाहरणहरू थप्ने क्षमता अपग्रेड गरियो

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

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

एक पटक हामीले RAML सँग थप लचिलो भाषाको रूपमा काम गर्न थाल्यौं, र परिणाम स्वरूप हामीले धेरै चीजहरू आफैं गर्नुपर्‍यो। उदाहरण को लागी, परियोजनाहरु मध्ये एक उपयोगिता को उपयोग गर्दछ ramlfications एकाइ परीक्षणहरूमा, जसले केवल RAML 0.8 लाई समर्थन गर्दछ। त्यसोभए हामीले बैसाखीहरू थप्नुपर्‍यो ताकि उपयोगिताले RAML संस्करण 1.0 "खान" सकोस्।

के तपाइँ छनौट गर्न आवश्यक छ?

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

यो समस्या समाधान गर्न, त्यहाँ दुई ओपनसोर्स उपकरणहरू छन् जसले अनुबंध रूपान्तरण प्रदान गर्नुपर्छ:

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

र हामीले सामना गरेका सबै कठिनाइहरू होइनन्। हाम्रो पाइपलाइनको एउटा चरण भनेको भण्डारबाट RAML निर्दिष्टीकरणको सापेक्ष सही छ भनेर प्रमाणित गर्नु हो। हामीले धेरै सुविधाहरू प्रयास गर्यौं। अचम्मको कुरा, तिनीहरू सबैले हाम्रो एनोटेसनहरूमा विभिन्न ठाउँहरूमा र पूर्णतया फरक नराम्रो शब्दहरूसँग कसम खाए। र सधैं बिन्दुमा होइन :)।

अन्तमा, हामी अहिले पुरानो परियोजनामा ​​बस्यौं, जसमा धेरै समस्याहरू छन् (कहिलेकाँही यो नीलोबाट क्र्यास हुन्छ, नियमित अभिव्यक्तिहरूसँग काम गर्दा समस्याहरू हुन्छन्)। यसरी, हामीले नि: शुल्क उपकरणहरूमा आधारित प्रमाणीकरण र रूपान्तरणको समस्याहरू समाधान गर्ने तरिका फेला पारेनौं, र व्यावसायिक उपयोगिता प्रयोग गर्ने निर्णय गर्यौं। भविष्यमा, OpenSource उपकरणहरू अधिक परिपक्व हुँदै जाँदा, यो समस्या समाधान गर्न सजिलो हुन सक्छ। यस बीचमा, "समाप्त" को लागी श्रम र समय लागत हामीलाई व्यावसायिक सेवाको लागत भन्दा बढी महत्त्वपूर्ण लाग्थ्यो।

निष्कर्षमा

यी सबै पछि, हामी हाम्रो अनुभव साझा गर्न चाहन्थ्यौं र नोट गर्नुहोस् कि सम्झौताहरू वर्णन गर्नको लागि उपकरण छनौट गर्नु अघि, तपाईंले यसबाट के चाहनुहुन्छ र कुन बजेट लगानी गर्न इच्छुक हुनुहुन्छ भनेर स्पष्ट रूपमा परिभाषित गर्न आवश्यक छ। यदि हामीले OpenSource को बारेमा बिर्स्यौं भने, त्यहाँ पहिले नै धेरै सेवाहरू र उत्पादनहरू छन् जसले तपाईंलाई जाँच गर्न, रूपान्तरण गर्न र प्रमाणीकरण गर्न मद्दत गर्नेछ। तर तिनीहरू महँगो छन्, र कहिलेकाहीँ धेरै महँगो। ठूला कम्पनीको लागि, त्यस्ता लागतहरू सहन योग्य छन्, तर स्टार्टअपको लागि तिनीहरू ठूलो बोझ हुन सक्छन्।

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

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

हाम्रो अनुभवको लागि, निम्न पोष्टहरूमा हामी हाम्रो RAML-Swagger वास्तुकलाको आधारमा हामी कुन स्थिर र गतिशील जाँचहरू सञ्चालन गर्छौं, साथै हामीले सम्झौताहरूबाट कुन कागजातहरू उत्पन्न गर्छौं, र यो सबै कसरी काम गर्छौं भन्ने बारे कुरा गर्नेछौं।

दर्ता भएका प्रयोगकर्ताहरूले मात्र सर्वेक्षणमा भाग लिन सक्छन्। साइन इन गर्नुहोस्कृपया

माइक्रोसेवा सम्झौताहरू एनोटेट गर्न तपाईं कुन भाषा प्रयोग गर्नुहुन्छ?

• RAML ०.८

• RAML ०.८

• स्वेगर ५

• OAS3 (उर्फ)

• खाका

• Другой

• प्रयोग नगर्ने

100 प्रयोगकर्ताहरूले मतदान गरे। २ प्रयोगकर्ताहरू रोकिए।

स्रोत: www.habr.com