स्टार्टअप में पांच महत्वपूर्ण API एकीकरण त्रुटियाँ

त्रुटि # 1। पीछे हटने की कोई पहचान और "तूफान" नहीं

लक्षण: डुप्लिकेट ऑर्डर/भुगतान, मात्रा में विसंगति, विवादित रिटर्न, डीएलक्यू अलर्ट बढ़ रहे हैं।

जड़: अनुरोधों/वेबहूक और नेटवर्क फ्लैपी की बार-बार डिलीवरी सामान्य है। यदि "क्रिएट/राइट ऑफ" ऑपरेशन अज्ञात नहीं है, तो रिट्रेज़क्षति को गुणा करता है।

कैसे करें

सभी असुरक्षित विधियों (POST/PATCH) के लिए पहचान-कुंजी/' ऑपरेशन _ id '.

'ऑपरेशन _ आईडी' के लिए डेटाबेस में अद्वितीय सूची। पुनरावृत्ति - पिछला परिणाम लौटाएँ।

इनबॉक्स तालिका के माध्यम से वेबहुक ('ईवेंट _ आईडी + सिग्नेचर' द्वारा dedupe)। आउटबाउंड घटनाएँ - आउटबॉक्स।

रेट्राई: अधिकतम 1-2 बार, घातांक + जिटर, केवल सुरक्षित संचालन के लिए।

HTTP सम्मेलन (उदाहरण):

http
POST/v1/भुगतान
पहचान-कुंजी: ik_f35a2
सामग्री प्रकार: अनुप्रयोग/json

{"राशि": 5000, "मुद्रा": "ईयूआर", "स्रोत": "card_..."}

SQL सुरक्षा (सरलीकृत):

sql
ALTER टेबल भुगतान ADD CONTRAINT uniq_op UNATE (operation_id);

जिटर के साथ रेट्राई (स्यूडोकोड):

रेंज में I के लिए अजगर (2):
कोशिश करें: रिटर्न call_api (पेलोड, टाइमआउट = 0। 6)
टाइमआउट को छोड़ कर:
नींद (0। 05 2i + यादृच्छिक। वर्दी (0, 0। 05))
अपस्ट्रीम अनुपलब्ध उठाएँ

चेकलिस्ट:

सभी "मौद्रिक/निर्माण" तर्क में 'ऑपरेशन _ आईडी' और यूनिक इंडेक्स है।
इनबाउंड वेबहुक केवल पहचान कार्यकर्ता के साथ इनबॉक्स के माध्यम से।
क्लाइंट SDK स्वचालित रूप से Idempotency-Key सेट करता है।

त्रुटि संख्या 2। टाइमआउट/रिट्रेज़बनाम एसएलओ: निर्भरता ओवरहीटिंग

लक्षण: p95 अचानक तैरता है, कतारें बढ़ ती हैं, सर्किट ब्रेकर "बैंग्स"।

रूट: प्रतिक्रिया का कुल एसएलओ 400-600 एमएस है, और बाहरी एपीआई के लिए टाइमआउट 1-2 एस हैं, और यहां तक कि × 3 को भी पीछे छोड़ देता है। आप जितना लंबा कर सकते हैं और आप नशे की लत को दोहराते हैं।

कैसे करें

बजट समय: यदि SLO 400 ms है, तो अपस्ट्रीम टाइमआउट: 250-300 ms; SLO ≤ अनुरोध का कुल समय समाप्ति।

सीमाएं/बैकप्रेशर: प्रत्येक निर्भरता के लिए कॉल के लिए सेमाफोरेस/वर्कर-पूल। एक बार में → 429/503 भीड़।

सर्किट ब्रेकर: टाइमआउट/5xx के साथ 'ओपन', 'हाफ-ओपन' डॉस्ड।

प्रवेश नियंत्रण: प्रतिगामी (प्रति धागा, समापन बिंदु/पीएसपी के अनुसार) प्रतिबंधित करें।

उदाहरण (जाओ):

गो सेम: = मेक (चान स्ट्रक्ट {}, 64 )//प्रतियोगिता सीमा पीएसपी फंक कॉलपीएसपी (सीटीएक्स संदर्भ) के लिए। संदर्भ, Req Req) (Res, त्रुटि) {
{चुनें
केस सेम <- संरचना {} {}:
स्थगित कवक () {<-sem} ()
c, रद्द करें: = संदर्भ। WithTimeout (ctx, 300time। मिलीसेकंड)
स्थगित रद्द करें ()
वापसी psp। करते हैं (c, req)
डिफ़ॉल्ट:
रिटर्न Res {}, अंतहीन कतार के बजाय ErrBusish//तत्काल विफलता
}
}

चेकलिस्ट:

