🧖 🧐 ↩️ सार्वजनिक अनुबंध, उनकी स्थिरता कैसे सुनिश्चित करें 🧑🏽‍🤝‍🧑🏼 🥫 🎛️

क्या आपके सिस्टम में कई परस्पर सेवाएं शामिल हैं?
सार्वजनिक API बदलते समय सेवा कोड को मैन्युअल रूप से अपडेट करें?
आपकी सेवाओं में परिवर्तन अक्सर दूसरों के काम को कम करते हैं, और अन्य डेवलपर्स आपको इसके लिए नफरत करते हैं?

यदि आपने कम से कम एक बार हाँ में उत्तर दिया है, तो आपका स्वागत है!

शर्तें

सार्वजनिक अनुबंध, विनिर्देश - सार्वजनिक इंटरफेस जिसके माध्यम से आप सेवा के साथ बातचीत कर सकते हैं। पाठ में उनका वही अर्थ है।

यह लेख किस बारे में है

कॉन्ट्रैक्ट और ऑटोमैटिक कोड जनरेशन के यूनिफाइड डिस्क्रिप्शन के लिए टूल्स का इस्तेमाल कर डेवलप की गई वेब सर्विसेज को कम करना सीखें।

नीचे वर्णित तकनीकों और उपकरणों का उचित उपयोग आपको नई सुविधाओं को जल्दी से रोल आउट करने और पुराने को तोड़ने की अनुमति नहीं देगा।

समस्या क्या दिखती है?

एक प्रणाली है जिसमें कई सेवाएं शामिल हैं। इन सेवाओं को विभिन्न टीमों को सौंपा गया है।

उपभोक्ता सेवाएं सेवा प्रदाता पर निर्भर करती हैं।
सिस्टम विकसित होता है, और एक दिन सेवा प्रदाता अपने सार्वजनिक अनुबंधों को बदलता है।

यदि उपभोक्ता सेवाएं परिवर्तन के लिए तैयार नहीं हैं, तो सिस्टम पूरी तरह से काम करना बंद कर देता है।

इस समस्या को हल कैसे करें

आपूर्तिकर्ता सेवा टीम सब कुछ ठीक कर देगी

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

उपभोक्ता टीम को अपनी सेवा का कोड अपडेट करें

अन्य लोग क्यों टूट रहे हैं, लेकिन क्या हम मरम्मत कर रहे हैं?

हालांकि, मुख्य सवाल यह है कि आपकी सेवा को कैसे ठीक किया जाए, अब अनुबंध कैसा दिखता है? आपको नया प्रदाता सेवा कोड सीखने या उनकी टीम से संपर्क करने की आवश्यकता है। हम कोड का अध्ययन करने और किसी अन्य टीम के साथ बातचीत करने में समय बिताते हैं।

सोचें कि समस्या को प्रकट होने से रोकने के लिए क्या करना चाहिए

लंबे समय में सबसे उचित विकल्प। अगले भाग में इस पर विचार करें।

किसी समस्या की अभिव्यक्ति को कैसे रोका जाए

सॉफ्टवेयर विकास के जीवन चक्र को तीन चरणों में दर्शाया जा सकता है: डिजाइन, कार्यान्वयन और परीक्षण।

निम्न में से प्रत्येक चरण को विस्तारित करने की आवश्यकता है:

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

प्रत्येक चरण को हमारी समस्या के उदाहरण के रूप में आगे समझाया गया है।

समस्या हमारे साथ कैसे दिखती है

यह हमारा पारिस्थितिकी तंत्र जैसा दिखता है।
मंडलियां सेवाएं हैं, और तीर उनके बीच संचार चैनल हैं।

फ्रंटेंड एक वेब-आधारित क्लाइंट एप्लिकेशन है।

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

क्या इस सेवा को अपने अनुबंधों को बदलना चाहिए, सिस्टम तुरंत काम करना बंद कर देगा।

हमारे सिस्टम के स्रोत मुख्य रूप से सी # में लिखे गए हैं, लेकिन गो और पायथन में भी सेवाएं हैं। इस संदर्भ में, इससे कोई फर्क नहीं पड़ता कि आंकड़े में अन्य सेवाएं क्या करती हैं।

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

