मग ते RAML किंवा OAS (स्वॅगर) आहे का?

मायक्रोसर्व्हिसेसच्या डायनॅमिक जगात, काहीही बदलू शकते-कोणताही घटक वेगळ्या भाषेत, भिन्न फ्रेमवर्क आणि आर्किटेक्चर वापरून पुन्हा लिहिला जाऊ शकतो. केवळ कॉन्ट्रॅक्ट्स अपरिवर्तित राहिले पाहिजेत जेणेकरून मायक्रोसर्व्हिसशी काही कायमस्वरूपी बाहेरून संवाद साधता येईल, अंतर्गत रूपांतरांची पर्वा न करता. आणि आज आम्ही कराराचे वर्णन करण्यासाठी स्वरूप निवडण्याच्या आमच्या समस्येबद्दल बोलू आणि आम्हाला सापडलेल्या कलाकृती सामायिक करू.

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

सूक्ष्म सेवा. Acronis Cyber ​​Cloud विकसित करताना, आम्हाला समजले की आम्ही त्यांच्यापासून सुटू शकत नाही. आणि मायक्रोसर्व्हिस डिझाइन करणे करार औपचारिक केल्याशिवाय अशक्य आहे, जे मायक्रोसर्व्हिसच्या इंटरफेसचे प्रतिनिधित्व करते.

परंतु जेव्हा उत्पादनामध्ये एकापेक्षा जास्त घटक असतात आणि करार विकास हा एक नियमित क्रियाकलाप बनतो, तेव्हा तुम्ही प्रक्रिया ऑप्टिमायझेशनबद्दल विचार करण्यास मदत करू शकत नाही. हे स्पष्ट होते की इंटरफेस (करार) आणि अंमलबजावणी (मायक्रोसर्व्हिस) एकमेकांशी जुळणे आवश्यक आहे, भिन्न घटकांनी समान गोष्टी एकाच प्रकारे केल्या पाहिजेत आणि या सर्व निर्णयांचे केंद्रीकृत निर्णय न घेता, प्रत्येक संघाला सक्ती केली जाईल त्यांना मिळविण्यासाठी पुन्हा पुन्हा वेळ घालवा.

Amazon microservices आकृती कडून ट्विट वर्नर वोगेलिस, CTO Amazon
कोंडी काय आहे? खरं तर, मायक्रो सर्व्हिसेसशी संवाद साधण्याचे दोन मार्ग आहेत - HTTP रेस्ट आणि Google कडून gRPC. Google च्या तंत्रज्ञानाच्या स्टॅकमध्ये अडकू नये म्हणून आम्ही HTTP विश्रांती निवडली. HTTP REST कॉन्ट्रॅक्ट एनोटेशन्सचे वर्णन दोनपैकी एका फॉरमॅटमध्ये केले जाते: RAML आणि OAS, पूर्वी स्वॅगर म्हणून ओळखले जात होते. त्यामुळे, प्रत्येक डेव्हलपमेंट टीमला मानकांपैकी एक निवडण्याची गरज भासते. परंतु हे दिसून येते की ही निवड करणे खूप कठीण आहे.

भाष्ये का आवश्यक आहेत?

भाष्य आवश्यक आहे जेणेकरून बाह्य वापरकर्ता त्याच्या HTTP इंटरफेसद्वारे आपल्या सेवेसह काय केले जाऊ शकते हे सहजपणे शोधू शकेल. म्हणजेच, मूलभूत स्तरावर, भाष्यामध्ये उपलब्ध संसाधनांची किमान यादी, त्यांच्या HTTP पद्धती, विनंती संस्था, पॅरामीटर्सची सूची, आवश्यक आणि समर्थित शीर्षलेखांचे संकेत, तसेच रिटर्न कोड आणि प्रतिसाद स्वरूप असणे आवश्यक आहे. कॉन्ट्रॅक्ट एनोटेशनचा एक अत्यंत महत्वाचा घटक म्हणजे त्यांचे मौखिक वर्णन ("तुम्ही विनंतीमध्ये हे क्वेरी पॅरामीटर जोडल्यास काय होईल?", "कोणत्या परिस्थितीत कोड 400 परत केला जाईल?")