टाइमआउट एसएलओ से छोटे हैं; रेट्राई ≤ 2; वहाँ jitter है।
बाहरी एपीआई के लिए पूल/सेमाफोर; मेट्रिक्स के साथ सर्किट ब्रेकर।
व्यस्त मार्गों पर, हम वापस लौटते हैं - कनेक्शन नहीं रखते हैं।

त्रुटि संख्या 3। कमजोर सुरक्षा: वेबहुक हस्ताक्षर, रहस्य, टीएलएस

लक्षण: "अन्य लोगों के" वेबहूक गुजरते हैं, कोड/लॉग में रहस्य, MITM जोखिम।

रूट: कोई हस्ताक्षर/ताजगी की जाँच नहीं, रहस्य एनवी फ़ाइलों, पुराने टीएलएस और कमजोर हेडर में रहते हैं।

कैसे करें

वेबहुक का हस्ताक्षर HMAC-SHA256 + 'एक्स-टाइमस्टैम्प' (विंडो ≤ 5-10 मिनट), हस्ताक्षर की सख्त तुलना।

महत्वपूर्ण एकीकरण या आईपी अनुमति-सूची के लिए एमटीएलएस।

तिजोरी/क्लाउड केएमएस के माध्यम से रहस्यों का घुमाव; न्यूनतम अधिका घटाव लेखा परीक्षा।
टीएलएस 1। 2/1. 3 केवल, HSTS, सही CORS (संकीर्ण स्रोत सूची)।

हस्ताक्षर सत्यापन (पायथन):

अजगर def सत्यापित (sig_hdr, ts_hdr, शरीर, रहस्य):
यदि abs (समय)। समय () - int (ts_hdr))> 600: वृद्धि समाप्त ()
calc = hmac। नया (रहस्य, (ts_hdr +। "" + शरीर)। एनकोड (), हैशलिब। sha256)। hexdigest ()
अगर hmac नहीं। compare_digest (calc, sig_hdr): BadSig ()

चेकलिस्ट:

सभी वेबहुक हस्ताक्षरित और सत्यापित हैं; ताजगी की खिड़की सीमित है।
केएमएस/वॉल्ट में रहस्य, रोटेशन और ऑडिटिंग है।
टीएलएस/एचएसटीएस सक्षम; CORS बिंदु; आईपी/एमटीएलएस जहां उपयुक्त हो।

त्रुटि संख्या 4। अनुबंध बहाव: योजना "अपना जीवन व्यतीत करती है"

लक्षण: प्रॉड "केवल कुछ ग्राहकों में" गिर गया, लॉग में 500/422, एसडीके और एपीआई के विभिन्न संस्करणों का तर्क है।

जड़: अनुबंधों का कोई सख्त विवरण नहीं है, पिछड़े असंगत परिवर्तन, "शांत" क्षेत्र, एक ही नामों के लिए अलग-अलग अर्थ।

कैसे करें

अनुबंध-पहला: OpenAPI/AsyncAPI + सर्वर/क्लाइंट जनरेशन; घटनाओं के लिए - एवरो/प्रोटोबुफ + स्कीमा रजिस्ट्री।

वर्शनिंग: 'v1 → v2' (URI/हेडर), विचलन-योजना, अनुग्रह-अवधि।

बैकवर्ड-कॉम्पैट: मामूली रिलीज में केवल योजक परिवर्तन; वी-बम्प के बिना हटाया/नाम बदला नहीं जा सकता.

संविदा परीक्षण: संधि/बफ - प्रदाता/उपभोक्ता का सीआई में परीक्षण किया जाता है।

उदाहरण:

यमल
OpenAPI: लघु इकाइयों में योग का स्पष्ट प्रकार:
प्रकार: पूर्णांक न्यूनतम: 0 विवरण: न्यूनतम मुद्रा इकाइयों में योग (पूर्णांक)

चेकलिस्ट:

अनुबंध को गिट में संग्रहीत किया जाता है, यदि असंगत हो तो सीआई मान्य/टूट जाता है।
स्कीमा घटनाओं के लिए पंजीकरण करता है, "बैक/फॉरवर्ड" संगतता।
परिवर्तनों का डॉकिंग पृष्ठ, अवक्षेपण की तारीखें, भागीदारों के लिए परीक्षण बेंच।

त्रुटि संख्या 5। "ब्लाइंड" लॉन्च: कोई मेट्रिक्स/लॉग/ट्रेल्स और सैंडबॉक्स नहीं

लक्षण: "कुछ भी दिखाई नहीं देता है", समर्थन भरता है, डीबैग - हैंड इन प्रोड।

जड़: अवलोकन शामिल नहीं था, कोई सिंथेटिक्स नहीं है, सैंडबॉक्स का परीक्षण "शब्दों में" किया गया था।

कैसे करें

