प्रोटोकॉल-पहला डिजाइन

प्रोटोकॉल पहला क्या है

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

कोड-फर्स्ट के विपरीत, जहां एपीआई केवल कोड का एक उपोत्पाद है, प्रोटोकॉल-पहले प्रोटोकॉल को एक प्राथमिक कलाकृति बनाता है: यह डोमेन अवधारणाओं, डेटा मॉडल, स्टेटस, त्रुटियों, निष्क्रियता शब्दार्दों, एसएलओ/एसएलआई और यहां तक कि नीति नीति का मालिखण है।

आपको इसकी आवश्यकता क्यों है?

संगठन भर में इंटरफेस की संगति और पूर्वानुमेयता।

फास्ट ऑनबोर्डिंग (एसडीके/स्थिर/ग्राहक ऑटोजेनरेशन, समान त्रुटियां और कोड)।

विश्वसनीय विकास (योजनाओं की संगतता, परीक्षण अनुबंध, स्पष्ट संस्करण नीति)।

उत्पाद फोकस: कोड लेखन से पहले व्यवहार, एसएलए और यूएक्स एकीकरण पर चर्चा करें।

स्वचालन: CI/CD सत्य के एकल स्रोत से कलाकृतियों (क्लाइंट, सर्वर स्टब्स, वेलिडेटर्स) को एकत्र करता है।

सुरक्षा और अनुपालन: अधिकार, पीआईआई मास्किंग, प्रतिधारण नीतियां अनुबंध में निहित हैं।

कोर दृष्टिकोण

1. सत्य का एकल स्रोत (SSOT) - मशीन-पढ़ने योग्य विनिर्देश:

REST: OpenAPI/JSON स्कीमा।

घटनाओं और स्ट्रीमिंग: AsyncAPI, एवरो/JSON स्कीमा।

आरपीसी: प्रोटोबुफ (जीआरपीसी), थ्रिफ्ट, स्मिथी।

ग्राफक्यूएल: एसडीएल + निर्देश/नीतियां।

2. पूर्व-कार्यान्वयन व्यवस्था: डोमेन शब्दावली, त्रुटि कोड, आइडेम्पोटेंसी शब्दार्थ, समय सीमा, रिट्रे, डीडुप्लिकेशन।

3. ऑटोजेनरेशन: क्लाइंट/सर्वर स्टब, टाइप, एसडीके, टेस्ट कॉन्ट्रैक्ट, मोक्स, पोस्टमैन कलेक्शन, टेराफॉर्म/ओपनएपीआई गेटवे कॉन्फ़िग।

4. शासन: लिंटर्स/नीतियां (नामकरण, पृष्ठभूमि, फिल्टर, त्रुटियां), एपीआई गिल्ड के माध्यम से समीक्षा, प्रमुख संस्करणों के लिए परिवर्तन-सलाहकार।

5. संगतता: "एडिटिव-ओनली" डिफ्यूज़, सिमेंटिक वर्शनिंग, कैनरी/उपभोक्ता-चालित परीक्षणों का सख्त सत्यापन।

6. अनुबंध स्तर पर अवलोकन: सहसंबंध आईडी, त्रुटि मॉडल, देरी बजट प्रोटोकॉल में वर्तनी है।

प्रक्रिया कैसी दिखती है (कंकाल)

1. दीक्षा: उत्पाद संक्षिप्त → उपयोगकर्ता यात्रा → API/प्रोटोकॉल PRD (संसाधन/विधियां/घटनाएँ, SLA/SLO, त्रुटियां, सीमा)।

2. मॉडलिंग: ड्राफ्ट स्पेसिफिकेशन (OpenAPI/AsyncAPI/Proto) + डेटा स्कीमा, शब्दों का शब्दकोश।

3. अनुबंध और यूएक्स एकीकरण: पेलोड उदाहरण, त्रुटि अनुबंध, स्थिति मानचित्र, संस्करण नियम।