तथापि, जेव्हा मोठ्या संख्येने मायक्रोसर्व्हिसेस विकसित करण्याचा विचार येतो, तेव्हा तुम्हाला लिखित भाष्यांमधून अतिरिक्त मूल्य मिळवायचे आहे. उदाहरणार्थ, RAML/Swagger वर आधारित, तुम्ही मोठ्या संख्येने प्रोग्रामिंग भाषांमध्ये क्लायंट आणि सर्व्हर कोड तयार करू शकता. तुम्ही मायक्रोसर्व्हिससाठी दस्तऐवज स्वयंचलितपणे प्राप्त करू शकता आणि ते तुमच्या विकसक-पोर्टलवर अपलोड करू शकता :).

संरचित करार वर्णनाचे उदाहरण

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

शिवाय, केवळ कॉन्ट्रॅक्ट्सची उच्च-गुणवत्तेची अंमलबजावणीच नाही तर भाष्ये दृश्यमान करण्यासाठी साधने देखील मायक्रोसर्व्हिससह कार्य सुलभ करणे शक्य करते. म्हणजेच, जर आर्किटेक्टने कराराचे गुणात्मक वर्णन केले असेल तर, त्यावर आधारित, डिझाइनर आणि विकासक अतिरिक्त वेळेच्या खर्चाशिवाय इतर उत्पादनांमध्ये सेवा लागू करतील.

अतिरिक्त साधने सक्षम करण्यासाठी, RAML आणि OAS दोन्हीकडे मानकांद्वारे प्रदान केलेला मेटाडेटा जोडण्याची क्षमता आहे (उदाहरणार्थ, OAS मध्ये हे असे केले जाते).

सर्वसाधारणपणे, मायक्रोसर्व्हिसेससाठी करार वापरण्यात सर्जनशीलतेला वाव खूप मोठा आहे... किमान सिद्धांतानुसार.

हेज हॉगची सापाशी तुलना

सध्या, Acronis येथे प्राधान्य विकास क्षेत्र Acronis सायबर प्लॅटफॉर्मचा विकास आहे. ऍक्रोनिस सायबर प्लॅटफॉर्म हे ऍक्रोनिस सायबर क्लाउड आणि एजंट भागासह तृतीय-पक्ष सेवांच्या एकत्रीकरणाचे नवीन मुद्दे आहेत. आम्ही RAML मध्ये वर्णन केलेल्या आमच्या अंतर्गत API सह आनंदी असलो तरी, API प्रकाशित करण्याच्या गरजेने पुन्हा निवडीचा प्रश्न उपस्थित केला: आमच्या कामासाठी कोणते भाष्य मानक वापरणे चांगले आहे?

सुरुवातीला, असे वाटले की दोन उपाय आहेत - सर्वात सामान्य घडामोडी म्हणजे RAML आणि Swagger (किंवा OAS). परंतु प्रत्यक्षात असे दिसून आले की किमान 2 पर्याय नाहीत, परंतु 3 किंवा अधिक आहेत.

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

परंतु RAML चे विकसक, Mulesoft, विकसित होत असलेल्या ओपन एपीआय कन्सोर्टियममध्ये सामील झाले आहेत. स्वैगर. म्हणून, RAML ने त्याचा विकास स्थगित केला. इव्हेंटच्या स्वरूपाची कल्पना करण्यासाठी, कल्पना करा की मुख्य लिनक्स घटकांचे देखभाल करणारे मायक्रोसॉफ्टमध्ये काम करण्यासाठी सोडले आहेत. ही परिस्थिती स्वॅगर वापरण्यासाठी पूर्व-आवश्यकता निर्माण करते, जी गतिमानपणे विकसित होत आहे आणि नवीनतम - तिसऱ्या आवृत्तीमध्ये - लवचिकता आणि कार्यक्षमतेच्या बाबतीत व्यावहारिकपणे RAML सोबत मिळते.

एका गोष्टीसाठी नाही तर...

हे दिसून येते की, सर्व ओपन-सोर्स युटिलिटीज OAS 3.0 वर अपडेट केल्या गेल्या नाहीत. गो मधील मायक्रोसर्व्हिसेससाठी, सर्वात गंभीर गोष्ट म्हणजे अनुकूलन नसणे जाणे मानकाच्या नवीनतम आवृत्तीसाठी. तथापि, Swagger 2 आणि Swagger 3 मधील फरक आहे प्रचंड. उदाहरणार्थ, तिसऱ्या आवृत्तीमध्ये विकसक:

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