मैं ऑटोमैटिक की ओर मैन्युअल अपडेट से दूर होना चाहूंगा। यह उस दर को बढ़ाने में मदद करेगा जिस पर ग्राहक कोड बदलता है और त्रुटियों को कम करता है। URL में त्रुटियां टाइपोस हैं, लापरवाही के कारण त्रुटियां, आदि।

हालाँकि, यह दृष्टिकोण क्लाइंट व्यवसाय तर्क में त्रुटियों को ठीक नहीं करता है। आप इसे केवल मैन्युअल रूप से समायोजित कर सकते हैं।

समस्या से कार्य तक

हमारे मामले में, क्लाइंट कोड की स्वचालित पीढ़ी को लागू करना आवश्यक है ।
ऐसा करने में, निम्नलिखित पर विचार किया जाना चाहिए:

सर्वर साइड - नियंत्रक पहले से ही लिखे गए हैं;
ब्राउज़र सेवा का एक ग्राहक है;
सेवाएं HTTP पर संचार करती हैं।
जनरेशन को ट्यून करना होगा। उदाहरण के लिए, JWT का समर्थन करना।

प्रशन

समस्या को हल करने के दौरान, सवाल उठे:

कौन सा उपकरण चुनना है;
अनुबंध कैसे प्राप्त करें;
ठेके कहां रखें;
ग्राहक कोड कहां रखा जाए;
किस पीढ़ी को करना है।

इन सवालों के जवाब निम्नलिखित हैं।

कौन सा टूल चुनना है

अनुबंध के साथ काम करने के लिए उपकरण दो दिशाओं में प्रस्तुत किए जाते हैं - आरपीसी और आरईएसटी।

RPC को केवल एक दूरस्थ कॉल के रूप में समझा जा सकता है, जबकि REST को HTTP क्रिया और URL के लिए अतिरिक्त शर्तों की आवश्यकता होती है।

आरपीसी और आरईएसटी कॉल में अंतर यहां प्रस्तुत किया गया है।

आरपीसी - दूरस्थ प्रक्रिया कॉल		REST Representational State Transfer
		, HTTP- URL
	Restaurant:8080/Orders/PlaceOrder	POST	Restaurant:8080/Orders
	Restaurant:8080/Orders/GetOrder?OrderNumber=1	GET	Restaurant:8080/Orders/1
	Restaurant:8080/Orders/UpdateOrder	PUT	Restaurant:8080/Orders/1

उपकरण

तालिका REST और RPC के साथ काम करने के लिए उपकरणों की तुलना दर्शाती है।

गुण	Openapi	WSDL	किफ़ायत	gRPC
एक प्रकार	आराम		RPC
मंच	निर्भर नहीं करता है
जुबान	निर्भर नहीं करता है
विकास क्रम *	कोड पहले, कल्पना पहले	कोड पहले, कल्पना पहले	पहले कल्पना	कोड पहले, कल्पना पहले
परिवहन प्रोटोकॉल	HTTP / 1.1	कोई भी (HTTP की आवश्यकता है)	अपना	HTTP / 2
राय	विनिर्देश		ढांचा
टिप्पणी	कम प्रवेश सीमा, बहुत सारे दस्तावेज	XML अतिरेक, SOAP, आदि।	उच्च प्रवेश सीमा, थोड़ा प्रलेखन	औसत प्रवेश सीमा, बेहतर प्रलेखन

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

विशेष पहले - पहले हम अनुबंधों को परिभाषित करते हैं, फिर हमें क्लाइंट का हिस्सा और उनसे सर्वर का हिस्सा मिलता है। यह विकास की शुरुआत में सुविधाजनक है जब अभी तक कोई कोड नहीं है। इसकी अतिरेक के कारण WSDL

आउटपुट

उपयुक्त नहीं है।

अपाचे थ्रिफ्ट बहुत ही आकर्षक है और सीखना मुश्किल है।