4. समीक्षा और शासन: लिंटर/मानक, डोमेन आक्रमणकारियों की चर्चा, लॉक-इन एमजीसी (न्यूनतम वारंटी अनुबंध)।

5. कलाकृतियों की ऑटो-पीढ़ी: एसडीके, छुरा, परीक्षण सुधार, बुनियादी ढांचा स्टब (गेटवे, आईएएम स्कोप)।

6. कार्यान्वयन और अनुबंध परीक्षण: आपूर्तिकर्ता और उपभोक्ता सीआई में संगतता जांच से गुजरते हैं।

7. अवलोकन और एसएलओ: सहसंबंध-आईडी ट्रेसिंग, त्रुटि कैटलॉग, रिट्रे/टाइमआउट बजट।

8. रिलीज़ और विकास: एडिटिव-फर्स्ट, रिजेक्शन पॉलिसी, कैनरी, ए/बी क्षमता के झंडे।

इंटरैक्शन प्रोटोकॉल और शैलियाँ

REST/HTTP

मानक: संसाधन मॉडल, 'GET/POST/PATCH/DELETE', pagination (कर्सर), फ़िल्टर, सॉर्टिंग।

फ़ील्ड और योजनाएँ: JSON स्कीमा, प्रारूप ('तिथि-समय', 'uuid'), इनवेरिएंट्स (regex/enum/min-max)।

त्रुटि: एकल प्रारूप ('प्रकार', 'कोड', 'शीर्षक', 'विस्तार', 'ट्रेस _ आईडी'), HTTP स्टैक में मैपिंग.

परिवर्तन नियंत्रण: ETag/If-Match, POST के लिए पहचान कुंजी, स्पष्ट शब्दार्थ 409/422।

gRPC/RPC

Protobuf: स्थिर टैग नंबरिंग, 'वैकल्पिक', हटाए गए क्षेत्रों के पुन: उपयोग को रोकना।

अनुबंध में समय सीमा और प्राथमिकताएं; स्थिर स्थिति (ओके, INVALID_ARGUMENT, FAILED_PRECONDITION, आदि)।

स्ट्रीमिंग: संदेश आदेश विनिर्देश, बैकप्रेशर, अंतिम ट्रेलर।

घटना-चालित (काफ्का/एनएटीएस/एसएनएस/एसक्यूएस)

AsyncAPI: थीम/चैनल, विभाजन कुंजी, डीडुप्लिकेशन कुंजी सम्मेलन, प्रतिधारण, वास्तव में एक बार शब्दार्थ "बनाम" कम से कम एक बार। "

कोर इवेंट और संवर्धन: अलग न्यूनतम पेलोड और एक्सटेंशन; संस्करण 'event _ type '/' schema _ version'।

पहचान: 'ईवेंट _ आईडी', 'प्रोड्यूसर _ आईडी', पुनरावृत्ति और डीडुप्लीकेशन पर पॉलिसी।

ग्राफ़क्यूएल

एक अनुबंध के रूप में एसडीएल, मूल्यह्रास के लिए निर्देश, गहराई और जटिलता पर सीमाएं, त्रुटि कोड/एक्सटेंशन अनुबंध।

वास्तुशिल्प सिद्धांतों के साथ एकीकरण

उलटा पिरामिड/महत्वपूर्ण पथ पहला: विनिर्देशन में, एमजीसी (अनिवार्य न्यूनतम), एक्सटेंशन - 'के माध्यम से? = '/क्षमताओं को शामिल करें।

पक्की सड़ कें: तैयार किए गए विनिर्देश टेम्पलेट (भुगतान, केवाईसी, ऑडिट, खोज, फाइलें) + लिंटर्स का एक सेट।

एपीआई गेटवे एंड सर्विस मेश: अनुबंध-आधारित नीतियां (दर-सीमा, ऑथ स्कोप, रेट्रीज, सर्किट-ब्रेकर)।