RED/USE metrics: मार्ग/विधि द्वारा प्रत्येक समापन बिंदु पर दर/त्रुटि/विलंबता।

सहसंबंध: सभी लॉग और प्रतिक्रियाओं में 'ट्रेस _ आईडी'; zapros↔vebkhuk का बंडल।

सिंथेटिक्स: स्वास्थ्य परीक्षण (लॉगिन/जमा रेत), वेबहुक के लिए एसएलए निगरानी टी + 60।

सैंडबॉक्स/चरण: पूरी तरह से पृथक कुंजी/डोमेन, काल्पनिक पीएसपी, प्रविष्टियाँ "रिपोर्ट में शामिल नहीं हैं।"

ट्रेस आईडी के साथ प्रतिक्रिया:

http
HTTP/1। 1 202 स्वीकार किया
ट्रेस-आईडी: 7f2b3d8e9c1a4
स्थान :/ v1/ops/req_42/status

चेकलिस्ट:

RED/USE metrics, डैशबोर्ड, अलर्ट (लक्षण + कारण)।
एंड-टू-एंड ट्रेल्स; JSON लॉग, कोई PII नहीं, 'trace _ id' के साथ।
प्रमुख क्षेत्रों से सिंथेटिक्स; सैंडबॉक्स आवश्यक है, अलग कुंजी।

प्रीलांच योजना (T-7 → T-0)

T-7 दिन:

अंतिम अनुबंध स्कैन: क्या कोई असंगत परिवर्तन हैं; फ्रीज योजनाओं।
रहस्य/प्रमाणपत्र: घुमाव, पहुँच, केएमएस नीतियों की जाँच करें।
सिंथेटिक्स 24 × 7, अलर्ट ऑन-कॉल से बंधे होते हैं।

टी-3 दिन:

मिनी-रन लोड करना (2-5 मिनट फट): हरे क्षेत्र में p95/पूल/कतारें।
DRY-RUN वेबहूक (रिप्ले, 5xx, जिटर), DLQ चेक।
भागीदारों की "फोन बुक": L1/L2 संपर्क, युद्ध-कक्ष चैनल।

T-0::

SLO गेट्स के लिए चैनल ट्रैफिक 5% → 25% → 50%; तैयार रोलबैक।
जोखिम भरे सुविधाओं पर किल-स्विच/फीचर-फ्लैग शामिल हैं।
युद्ध-कक्ष सक्रिय है, स्थिति टेम्पलेट तैयार किए जाते हैं।

रोलबैक योजना (अगर कुछ गलत हुआ)

1. पिछले स्थिर संस्करण/मार्ग पर यातायात जारी क

2. phicheflag विवादास्पद परिवर्तन अक्षम करें

3. कतारों/पूलों को स्थिर करें, एक तूफान में पीछे हटना बंद करें।

4. पोस्ट-घटना: समयरेखा, जड़ें, कार्य (निश्चित आगे/अनुबंध सुधार) एकत्र करें।

स्व-परीक्षण तालिका प्रारंभ करें (छोटा)

ब्लॉक	प्रश्न	हाँ, नहीं
पहचान	क्या सभी "बनाने" के तरीकों में एक आइडेम्पोटेंसी-की/' ऑपरेशन _ आईडी 'और एक यूनिक इंडेक्स है?
रिट्रेज ़/टाइमआउट	टाइमआउट एसएलओ से छोटे हैं; रेट्राई ≤2; पर jitter?
सुरक्षा	वेबहूक ने हस्ताक्षर किए, ताजगी खिड़की ≤10 मिनट, केएमएस में रहस्य?
अनुबंध	OpenAPI/AsyncAPI तय, CI असंगति को पकड़ ता है?
अवलोकन क्षमता	RED/USE, ट्रेल्स, सिंथेटिक T + 60, सैंडबॉक्स अलग-थलग?
रोलबैक	क्या एक/किल-स्विच रोलबैक बटन, संचार योजना है?

अक्सर पूछा "क्या होगा"...

... क्या प्रदाता Idempotency-Key का समर्थन नहीं करता है?

'हैश (बॉडी)' + 'पार्टनर _ request _ id' संग्रहीत करें और अपनी पहचान दर्ज करें.

... वेबहुक कभी-कभी "उत्तर से पहले" आते हैं?

'ऑपरेशन _ id' पर सीव करें और अस्थायी रूप से "अज्ञात → concile" स्थिति रखें; आवधिक सामंजस्य विसंगतियों को बंद कर देगा।

... पुराने ग्राहकों और नए का समर्थन करने की आवश्यकता

एंडपॉइंट्स ('/v1 'and '/v2') संस्करण, हेडर/यूआरआई द्वारा मार्ग, कम से कम एन महीनों के लिए पिछड़े संगतता रखें।

सारांश फिर से शुरू करें

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