जीआरपीसी को नेट कोर 3.0 और नेट स्टैंडर्ड 2.1 की आवश्यकता होती है। विश्लेषण के समय, शुद्ध कोर 2.2 और शुद्ध मानक 2.0 का उपयोग किया गया था। बॉक्स से बाहर ब्राउज़र में कोई जीआरपीसी समर्थन नहीं है, एक अतिरिक्त समाधान की आवश्यकता है। जीआरपीसी प्रोटोबॉफ और एचटीटीपी / 2 बाइनरी सीरियलाइजेशन का उपयोग करता है। इस वजह से, एपीआई जैसे पोस्टमैन, आदि के परीक्षण के लिए उपयोगिताओं की सीमा संकीर्ण हो रही है। कुछ JMeter के माध्यम से लोड परीक्षण को अतिरिक्त प्रयास की आवश्यकता हो सकती है। उपयुक्त नहीं है, जीआरपीसी में स्विच करने के लिए बहुत सारे संसाधनों की आवश्यकता होती है।

OpenAPI को अतिरिक्त अपडेट की आवश्यकता नहीं है। यह REST और इस विनिर्देशन के साथ काम करने वाले उपकरणों की बहुतायत को दर्शाता है। हम इसका चयन करते हैं।

OpenAPI के साथ काम करने के लिए उपकरण

तालिका OpenAPI के साथ काम करने के लिए उपकरणों की तुलना दिखाती है।

उपकरण	swashbuckle	NSwag	Openapitools
समर्थित विशिष्टता संस्करण	OpenApi v2, v3 प्रारूप में विनिर्देश उत्पन्न कर सकते हैं
कोड पहला समर्थन	वहाँ है	वहाँ है	नहीं
समर्थित सर्वर भाषाएँ	नहीं	सी #	बहुत सारा
समर्थित ग्राहक भाषाएँ	नहीं	C #, टाइपस्क्रिप्ट, AngularJS, कोणीय (v2 +), window.fetch API	बहुत सारा
जनरेशन सेटिंग्स	नहीं	वहाँ है	वहाँ है
राय	नगेट पैकेज	Nuget पैकेज + अलग उपयोगिता	अलग उपयोगिता

Swashbuckle का निष्कर्ष उपयुक्त नहीं है, क्योंकि आपको केवल विनिर्देश प्राप्त करने की अनुमति देता है। क्लाइंट कोड जनरेट करने के लिए, आपको एक अतिरिक्त समाधान का उपयोग करने की आवश्यकता है।

OpenApiTools सेटिंग्स का एक गुच्छा के साथ एक दिलचस्प उपकरण है, लेकिन यह पहले कोड का समर्थन नहीं करता है। इसका लाभ कई भाषाओं में सर्वर कोड उत्पन्न करने की क्षमता है।

NSwag सुविधाजनक है कि यह एक Nuget पैकेज है। प्रोजेक्ट बनाते समय कनेक्ट करना आसान है। हमारी ज़रूरत की हर चीज़ का समर्थन करता है: c # में कोड का पहला दृष्टिकोण और पीढ़ी कोड। हम इसका चयन करते हैं।

ठेके की व्यवस्था कहां से करें। अनुबंधों तक सेवाओं का उपयोग कैसे करें

अनुबंध भंडारण के आयोजन के लिए समाधान यहां दिए गए हैं। समाधान बढ़ती जटिलता के क्रम में सूचीबद्ध हैं।

प्रदाता सेवा परियोजना फ़ोल्डर सबसे आसान विकल्प है। यदि आपको दृष्टिकोण में चलाने की आवश्यकता है, तो इसे चुनें।
एक साझा फ़ोल्डर एक वैध विकल्प है यदि वांछित परियोजनाएं समान भंडार में हैं। लंबे समय में, फ़ोल्डर में अनुबंधों की अखंडता को बनाए रखना मुश्किल होगा। इसके लिए अनुबंधों के विभिन्न संस्करणों आदि के लिए अतिरिक्त टूल की आवश्यकता हो सकती है।
विनिर्देशों के लिए अलग रिपॉजिटरी - यदि प्रोजेक्ट अलग-अलग रिपॉजिटरी में हैं, तो अनुबंधों को एक सार्वजनिक स्थान पर रखा जाना चाहिए। नुकसान साझा किए गए फ़ोल्डर के समान हैं।
सेवा एपीआई (swagger.ui, swaggerhub) के माध्यम से - एक अलग सेवा जो विनिर्देश प्रबंधन से संबंधित है।

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