Versioning और Evolution

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

सुरक्षा और अनुपालन

अनुबंध के हिस्से के रूप में प्रमाणीकरण/प्राधिकरण (OAuth2/OIDC स्कोप, एमटीएलएस, जेडब्ल्यूटी दावा)।

पीआईआई/पीसीआई: मास्किंग, टोकन प्रारूप, विशेष भंडारण मोड/टीटीएल वाले क्षेत्र।

लेखा परीक्षा नीतियाँ: आवश्यक विशेषताएँ ('कर्ता', 'विषय', 'क्रिया', 'heased _ at', 'trace _ id').

सीमाएँ: दर सीमा हेडर, कोटा, संदेश आकार, समय सीमा।

संविदा अवलोकन

सहसंबंध/अनुरोध-आईडी: विनिर्देशन में आवश्यक।

त्रुटि कैटलॉग - निश्चित कोड और SLA को हल करने के लिए।

SLI/SLO: p50/p95 विलंबता, सफल प्रतिक्रियाओं का अनुपात, संगत घटनाओं का अनुपात, अज्ञात दोहराव का अनुपात।

परीक्षण और गुणवत्ता

अनुबंध परीक्षण (प्रदाता ↔ उपभोक्ता), सीआई में स्कीमा डिफ, मॉक सर्वर की पीढ़ी।

गोल्डन नमूने: अनुरोधों/प्रतिक्रियाओं के संदर्भ उदाहरण, e2e के लिए जुड़ नार।

अराजकता/विलंबता इंजेक्शन: टाइमआउट/रिट्रे चेक, एमजीसी को बचाते समय एक्सटेंशन का क्षरण।

नमूना डोमेन टैम्प्लेट्स

भुगतान (REST + घटनाएँ)

'POST/भुगतान' → 'भुगतान _ id', 'स्थिति = अधिकृत' के साथ '201 बनाया'।

घटना का भुगतान। अधिकृत। v1 '(ядро): ' {payment_id, राशि, मुद्रा, विधि, occurred_at} '।

विस्तार 'भुगतान। समृद्ध। v1 ': जोखिम दर, जियो, डिवाइस-फिंगरप्रिंट।

त्रुटियां: '422' (सत्यापन), '402' (भुगतान आवश्यक), '409' (डुप्लिकेट)।

SLA: प्राधिकरण ≤ 800ms p95; कर्नेल इवेंट ≤ 2c लैग पी 95।

KYC (gRPC + कतार)

आरपीसी 'StartVerification (user_id)' → 'ऑपरेशन _ id'।

विषय 'kyc में प्रगति की घटनाएँ। स्थिति। v1 '(' PENDING '→' ADENDED/RECEND ')।

अनुबंध पीआईआई क्षेत्रों, शेल्फ जीवन, मास्किंग, कारण विफलता कोड को निर्धारित करता है।

लेखा परीक्षा (केवल घटना)

'audit। रिकॉर्ड कि v1 '(ядро): ' अभिनेता ',' विषय ',' क्रिया ',' hece _ at ',' ट्रेस _ id '।

संवर्धन: आईपी, उपकरण, भू - एक अलग घटना/धागा, कर्नेल को अवरुद्ध नहीं करता है।

उपकरण और स्वचालन (लगभग ढेर)

Спеки: OpenAPI/AsyncAPI/Protobuf/Avro/GraphQL SDL।

Линтеры: स्पेक्ट्रल, ओपनएपीआई डिफ, बफ (प्रोटोबुफ), कन्फ्लूएंट एसआर संगतता जांच।

Генерация: OpenAPI जनरेटर, Buf/Protoc, GraphQL Codegen, AsyncAPI जनरेटर।

गेटवे: Cong/Apigee/Azure/GCP GW, दूत।