परिस्थिती मजेदार आहे: मानक निवडताना, आपल्याला RAML, Swagger 2 आणि Swagger 3 स्वतंत्र पर्याय म्हणून विचारात घेणे आवश्यक आहे. तथापि, फक्त Swagger 2 ला OpenSource साधनांसाठी चांगला सपोर्ट आहे. RAML खूप लवचिक आहे...आणि गुंतागुंतीचे आहे, आणि Swagger 3 ला समुदायाद्वारे असमाधानकारकपणे समर्थन दिले जाते, त्यामुळे तुम्हाला मालकीची साधने किंवा व्यावसायिक उपाय वापरावे लागतील, जे खूप महाग असतात.

शिवाय, स्वॅगरमध्ये अनेक छान वैशिष्ट्ये आहेत, जसे की रेडीमेड पोर्टल editor.swagger.io, ज्यावर तुम्ही भाष्य अपलोड करू शकता आणि तपशीलवार वर्णन, दुवे आणि कनेक्शनसह त्याचे व्हिज्युअलायझेशन मिळवू शकता, नंतर अधिक मूलभूत आणि कमी अनुकूल RAML साठी अशी कोणतीही संधी नाही. होय, तुम्ही GitHub वरील प्रकल्पांमध्ये काहीतरी शोधू शकता, तेथे एनालॉग शोधू शकता आणि ते स्वतः उपयोजित करू शकता. तथापि, कोणत्याही परिस्थितीत, एखाद्याला पोर्टलची देखभाल करावी लागेल, जे मूलभूत वापरासाठी किंवा चाचणी गरजांसाठी इतके सोयीचे नाही. याव्यतिरिक्त, स्वैगर अधिक "तत्वहीन" किंवा अधिक उदार आहे - ते कोडमधील टिप्पण्यांमधून व्युत्पन्न केले जाऊ शकते, जे अर्थातच, एपीआय प्रथम तत्त्वाच्या विरोधात जाते आणि कोणत्याही RAML युटिलिटीद्वारे समर्थित नाही.

एकेकाळी आम्ही RAML सह अधिक लवचिक भाषा म्हणून काम करण्यास सुरुवात केली आणि परिणामी आम्हाला बर्‍याच गोष्टी स्वतः कराव्या लागल्या. उदाहरणार्थ, प्रकल्पांपैकी एक युटिलिटी वापरते ramlfications युनिट चाचण्यांमध्ये, जे फक्त RAML 0.8 चे समर्थन करते. त्यामुळे आम्हाला क्रॅच जोडावे लागले जेणेकरून युटिलिटी RAML आवृत्ती 1.0 “खाऊ” शकेल.

तुम्हाला निवडण्याची गरज आहे का?

RAML साठी सोल्यूशन्सची इकोसिस्टम पूर्ण करण्यावर काम केल्यावर, आम्ही या निष्कर्षावर पोहोचलो की आम्हाला RAML चे स्वेगर 2 मध्ये रूपांतर करावे लागेल आणि त्यात सर्व ऑटोमेशन, पडताळणी, चाचणी आणि त्यानंतरचे ऑप्टिमायझेशन पार पाडावे लागेल. RAML ची लवचिकता आणि Swagger कडून कम्युनिटी टूलिंग सपोर्ट या दोन्हींचा फायदा घेण्याचा हा एक चांगला मार्ग आहे.

या समस्येचे निराकरण करण्यासाठी, दोन ओपनसोर्स साधने आहेत जी कॉन्ट्रॅक्ट रूपांतरण प्रदान करतात:

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

आणि आम्हाला आलेल्या सर्व अडचणी नाहीत. आमच्या पाइपलाइनमधील एक पायरी म्हणजे रेपॉजिटरीमधील RAML तपशीलाच्या तुलनेत बरोबर आहे याची पडताळणी करणे. आम्ही अनेक उपयुक्तता वापरून पाहिल्या. आश्चर्याची गोष्ट म्हणजे, त्या सर्वांनी वेगवेगळ्या ठिकाणी आणि पूर्णपणे भिन्न वाईट शब्दांसह आमच्या भाष्यांवर शपथ घेतली. आणि नेहमी मुद्द्यावर नाही :).