आप किस बिंदु पर उत्पन्न होते हैं

अब आपको यह तय करने की आवश्यकता है कि कोड जनरेशन को किस बिंदु पर करना है।
यदि अनुबंध साझा किए जाते हैं, तो उपभोक्ता सेवाएं अनुबंध प्राप्त कर सकती हैं और यदि आवश्यक हो तो कोड स्वयं उत्पन्न कर सकती हैं।

हमने सेवा प्रदाता परियोजना के साथ फ़ोल्डर में अनुबंध रखने का फैसला किया। इसका मतलब है कि आपूर्तिकर्ता सेवा परियोजना की विधानसभा के बाद ही पीढ़ी का निर्माण किया जा सकता है।

क्लाइंट कोड कहां रखें

ग्राहक कोड अनुबंध द्वारा उत्पन्न किया जाएगा। यह पता लगाना बाकी है कि इसे कहां रखा जाए।
ऐसा लगता है कि क्लाइंट कोड को एक अलग StorageServiceClientProxy प्रोजेक्ट में रखना एक अच्छा विचार है। प्रत्येक परियोजना इस विधानसभा को जोड़ने में सक्षम होगी।

इस समाधान के लाभ:

ग्राहक कोड अपनी सेवा के करीब है और लगातार अद्यतित है;
उपभोक्ता एक रिपॉजिटरी के भीतर परियोजना के लिंक का उपयोग कर सकते हैं।

नुकसान:

काम नहीं करेगा यदि आपको सिस्टम के किसी अन्य भाग में क्लाइंट उत्पन्न करने की आवश्यकता है, उदाहरण के लिए, एक अलग रिपॉजिटरी। यह अनुबंध के लिए कम से कम एक साझा फ़ोल्डर का उपयोग करके हल किया गया है;
उपभोक्ताओं को उसी भाषा में लिखा जाना चाहिए। यदि आपको किसी अन्य भाषा में क्लाइंट की आवश्यकता है, तो आपको OpenApiTools का उपयोग करने की आवश्यकता है।

हम NSwag उपवास करते हैं

नियंत्रक विशेषताएँ

NSwag को यह बताने की आवश्यकता है कि हमारे नियंत्रकों के लिए सही विनिर्देश कैसे उत्पन्न करें।

ऐसा करने के लिए, आपको विशेषताओं को व्यवस्थित करने की आवश्यकता है।

