माइक्रोसर्विस अनुबंध के एनोटेशन के साथ क्या किया जा सकता है?

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



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

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

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

लंबे समय तक रहते हैं एपीआई गाइडलाइन!

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



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

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

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

• POST बेमतलब होगा या नहीं?
• हम किस त्रुटि कोड का उपयोग करते हैं और उनका क्या मतलब है?
• क्या मैं त्रुटि कोड में व्यावसायिक तर्क जोड़ सकता हूं?

अब कल्पना करें कि प्रत्येक टीम को व्यक्तिगत रूप से इन उत्तरों पर पहेली बनानी चाहिए।

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

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

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

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



बेशक, दिशानिर्देश एपीआई को अपनाने से सभी एपीआई स्वचालित रूप से संवैधानिक नहीं बन गए हैं। प्रत्येक API का विश्लेषण किया जाना था, प्रत्येक devlid को नई आवश्यकताओं को समझना था। इसलिए, हमने हमारे द्वारा विकसित की गई दिशानिर्देश एपीआई के खिलाफ रैमएल जांच का स्वचालन किया।
स्थैतिक विश्लेषण

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

पहले संस्करण में, हमने निम्नलिखित नियमों की पहचान की:

1. एपीआई विवरण के लिए जाँच करें। जैसा कि हमने अपने पिछले लेख में कहा था, आप एपीआई एनोटेशन के आधार पर सुंदर दस्तावेज बना सकते हैं। इसका मतलब है कि प्रत्येक संसाधन, क्वेरी पैरामीटर और प्रतिक्रिया में एक विवरण होना चाहिए जो हमारे एपीआई के किसी भी उपयोगकर्ता को सभी आवश्यक जानकारी देगा। यह एक तिपहिया प्रतीत होगा, लेकिन डेवलपर्स को दिखाना कितना आसान है कि उनका एनोटेशन विवरणों में समृद्ध नहीं है!
2. उदाहरणों की उपस्थिति और शुद्धता के लिए जाँच करना। एपीआई एनोटेशन भाषाएँ भी आपको उदाहरणों का वर्णन करने की अनुमति देती हैं। उदाहरण के लिए, प्रतिक्रिया में हम वास्तविक सेवा प्रतिक्रिया का एक उदाहरण जोड़ सकते हैं, वास्तविक जीवन से कुछ। उदाहरणों का उपयोग करना बताता है कि एंडपॉइंट का उपयोग कैसे किया जाना चाहिए और काम करना चाहिए, और हम एनोटेशन के स्थैतिक विश्लेषण के माध्यम से उदाहरणों की जांच करते हैं।
3. HTTP प्रतिक्रिया कोड की वैधता। HTTP मानक बड़ी संख्या में कोड परिभाषित करता है, लेकिन उनकी व्याख्या अलग-अलग तरीकों से की जा सकती है। हमारी दिशानिर्देश कोड के उपयोग को औपचारिक बनाता है। हम HTTP विधि के अनुसार विभिन्न कोड की प्रयोज्यता को भी सीमित करते हैं। उदाहरण के लिए, HTTP विनिर्देशन के अनुसार, कोड 201, संसाधन निर्मित होने पर वापस आ जाता है। इसलिए, जीईटी रिटर्निंग 201 एक वेक-अप कॉल होगी (या तो कोड का गलत तरीके से उपयोग किया जाता है, या जीईटी संसाधन बनाता है)। इसलिए, हमारी दिशानिर्देश API ऐसे उपयोग को प्रतिबंधित करती है। इसके अलावा, आर्किटेक्ट्स ने प्रत्येक विधि के लिए कोड के सेट निर्धारित किए हैं, और अब हम एनोटेशन के स्तर पर उन्हें स्थिर मोड में जांचते हैं।
4. HTTP तरीकों की जाँच। हर कोई जानता है कि HTTP प्रोटोकॉल में मानक विधियों (GET, POST, PUT, आदि) का एक सेट है, और यह कस्टम तरीकों का उपयोग करना भी संभव बनाता है। हमारी दिशानिर्देश एपीआई अनुमत विधियों का वर्णन करती है जो अनुमत हैं, लेकिन अवांछनीय (विकल्प), साथ ही पूरी तरह से निषिद्ध हैं (इसका उपयोग केवल आर्किटेक्ट के आशीर्वाद के साथ किया जा सकता है)। निषिद्ध में मानक HEAD विधि, साथ ही किसी भी कस्टम तरीके शामिल हैं। यह सब अनुबंधों के एनोटेशन में सत्यापित करना भी आसान है।
5. पहुंच अधिकारों का सत्यापन। हमें उम्मीद है कि 2019 में प्राधिकरण समर्थन की आवश्यकता के लिए अतिरिक्त स्पष्टीकरण की आवश्यकता नहीं है। अच्छा प्रलेखन में यह जानकारी होनी चाहिए कि एपीआई किस भूमिका का समर्थन करता है और प्रत्येक भूमिका के लिए कौन से एपीआई तरीके उपलब्ध हैं। एनोटेशन स्तर पर रिकॉर्ड किए गए रोल मॉडल के बारे में जानकारी का दस्तावेजीकरण करने के अलावा, आप डायनामिक्स में बहुत अधिक दिलचस्प चीजें करने की अनुमति देते हैं, हालांकि, हम अगले लेख में इस बारे में बात करेंगे।
6. नामकरण की मान्यता। नामकरण संस्थाओं के लिए विभिन्न तरीकों का उपयोग करने से सिरदर्द से राहत मिलती है। सामान्य तौर पर, दो "शिविर" होते हैं - CamelCase के समर्थक और snake_case.Camelcase - जब प्रत्येक शब्द एक बड़े अक्षर से शुरू होता है, और snake_case - जब शब्दों को अंडरस्कोर द्वारा अलग किया जाता है और सब कुछ छोटे अक्षरों में लिखा जाता है। विभिन्न भाषाओं में, अलग-अलग तरीकों से नाम देने का रिवाज है। उदाहरण के लिए, Python में snake_case स्वीकार किया जाता है, और CamelCase को Go या Java में अपनाया जाता है। हमने सभी परियोजनाओं के लिए अपनी पसंद को सार्वभौमिक बनाया और एपीआई गाइडलाइन में तय किया। इसलिए, एनोटेशन के माध्यम से, हम संसाधनों और मापदंडों के नामों को सांख्यिकीय रूप से जांचते हैं;
7. कस्टम हेडर की मान्यता। यह नामकरण जांच का एक और उदाहरण है, लेकिन यह विशेष रूप से प्रमुखों से जुड़ा हुआ है। हम पर Acronis में यह एक्स-कस्टम-हैडर-नाम के प्रारूप का उपयोग करने के लिए प्रथागत है (इस तथ्य के बावजूद कि यह प्रारूप पदावनत है)। और हम एनोटेशन के स्तर पर इसके अनुपालन को नियंत्रित करते हैं।
8. HTTPS समर्थन सत्यापित करें। किसी भी आधुनिक सेवा को HTTPS का समर्थन करना चाहिए, और कुछ का मानना ​​है कि इन दिनों HTTP के साथ काम करना आम तौर पर बुरी खबर है। इसलिए, RAML या स्वैगर एनोटेशन को इंगित किया जाना चाहिए। कि माइक्रोसैट HTTP के बिना HTTPS का समर्थन करता है।
9. URI की संरचना की जाँच करें। प्रागैतिहासिक काल में, अर्थात्, दिशानिर्देश API जारी करने से पहले, अनुरोध URI अलग-अलग सेवाओं में अलग दिखता था: कहीं / एपीआई / 2, कहीं / एपीआई / सर्विस_नाम / वी 2, और इसी तरह। अब हमारे दिशानिर्देश में हमारे सभी API के लिए एक मानक URI संरचना परिभाषित की गई है। मैनुअल वर्णन करता है कि उन्हें कैसे दिखना चाहिए ताकि भ्रम पैदा न हो।
10. नए संस्करणों की अनुकूलता की जाँच करना। एक और पहलू जो किसी भी एपीआई लेखक को ध्यान में रखना चाहिए वह है पिछड़ी संगतता। यह देखना महत्वपूर्ण है कि पुराने एपीआई के आधार पर बनाया गया कोड नए संस्करण के साथ काम कर सकता है या नहीं। इस परिवर्तन के आधार पर दो श्रेणियों में विभाजित किया जा सकता है: पीछे की संगतता और संगत को तोड़ना। हर कोई जानता है कि ब्रेकिंग परिवर्तन अस्वीकार्य हैं, और यदि आप कुछ नाटकीय रूप से "सुधार" करना चाहते हैं, तो डेवलपर को एपीआई का एक नया संस्करण जारी करना चाहिए। लेकिन हर कोई गलत हो सकता है, इसलिए स्थैतिक जांच के चरण में हमारा दूसरा लक्ष्य केवल संगत परिवर्तन छोड़ना और असंगत लोगों को शपथ दिलाना है। यह माना जाता है कि कोड की तरह एनोटेशन, भंडार में संग्रहीत किया जाता है और इसलिए, इसमें परिवर्तनों का पूरा इतिहास है। इसलिए, हम पिछड़े संगतता के लिए अपने HTTP REST की जाँच कर सकते हैं। उदाहरण के लिए, (विधि, पैरामीटर, प्रतिक्रिया कोड) संगतता के उल्लंघन का उल्लंघन नहीं करता है, और हटाने से संगतता का नुकसान हो सकता है। और यह पहले से ही एनोटेशन के स्तर पर जांचा जा सकता है।

जब कोई वर्णन नहीं हैं

जब वर्णन होते हैं

निष्कर्ष

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

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