सरतेशेवटी, आम्ही आता कालबाह्य झालेल्या प्रकल्पावर स्थायिक झालो, ज्यामध्ये अनेक समस्या देखील आहेत (कधीकधी तो निळ्या रंगात क्रॅश होतो, नियमित अभिव्यक्तीसह काम करताना समस्या येतात). अशा प्रकारे, आम्हाला विनामूल्य साधनांच्या आधारे प्रमाणीकरण आणि रूपांतरणाच्या समस्या सोडवण्याचा मार्ग सापडला नाही आणि व्यावसायिक उपयुक्तता वापरण्याचा निर्णय घेतला. भविष्यात, OpenSource साधने अधिक परिपक्व होत असताना, ही समस्या सोडवणे सोपे होऊ शकते. दरम्यान, व्यावसायिक सेवेच्या किमतीपेक्षा “फिनिशिंग” साठी लागणारा श्रम आणि वेळ आम्हाला जास्त महत्त्वाचा वाटला.

निष्कर्ष

हे सर्व केल्यानंतर, आम्हाला आमचा अनुभव सामायिक करायचा होता आणि लक्षात घ्या की करारांचे वर्णन करण्यासाठी एखादे साधन निवडण्यापूर्वी, तुम्हाला त्यातून काय हवे आहे आणि तुम्ही कोणत्या बजेटमध्ये गुंतवणूक करण्यास इच्छुक आहात हे स्पष्टपणे परिभाषित करणे आवश्यक आहे. जर आम्ही OpenSource बद्दल विसरलो, तर आधीच मोठ्या संख्येने सेवा आणि उत्पादने आहेत जी तुम्हाला तपासण्यात, रूपांतरित करण्यात आणि प्रमाणित करण्यात मदत करतील. परंतु ते महाग असतात आणि कधीकधी खूप महाग असतात. मोठ्या कंपनीसाठी, असे खर्च सहन करण्यायोग्य असतात, परंतु स्टार्टअपसाठी ते एक मोठे ओझे बनू शकतात.

तुम्ही नंतर वापरणार असलेल्या साधनांचा संच ठरवा. उदाहरणार्थ, जर तुम्हाला फक्त एक करार प्रदर्शित करायचा असेल, तर स्वेगर 2 वापरणे सोपे होईल, ज्यात एक सुंदर API आहे, कारण RAML मध्ये तुम्हाला सेवा स्वतः तयार आणि देखरेख करावी लागेल.
तुमच्याकडे जितकी अधिक कार्ये असतील तितकी टूल्सची गरज अधिक असेल आणि ते वेगवेगळ्या प्लॅटफॉर्मसाठी भिन्न असतील आणि भविष्यात तुमचा खर्च कमी करणारी निवड करण्यासाठी उपलब्ध आवृत्त्यांशी त्वरित परिचित होणे चांगले आहे.

पण आज अस्तित्वात असलेल्या सर्व परिसंस्था अपूर्ण आहेत हे ओळखण्यासारखे आहे. म्हणूनच, जर कंपनीमध्ये असे चाहते असतील ज्यांना RAML मध्ये काम करायला आवडते कारण "हे तुम्हाला अधिक लवचिकपणे विचार व्यक्त करण्यास अनुमती देते" किंवा त्याउलट, स्वॅगरला प्राधान्य देतात कारण "ते स्पष्ट आहे," त्यांना कामावर सोडणे चांगले. ते काय आहेत ते त्यांना याची सवय आहे आणि ते हवे आहे, कारण कोणत्याही फॉरमॅटच्या साधनांना फाइलसह बदल आवश्यक आहेत.

आमच्या अनुभवाबद्दल, पुढील पोस्ट्समध्ये आम्ही आमच्या RAML-Swagger आर्किटेक्चरच्या आधारे आम्ही कोणती स्थिर आणि गतिमान तपासणी करतो, तसेच आम्ही करारांमधून कोणते दस्तऐवज तयार करतो आणि हे सर्व कसे कार्य करते याबद्दल बोलू.

केवळ नोंदणीकृत वापरकर्तेच सर्वेक्षणात भाग घेऊ शकतात. साइन इन करा, आपले स्वागत आहे.

मायक्रोसर्व्हिस कॉन्ट्रॅक्ट्सवर भाष्य करण्यासाठी तुम्ही कोणती भाषा वापरता?

• RAML 0.8

• RAML 1.0

• स्वैगर ५

• OAS3 (उर्फ)

• खाका

• इतर

• वापरत नाही

100 वापरकर्त्यांनी मतदान केले. 24 वापरकर्ते दूर राहिले.

स्त्रोत: www.habr.com