Тесты: संधि/सीडीसी, ड्रेड, स्कीमाथेसिस, होवरफ्लाई, मॉकसर्वर।

रजिस्टर: योजनाओं की गिट-निर्देशिका + स्कीमा रजिस्ट्री/कला रजिस्ट्री।

प्रलेखन: Redocly/Stoplight/Swagger-UI/GraphiQL/Explorer।

एंटी-पैटर्न

दुर्घटना से कोड-पहला: "एमवीपी पहले नियंत्रकों पर", तथ्यात्मक विनिर्देश, प्रलेखन और व्यवहार के बीच विसंगति।

स्वैगर-वॉश: वास्तविक नियमों (त्रुटियों, सीमाओं, एसएलए, संस्करणों) के बिना एक औपचारिक OpenAPI।

संगतता विराम: प्रमुख संस्करण के बिना हटाए गए क्षेत्र/परिवर्तित प्रोटोबुफ टैग का पुन: उपयोग करना।

पैगिनेशन/फिल्टर के बिना "मोटी" प्रतिक्रिया; पहचान की कमी।

ऑफ-कॉन्ट्रैक्ट सिक्योरिटी: ऑथ/स्कोप्स का वर्णन विकी में किया गया है, लेकिन विनिर्देशन में नहीं।

संगठन को संसाधित करने के लिए संबंध

एपीआई गिल्ड: मानक ट्रस्टी, समीक्षा बदलें, प्रशिक्षण लें।

डिजाइन डॉक्स: प्रत्येक एपीआई - पीआरडी, एडीआर (समाधान), एसएलए, जोखिम मैट्रिक्स के लिए।

परिवर्तन प्रबंधन: RFC प्रक्रिया, रिलीज़ नोट्स, माइग्रेशन गाइड, विचलन-समयरेखा।

Paved Road & Templates: विनिर्देशन से सेवा ढांचा जनरेटर (हैंडलर कंकाल, सत्यापन, लॉगिंग)।

जाँच सूची

प्रारंभ होने से पहले

• एक PRD और एक डोमेन शब्दावली है।
• चयनित शैली (REST/gRPC/Event/GraphQL) और स्कीमा प्रारूप।
• एमजीसी, त्रुटियां, एसएलए/एसएलओ, पहचान नियम परिभाषित।

विकास के अंतर्गत

• विनिर्देशन लिंटर्स और समीक्षा पास करता है।
• एसडीके/स्थिर/स्थिरता ऑटो-जनरेशन कॉन्फ़िगर किया गया है।
• अनुबंध-परीक्षण (सीडीसी) सीआई में शामिल हैं; स्कीमा-डिफ ब्लॉक असंगत परिवर्तन करता है।

रिलीज से पहले

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

FAQ

प्रोटोकॉल-पहला एपीआई-पहले से कैसे भिन्न है?

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

क्या इससे विकास धीमा हो जाएगा?

शुरुआत थोड़ी लंबी हो सकती है, लेकिन फिर हम एकीकरण, स्थिरता और समानांतर विकास गति (ऑटो-जेनरेशन, स्थिर एसडीके) पर जीतते हैं।

त्वरित प्रयोगों का क्या करना है?

योजनाओं (ड्राफ्ट), फ्लैग और सैंडबॉक्स के "ड्राफ्ट" संस्करणों का उपयोग करें, लेकिन लिंटर और बुनियादी संगतता नियमों को न छोड़ें।

कुल

प्रोटोकॉल-पहला डिजाइन अनुबंध को वास्तुकला का केंद्र बनाता है: हम व्यवहार का समन्वय करते हैं, योजनाओं को ठीक करते हैं, स्वचालित पीढ़ी और परीक्षण करते हैं, अतिरिक्त रूप नतीजतन, हमें स्केल और कमांड में परिवर्तन के लिए पूर्वानुमेय एकीकरण, विकास की उच्च गति और सिस्टम का प्रतिरोध मिलता है।