[Microsoft.AspNetCore.Mvc.Routing.Route("[controller]")]  //  url
[Microsoft.AspNetCore.Mvc.ApiController] //     
public class DescriptionController : ControllerBase {
[NSwag.Annotations.OpenApiOperation("GetDescription")] //    
[Microsoft.AspNetCore.Mvc.ProducesResponseType(typeof(ConversionDescription), 200)] //    200  
[Microsoft.AspNetCore.Mvc.ProducesResponseType(401)] //    401
[Microsoft.AspNetCore.Mvc.ProducesResponseType(403)] //    403
[Microsoft.AspNetCore.Mvc.HttpGet("{pluginName}/{binaryDataId}")] //  url
public ActionResult<ConversionDescription> GetDescription(string pluginName, Guid binaryDataId) { 
 // ... 
}

डिफ़ॉल्ट रूप से, NSwag MIME टाइप एप्लिकेशन / ऑक्टेट-स्ट्रीम के लिए सही स्पेसिफिकेशन उत्पन्न नहीं कर सकता है। उदाहरण के लिए, यह तब हो सकता है जब फ़ाइलें स्थानांतरित की जाती हैं। इसे ठीक करने के लिए, आपको विनिर्देश बनाने के लिए अपनी विशेषता और प्रोसेसर लिखना होगा।

[Microsoft.AspNetCore.Mvc.Route("[controller]")]
[Microsoft.AspNetCore.Mvc.ApiController]
public class FileController : ControllerBase {
[NSwag.Annotations.OpenApiOperation("SaveFile")]
[Microsoft.AspNetCore.Mvc.ProducesResponseType(401)]
[Microsoft.AspNetCore.Mvc.ProducesResponseType(403)]
[Microsoft.AspNetCore.Mvc.HttpPost("{pluginName}/{binaryDataId}/{fileName}")]
[OurNamespace.FileUploadOperation] //  
public async Task SaveFile() { // ... }

फ़ाइल संचालन के लिए विनिर्देशों को बनाने के लिए प्रोसेसर

विचार यह है कि आप इस विशेषता को संभालने के लिए अपनी विशेषता और प्रोसेसर लिख सकते हैं।

हम नियंत्रक पर विशेषता लटकाते हैं, और जब NSwag इसे पूरा करता है, तो यह हमारे प्रोसेसर का उपयोग करके इसे संसाधित करेगा।

इसे लागू करने के लिए, NSwag OpenApiOperationProcessorAttribute और IOperationProcessor कक्षाएं प्रदान करता है।

हमारी परियोजना में, हमने अपना उत्तराधिकारी बनाया:

FileUploadOperationAttribute: OpenApiOperationProcessorAttribute
FileUploadOperationProcessor: IOperationProcessor

प्रोसेसर के उपयोग के बारे में यहाँ और पढ़ें।

कल्पना और कोड पीढ़ी के लिए NSwag कॉन्फ़िगरेशन

विन्यास में 3 मुख्य खंड:

रनटाइम - निर्दिष्ट करता है। नेट रनटाइम। उदाहरण के लिए, NetCore22;
documentGenerator - एक विनिर्देशन उत्पन्न करने का वर्णन करता है;
codeGenerators - विनिर्देश के अनुसार कोड उत्पन्न करने के तरीके को परिभाषित करता है।

NSwag में सेटिंग्स का एक गुच्छा होता है, जो पहले भ्रमित करता है।

सुविधा के लिए, आप NSwag Studio का उपयोग कर सकते हैं। इसका उपयोग करके, आप वास्तविक समय में देख सकते हैं कि विभिन्न सेटिंग्स कोड पीढ़ी या विनिर्देशों के परिणाम को कैसे प्रभावित करती हैं। उसके बाद, मैन्युअल रूप से कॉन्फ़िगरेशन फ़ाइल में चयनित सेटिंग्स का चयन करें।

कॉन्फिग सेटिंग्स के बारे में यहाँ पढ़ें

सर्विस प्रोवाइडर के प्रोजेक्ट को असेम्बल करने पर हम स्पेसिफिकेशन और क्लाइंट कोड जनरेट करते हैं

ताकि सेवा प्रदाता परियोजना की विधानसभा के बाद, विनिर्देश और कोड उत्पन्न हो, निम्नलिखित करें:

हमने क्लाइंट के लिए एक वेबएपी प्रोजेक्ट बनाया।
हमने Nswag CLI - Nswag.json (पिछले भाग में वर्णित) के लिए एक विन्यास लिखा था।
हमने csproj सर्विस प्रोवाइडर प्रोजेक्ट के अंदर PostBuild Target लिखा है।

<Target Name="GenerateWebApiProxyClient“ AfterTargets="PostBuildEvent">
<Exec Command="$(NSwagExe_Core22) run nswag.json”/>

$ (NSwagExe_Core22) nswag.json चलाते हैं - nswag.json कॉन्फ़िगरेशन के साथ NSWag उपयोगिता को .bet runtetine netCore 2.2 पर चलाते हैं।

लक्ष्य निम्न कार्य करता है:

NSwag एक विक्रेता सेवा असेंबली से एक विनिर्देश बनाता है।
NSwag स्पेसिफिकेशन के अनुसार क्लाइंट कोड जेनरेट करता है।

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

NSwag आपको सॉफ्टवेयर एपीआई के माध्यम से विनिर्देश / कोड पीढ़ी को अनुकूलित करने की अनुमति देता है।

JWT के लिए समर्थन कैसे जोड़ें

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

यहाँ जेडब्ल्यूटी बारे में अधिक जानकारी jwt.io ।

कार्य निवर्तमान HTTP अनुरोध के हेडर को संशोधित करने की आवश्यकता के लिए उबालता है।
ऐसा करने के लिए, NSwag कोड जनरेटर एक विस्तार बिंदु उत्पन्न कर सकता है - CreateHttpRequestMessageAsync विधि। इस विधि के अंदर भेजने से पहले HTTP अनुरोध तक पहुँच है।

कोड उदाहरण

protected Task<HttpRequestMessage> CreateHttpRequestMessageAsync(CancellationToken cancellationToken) {
      var message = new HttpRequestMessage();

      if (!string.IsNullOrWhiteSpace(this.AuthorizationToken)) {
        message.Headers.Authorization =
          new System.Net.Http.Headers.AuthenticationHeaderValue(BearerScheme, this.AuthorizationToken);
      }

      return Task.FromResult(message);
    }

निष्कर्ष

हमने OpenAPI के साथ विकल्प चुना, क्योंकि इसे लागू करना आसान है, और इस विनिर्देश के साथ काम करने के लिए उपकरण अत्यधिक विकसित हैं।

OpenAPI और GRPC पर निष्कर्ष:

OpenAPI

विनिर्देश क्रिया है;
, ;
;
.

GRPC

, URL, HTTP ..;
OpenAPI;
;
;
HTTP/2.

इस प्रकार, हमें नियंत्रकों के पहले से ही लिखित कोड के आधार पर एक विनिर्देश प्राप्त हुआ। ऐसा करने के लिए, नियंत्रकों पर विशेष विशेषताओं को लटका देना आवश्यक था।

फिर, प्राप्त विनिर्देश के आधार पर, हमने ग्राहक कोड की पीढ़ी को लागू किया। अब हमें क्लाइंट कोड को मैन्युअल रूप से अपडेट करने की आवश्यकता नहीं है।

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

सार्वजनिक अनुबंधों का संस्करण

सार्वजनिक अनुबंधों का संस्करण क्यों?

सेवा प्रदाताओं में परिवर्तन के बाद, पूरी प्रणाली एक सुसंगत, परिचालन स्थिति में रहना चाहिए।

सार्वजनिक एपीआई में परिवर्तन को टाला जाना चाहिए ताकि ग्राहकों को न तोड़ा जा सके।

समाधान के विकल्प

सार्वजनिक अनुबंधों के संस्करण के बिना

सेवा प्रदाता टीम स्वयं उपभोक्ता सेवाओं को ठीक करती है।

यदि सेवा प्रदाता टीम के पास उपभोक्ता सेवा रिपॉजिटरी तक पहुंच नहीं है या कमियों का अभाव है तो यह दृष्टिकोण काम नहीं करेगा। यदि ऐसी कोई समस्या नहीं है, तो आप बिना संस्करण के कर सकते हैं।

सार्वजनिक अनुबंधों के संस्करण का उपयोग करें

सेवा प्रदाता टीम अनुबंधों के पिछले संस्करण को छोड़ देती है।

इस दृष्टिकोण में पिछले एक की कमियां नहीं हैं, लेकिन अन्य कठिनाइयों को जोड़ता है।
आपको निम्नलिखित पर निर्णय लेने की आवश्यकता है:

किस उपकरण का उपयोग करना है;
जब एक नया संस्करण शुरू करने के लिए;
कब तक पुराने संस्करणों को बनाए रखने के लिए।

किस उपकरण का उपयोग करें

तालिका में OpeanAPI और जीआरपीसी के संस्करण के साथ जुड़ी सुविधाओं को दिखाया गया है।

	gRPC	Openapi
संस्करण विशेषता	प्रोटोबुफ़ स्तर पर, एक विशेषता पैकेज [packageName] है। [संस्करण]	विनिर्देश स्तर पर, बेसपाथ (URL के लिए) और संस्करण विशेषताएँ हैं
तरीकों के लिए पदावनत विशेषता	हां, लेकिन C # के तहत कोड जनरेटर द्वारा ध्यान नहीं दिया गया	हां, इसे अप्रचलित के रूप में चिह्नित किया गया है । NSwag पहले कोड के साथ समर्थित नहीं है, आपको अपना प्रोसेसर लिखने की आवश्यकता है
मापदंडों के लिए पदावनत विशेषता	अप्रचलित के रूप में चिह्नित है	हां, इसे अप्रचलित के रूप में चिह्नित किया गया है । NSwag पहले कोड के साथ समर्थित नहीं है, आपको अपना प्रोसेसर लिखने की आवश्यकता है

पदावनत का अर्थ है कि यह एपीआई अब उपयोग करने लायक नहीं है।

दोनों उपकरण संस्करण का समर्थन करते हैं और डिप्रेक्टेड विशेषताएँ।

यदि आप OpenAPI और कोड पहले दृष्टिकोण का उपयोग करते हैं, तो फिर से आपको सही विनिर्देश बनाने के लिए प्रोसेसर लिखने की आवश्यकता होती है।

एक नए संस्करण को कब पेश किया जाए

नए संस्करण को पेश किया जाना चाहिए जब अनुबंधों में परिवर्तन पिछड़े संगतता को संरक्षित नहीं करते हैं।

अनुबंध के नए और पुराने संस्करणों के बीच परिवर्तन को उल्लंघन करने वाली संगतता को कैसे सत्यापित करें?

OpenAPI के लिए 2 विशिष्टताओं github.com/Azure/openapi-diff के बीच संगतता की जाँच करने के लिए एक Azure opeanapi-diff उपकरण है ;
जीआरपीसी के लिए कोई स्वचालित उपकरण नहीं मिला, केवल संस्करण नीतियां हैं;
सामान्य github.com/grpc/grpc/blob/master/doc/versioning.md;
under .Net docs.microsoft.com/en-us/aspnet/core/grpc/versioning?view=aspnetcore-3.1 ।

संस्करणों को बनाए रखने के लिए कब तक

इस सवाल का कोई सही जवाब नहीं है।

पुराने संस्करण के लिए समर्थन को हटाने के लिए, आपको यह जानना होगा कि आपकी सेवा का उपयोग कौन करता है।

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

तो इस स्थिति में क्या किया जा सकता है?

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

इस स्थिति में एकमात्र सलाह सार्वजनिक अनुबंधों पर अधिक ध्यान देना है ताकि उनके परिवर्तनों की आवृत्ति को कम किया जा सके।

यदि सार्वजनिक अनुबंध एक बंद प्रणाली में उपयोग किए जाते हैं, तो आप सीडीसी दृष्टिकोण का उपयोग कर सकते हैं। इसलिए हम पता लगा सकते हैं कि ग्राहकों ने सॉफ्टवेयर के पुराने संस्करणों का उपयोग कब बंद कर दिया। उसके बाद, आप पुराने संस्करण का समर्थन हटा सकते हैं।

निष्कर्ष

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

परीक्षण अनुबंध और सीडीसी

इस खंड को अलौकिक रूप से प्रकाशित किया गया है, जैसा कि इस दृष्टिकोण के कार्यान्वयन के लिए कोई गंभीर शर्त नहीं हैं।

उपभोक्ता संचालित अनुबंध (सीडीसी)

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

उपभोक्ता अनुबंध का वर्णन करता है।
आपूर्तिकर्ता इस अनुबंध को घर पर लागू करता है।
इस अनुबंध का उपयोग उपभोक्ता और आपूर्तिकर्ता में CI प्रक्रिया में किया जाता है। यदि प्रक्रिया का उल्लंघन किया जाता है, तो किसी ने अनुबंध का पालन करना बंद कर दिया है।

संधि

PACT एक उपकरण है जो इस विचार को कार्यान्वित करता है।

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

क्लाइंट परीक्षणों के दौरान, एक प्रदाता स्टब बनाया जाता है, और आपूर्तिकर्ता परीक्षणों के दौरान, एक क्लाइंट स्टब बनाया जाता है। ये दोनों स्टब्स एक पैक्ट फाइल का उपयोग करते हैं।

इसी तरह का ठूंठ निर्माण व्यवहार स्वैगर मॉक वैलिडेटर bitbucket.org/atlassian/swagger-mock-validator/src/master के माध्यम से प्राप्त किया जा सकता है ।

पैक्ट के बारे में उपयोगी लिंक

संधि दलाल - संधि फ़ाइल प्रबंधन समाधान docs.pact.io/pact_broker
संधि अभी तक जीआरपीसी का समर्थन नहीं करती है। रोडमैप संधि के बारे में और अधिक पढ़ें pact.canny.io ।
PACT के बारे में अधिक जानकारी docs.pact.io पर देखें ।
आपको PACT docs.pact.io/faq/convinceme का उपयोग क्यों करना चाहिए

CDC को CI में कैसे एम्बेड किया जा सकता है

पैक्ट + पैक्ट ब्रोकर की तैनाती स्वयं;
एक तैयार पैक्ट फ्लो सास समाधान खरीद।

निष्कर्ष

संविदा अनुपालन सुनिश्चित करने के लिए संधि की आवश्यकता है। यह दिखाएगा कि जब अनुबंधों में बदलाव उपभोक्ता सेवाओं की उम्मीदों का उल्लंघन करते हैं।

यह उपकरण तब उपयुक्त होता है जब आपूर्तिकर्ता ग्राहक - ग्राहक को अडॉप्ट करता है। यह एक पृथक प्रणाली के अंदर ही संभव है।

यदि आप बाहरी दुनिया के लिए एक सेवा कर रहे हैं और यह नहीं जानते हैं कि आपके ग्राहक कौन हैं, तो पैक्ट आपके लिए नहीं है।

सार्वजनिक अनुबंध, उनकी स्थिरता कैसे सुनिश्चित करें

शर्तें

यह लेख किस बारे में है

समस्या क्या दिखती है?

इस समस्या को हल कैसे करें

आपूर्तिकर्ता सेवा टीम सब कुछ ठीक कर देगी

उपभोक्ता टीम को अपनी सेवा का कोड अपडेट करें

सोचें कि समस्या को प्रकट होने से रोकने के लिए क्या करना चाहिए

किसी समस्या की अभिव्यक्ति को कैसे रोका जाए

समस्या हमारे साथ कैसे दिखती है

समस्या से कार्य तक

प्रशन

कौन सा टूल चुनना है

उपकरण

OpenAPI के साथ काम करने के लिए उपकरण

ठेके की व्यवस्था कहां से करें। अनुबंधों तक सेवाओं का उपयोग कैसे करें

आप किस बिंदु पर उत्पन्न होते हैं

क्लाइंट कोड कहां रखें

हम NSwag उपवास करते हैं

नियंत्रक विशेषताएँ

फ़ाइल संचालन के लिए विनिर्देशों को बनाने के लिए प्रोसेसर

कल्पना और कोड पीढ़ी के लिए NSwag कॉन्फ़िगरेशन

सर्विस प्रोवाइडर के प्रोजेक्ट को असेम्बल करने पर हम स्पेसिफिकेशन और क्लाइंट कोड जनरेट करते हैं

JWT के लिए समर्थन कैसे जोड़ें

निष्कर्ष

सार्वजनिक अनुबंधों का संस्करण

सार्वजनिक अनुबंधों का संस्करण क्यों?

समाधान के विकल्प

सार्वजनिक अनुबंधों के संस्करण के बिना

सार्वजनिक अनुबंधों के संस्करण का उपयोग करें

किस उपकरण का उपयोग करें

एक नए संस्करण को कब पेश किया जाए

संस्करणों को बनाए रखने के लिए कब तक

निष्कर्ष

परीक्षण अनुबंध और सीडीसी

उपभोक्ता संचालित अनुबंध (सीडीसी)

संधि

पैक्ट के बारे में उपयोगी लिंक

CDC को CI में कैसे एम्बेड किया जा सकता है

निष्कर्ष

More articles: