संदर्भ कार्यान्वयन

1) उद्देश्य, सीमाएँ और सिद्धांत

1. प्रोटोकॉल/चश्मे की असंदिग्ध व्याख्या दें।

2. स्वतंत्र संगतता जांच सुनिश्चित क

3. क्लाइंट/सर्वर/वेबहूक के कार्यशील उदाहरण प्रदान करें।

4. एकीकरण और कार्यान्वयन की लागत को कम करें।

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

• स्पेक-फर्स्ट: ट्रू - इन स्पेसिफिकेशन्स (OpenAPI/AsyncAPI/Proto/JSON-Schema/IDL)।
• नियतात्मक और परीक्षण योग्य: प्रजनन योग्य प्रतिक्रियाएँ और कल्पनाएँ।
• डॉक्स-ए-कोड: सभी वीसीएस में, कोड और अनुरूपता परीक्षणों के साथ एक संस्करण।
• पोर्टेबिलिटी: कंटेनर, हेल्म/कंपोज, रेडी-मेड मैनिफेस्ट।

2) संदर्भ कार्यान्वयन के प्रकार

RI-Server: सर्वर संदर्भ प्रति विनिर्देश (REST/gRPC/GraphQL/स्ट्रीमिंग)।

आरआई-क्लाइंट/एसडीके: क्लाइंट संदर्भ (एक या दो लोकप्रिय प्लेटफॉर्म) + उदाहरण।

RI-Webhook रिसीवर: हस्ताक्षरित वेबहुक हैंडलर (हस्ताक्षर सत्यापन, रिट्रेज़)।

RI-Addapters: संदेश दलालों/घटना बसों (एवरो/प्रोटो/JSON, स्कीमा रजिस्ट्री) के लिए एडेप्टर।

आरआई-डेटा: संदर्भ डेटा सेट, गोपनीयता प्रोफाइल, सोने के स्नैपशॉट।

3) आरआई रिपॉजिटरी आर्किटेक्चर

ri/
specs/# OpenAPI/AsyncAPI/Proto/JSON-Schema server/# reference server src/
config/
docker/
helm/
client/# reference client/SDK + examples js/python/go/
conformance/# conformance runner, test cases, gold cases files/
fixtures/
golden/
samples/# end-to-end scripts, Postman/k6/Locust security/# test keys, policies, example signature docs/# manual, ADR, runbook, FAQ ci/# pipelines, configs, compatibility matrix tools/# generators, linters, circuit checkers

• प्रत्येक रिलीज़ में 'vX' टैग होता है। Y.Z 'और कलाकृतियाँ (चित्र, चार्ट, SDK)।
• प्रत्येक धब्बा के लिए - राशि और हस्ताक्षर (आपूर्ति-श्रृंखला)
• CHANGELOG ने "ब्रेकिंग" परिवर्तनों

4) स्पेक्स, अनुबंध और योजनाएं

परिवहन: OpenAPI/REST, gRPC/Proto, GraphQL SDL, AsyncAPI।

शब्दार्थ: त्रुटि कोड, पहचान, कर्सर/पगिनेशन, रेट्राई, डीडुप्लिकेशन।

घटनाएँ: type/version, 'id', 'hease _ at _ utc', 'partion _ key', invariants ऑर्डर करें.

हस्ताक्षर/सुरक्षा: OIDC/JWT टिकट, वेबहुक हस्ताक्षर (HMAC/EdDSA), कुंजी रोटेशन।

अनुपालन योजनाएं: 'बैकवर्ड' फॉरवर्ड 'फुल' नियम, मेजर के बिना कोई ब्रेकिंग चेंज नहीं।

5) अनुरूपता परीक्षण

• धब्बों का अनुपालन (योजनाओं का सत्यापन),
• व्यवहार अपरिवर्तनीय (पहचान, छंटाई, कर्सर, टीटीएल, पुन: प्रयास नीतियां),
• सुरक्षा (हस्ताक्षर, समय सीमा, गैर/रिप्ले सुरक्षा),
• अस्थायी पहलू (UTC, RFC3339, DST),
• नकारात्मक मामले और सीमा की स्थिति।

गोल्डन फाइलें: स्थिर संदर्भ प्रतिक्रियाएं/घटनाएं जिनके परिणामों की तुलना की जाती है

python def run_conformance(target_url, cases, golden_dir):
for case in cases:
req = build_request(case. input)
res = http_call(target_url, req)
assert match_status(res. status, case. expect. status)
assert match_headers(res. headers, case. expect. headers)
assert match_body(res. json, golden_dir / case. id, allow_extra_fields=True)
for invariant in case. invariants:
assert invariant. holds(res, case. context)

consumer/sdk-js 1. 4server 1. 6, 1. 7server 2. 0 consumer/sdk-go 0. 9server 1. 5–1. 7   –
webhook-receiver 1. 1events v1events v2 (deprecated fields removed)

6) उत्पादन न्यूनतम (कोई तामझाम नहीं)

सुरक्षा: डिफ़ॉल्ट रूप से टीएलएस, सुरक्षा हेडर, सीओआरएस सीमा, सीमाएँ, एंटी-रीप्ले।

अवलोकन: लॉग (संरचनात्मक + पीडी मास्किंग), मेट्रिक्स (p50/p95/p99, त्रुटि दर), ट्रेसिंग (सहसंबंध 'अनुरोध _ आईडी')।

कॉन्फ़िग: सभी पर्यावरण चर और फ़ाइलों के माध्यम से, कॉन्फ़िगरेशन योजना मान्य है.

पर्फ-बेसलाइन: कॉमन पूल सेटिंग्स, चेन टाइमआउट बजट, कोलसिंग के साथ कैश।

स्थिरता: जिटर, सर्किट ब्रेकर, बैकप्रेशर के साथ रेट्राई।

7) सीआई/सीडी और कलाकृतियाँ

1. लिंट/असेंबली/यूनिट परीक्षण।

2. कल्पना सत्यापन (OpenAPI/AsyncAPI/Proto-lint).

3. चश्मा से एसडीके/स्टैब का उत्पादन।

4. अनुरूपता रन: 'री-सर्वर' बनाम 'मामले' और 'सोना।'

5. छवियों का निर्माण करें (SBOM, हस्ताक्षर), रजिस्ट्री को प्रकाशित करें।

6. E2E स्क्रिप्ट (डॉकर-कम्पोज/काइंड/हेल्म)।

7. डॉकसाइट और उदाहरण प्रकाशित करना।

• कंटेनर चित्र 'री-सर्वर', 'री-वेबहुक',
• एसडीके पैकेज (npm/pypi/go),
• हेल्म चार्ट/कंपोज़फ़ाइलें,
• "गोल्ड फ़ाइलों" और एक अनुरूप धावक के साथ जिप करें।

8) नमूने, एसडीके और कैसे-कैसे

दो लोकप्रिय ढेरों पर मिनी-एप्लिकेशन (जैसे) नोड। चरण के साथ js/Go): प्रमाणीकरण → API कॉल → त्रुटि हैंडलिंग → रिट्रे → वेबहुक।

कैसे-टू: पहचान POST, कर्सिव पेगिनेशन, वेबहुक हस्ताक्षर, प्रसंस्करण 429/503।

k6/JMeter "धूम्रपान-पर्फ" के लिए प्रोफाइल (लोड नहीं, बल्कि बुनियादी स्वास्थ्य)।

9) सत्यापन और विकास

SemVer: ब्रेकिंग चेंज → मेजर; गैर-टूटने योग्य MINTER → PATCH → जोड़ें।

अस्वीकृति योजना: चश्मा में घोषणाएं, झंडे की सुविधा, "छाया" अनुरूपता मोड की अवधि, फिर लागू करें।

घटना संगतता: अपरिचित क्षेत्रों की अनदेखी करने के लिए उपभोक्ताओं की आवश्यकता होती है।

10) आरआई में सुरक्षा और गोपनीयता

परीक्षण कुंजी और रहस्य - केवल स्टैंड के लिए; गोदी में - प्रतिस्थापन निर्देश।

लॉग में पीडी मास्किंग; काल्पनिक गुमनामी प्रोफाइल (PII → सिंथेटिक्स)।

डेमो पर्यावरण कलाकृतियां आजीवन नीति (टीटीएल, ऑटो-क्लीन)।

11) आरआई के लिए अवलोकन और एसएलओ

SLI/SLO RI: p95 <250 ms संदर्भ बेंच पर, त्रुटि दर <0। 5%, निर्भरता विफलता के तहत सही गिरावट (नमूने में)।

डैशबोर्ड: विलंबता/थ्रूपुट/त्रुटियाँ + अनुरूप परिणाम।

वेबहूक/टोकन चेक (पता लगाया विफलता कारण) पर हस्ताक्षर करने के लिए निर्णय लॉग।

12) प्रदर्शन: "पर्याप्त" बेसलाइन

गर्म और ठंडी पटरियों पर 'wrk/hey/k6' प्रोफाइल।

स्पष्ट स्थिति: आरआई अधिकतम आरपीएस पर प्रतिस्पर्धा नहीं करता है, लेकिन एक विशिष्ट लक्ष्य का सामना करना चाहिए (उदाहरण के लिए, टी 3 पर 500 आरपीएस। p95 <200ms) के साथ मध्यम - इंटीग्रेटर के लिए एक दिशानिर्देश के रूप में।

13) ऑपरेशन मैनुअल (रनबुक)

स्थानीय लॉन्च: रचना/' मेकअप '।

K8s-deploy: हेल्म मूल्य, रहस्य, इंग्रेस, एचपीए।

वेबहुक हस्ताक्षर कुंजियों का घुमाव (दोहरी कुंजी अवधि)।

ट्रेबलशूटिंग: लगातार त्रुटियां और उनके कारण (401, 403, 429, 503), लॉग/ट्रेल्स कैसे पढ़ें।

14) प्रबंधन और स्वामित्व

मालिक: धब्बे + मंच (उपकरण) + सुरक्षा के उत्पाद मालिक।

पंचांग जारी करें और अनुमोदन विंडो को तोड़ें।

सार्थक प्रोटोकॉल परिवर्तन पर RFC/ADR।

15) भाषाओं/प्लेटफार्मों के लिए अनुकूलन

अनुशंसित न्यूनतम एक उच्च-स्तरीय (जेएस/टीएस) और एक प्रणाली (गो/जावा) है।

टाइप मैपिंग: कैसे दिनांक/मुद्रा प्रारूप/दशमलव/बाइट सेट दर्शाए जाते हैं।

प्रत्येक एसडीके में रिट्रेज ़/टाइमआउट/पूल सेटिंग के लिए सिफारिशें।

16) एंटी-पैटर्न

RI = "परीक्षण के बिना सैंडबॉक्स": कोई अनुरूपता नहीं, कोई लाभ नहीं।

स्पेका कोड से "अलग से रहता है" और विसंगति का परीक्षण करता है।

"गोल्डन फाइल" और इनवेरिएंट्स की कमी - व्यवहार के बारे में गुच्छे और विवाद।

निर्भरता ढांचा: कंटेनराइजेशन के बिना एक पुस्तकालय/क्लाउड के लिए कठोर बंधन।

पीडी मास्किंग के बिना लॉग, भंडार में कुंजी।

पर्फ व्यवहार के बजाय मिश्रण करता है: "कौन सही है" के बजाय "कौन तेज है" को मापने की कोशिश कर रहा है।

मॉड्यूलर और कलाकृतियों के बिना एक विशाल द्विआधारी/छवि (एसडीके/चार्ट/चश्मा)।

17) आर्किटेक्ट चेकलिस्ट

1. Speka - canonical और मान्य? (OpenAPI/Proto/AsyncAPI/JSON-Schema)

2. क्या पूर्ण उदाहरणों के साथ एक आरआई-सर्वर और कम से कम एक आरआई-क्लाइंट/एसडीके है?
3. अनुरूपता धावक, मामले, "सुनहरी फाइलें", नकारात्मक और अपरिवर्तनीय तैयार?
4. CI/CD छवियों, SDK, साइट, अनुरूपता और e2e को इकट्ठा करता है?
5. डिफ़ॉल्ट सुरक्षा: टीएलएस, हस्ताक्षर, सीमा, पीडी मास्किंग?
6. अवलोकन: आरआई के लिए लॉग/मैट्रिक्स/ट्रेल्स, डैशबोर्ड और एसएलओ?
7. Perf-basline प्रलेखित और प्रजनन योग्य?
8. SemVer वर्शनिंग, संगतता मैट्रिक्स, अस्वीकृति प्रक्रिया?
9. रनबुक और स्थानीय/क्लस्टर लॉन्च - एक क्लिक में?
10. मालिक, रिलीज़ कैलेंडर, RFC/ADR स्ट्रीम परिभाषित?

18) मिनी-उदाहरण: संदर्भ वेबहुक (स्यूडोकोड)

python def verify_webhook(request, keys):
sig = request. headers["X-Signature"]
ts = int(request. headers["X-Timestamp"])
if abs(now_utc(). epoch - ts) > 300: return 401 # replay window body = request. raw_body if not any(hmac_ok(body, ts, k, sig) for k in keys. active_and_previous()):
return 401 event = json. loads(body)
if seen(event["id"]): return 200 # idempotency handle(event)
mark_seen(event["id"])
return 200

परीक्षण मामला जांचता है: समय विंडो, हस्ताक्षर की शुद्धता (वर्तमान और पिछली कुंजी), घटना की पहचान. id ', नकारात्मक (भ्रष्ट हस्ताक्षर, समाप्त' ts ')।

निष्कर्ष

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