कोड गंध 303 - परिवर्तन करते समय मौजूदा ग्राहकों को तोड़ने से कैसे रोकें

जब आप बिना चेतावनी के एपीआई को तोड़ते हैं, तो आप विश्वास को तोड़ते हैं

TL;DR: आपको अपने एपीआई को संस्करण करना चाहिए ताकि आप परिवर्तन करते समय मौजूदा क्लाइंट को तोड़ने से रोक सकें।

TL;DR: आपको अपने एपीआई को संस्करण करना चाहिए ताकि आप परिवर्तन करते समय मौजूदा क्लाइंट को तोड़ने से रोक सकें।

समस्याएं

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

समाधान

1. Semantic Version को जोड़ें
2. Backward Compatibility का उपयोग करें
3. अप्रत्याशित चेतावनी बनाएं
4. रोडमैप बनाएं
5. Content Negotiation का उपयोग करें
6. समान संस्करण बनाए रखें
7. बदलावों को जल्द से जल्द बताएं
8. लक्षणों को धीरे-धीरे हटाएं
9. दस्तावेज़ स्पष्ट रूप से बदलाव को तोड़ रहा है
10. लॉगिंग के साथ अपरिवर्तित मापदंडों की जांच करें
11. नए संस्करणों का पूरी तरह से परीक्षण
12. सूर्यास्त के बाद कमजोर कार्यक्षमता को हटाएं

संदर्भ

जब आप सही संस्करण किए बिना एपीआई को संशोधित करते हैं, तो आप विघटन परिवर्तन बनाते हैं जो सभी मौजूदा क्लाइंट को प्रभावित करते हैं।

आप उपभोक्ताओं को तुरंत अपने कोड को अपडेट करने के लिए मजबूर करते हैं या सिस्टम विफलताओं का सामना करते हैं।

आप API प्रदाताओं और उपभोक्ताओं के बीच अनुबंध को तोड़ते हैं।

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

आज यह पहले से कहीं अधिक महत्वपूर्ण हैकई आईएएस मौजूदा एपीआई दस्तावेज का उपयोग करके अपने समाधान बनाते हैं.

जब आप एपीआई को वापस संगतता बनाए रखने के बिना अपडेट करते हैं, तो आप उस पर निर्भर सभी अनुप्रयोगों को तोड़ने का जोखिम उठाते हैं।

यह उपयोगकर्ताओं के लिए अस्थिरता, निराशा और महंगी मरम्मत पैदा करता है।

ग्राहक अक्सर सहन करते हैंदोषोंनई कार्यक्षमताओं में, लेकिन कभी भी पहले स्थिर व्यवहार टूट गया।

सही संस्करण संक्रमण को सुनिश्चित करता है और आपके सिस्टम की विश्वसनीयता बनाए रखता है।

नमूना कोड

ग़लत

// user-api-v1.json - Original API response
{
  "id": 317,
  "name": "Mr Nimbus",
  "email": "nimbus@atlantis.com",
  "nationalities": "Brazilian,Canadian,Oceanic"
}

// Later changed to this without versioning:
{
  "userId": 317,
  "fullName": "Mr Nimbus", 
  "emailAddress": "nimbus@atlantis.com",
  "createdAt": "2018-12-09T18:30:00Z",
  "nationalities": ["Brazilian", "Canadian", "Oceanic"]
}

fetch('/api/users/317')
  .then(response => response.json())
  .then(user => {
    // This breaks when API changes field names and data types
    document.getElementById('name').textContent = user.name;
    document.getElementById('email').textContent = user.email;
    // This breaks when nationalities changes from string to array
    document.getElementById('nationalities').textContent 
      = user.nationalities;
  });

ठीक है 🙂

// user-api-v1.json - Version 1 (maintained)
{
  "id": 317,
  "name": "Mr Nimbus",
  "email": "nimbus@atlantis.com",
  "nationalities": "Brazilian,Canadian,Oceanic"
}

// user-api-v2.json - Version 2 
// (new structure, backward compatible)
{
  "id": 317,
  "userId": 317,
  "name": "Mr Nimbus",
  "fullName": "Mr Nimbus",
  "email": "nimbus@atlantis.com",
  "emailAddress": "nimbus@atlantis.com",
  "createdAt": "2018-12-09T18:30:00Z",
  "nationalities": "Brazilian,Canadian,Oceanic"
  "nationalitiesList": ["Brazilian", "Canadian", "Oceanic"]
}

// user-api-v3.json - Version 3 
// (new structure, backward not compatible)
{
  "userId": 317,
  "fullName": "Mr Nimbus",
  "emailAddress": "nimbus@atlantis.com",
  "createdAt": "2018-12-09T18:30:00Z",
  "nationalitiesList": ["Brazilian", "Canadian", "Oceanic"]
}

// client-code-versioned.js
const API_VERSION = 'v1';

fetch(`/api/${API_VERSION}/users/317`)
  .then(response => response.json())
  .then(user => {
    document.getElementById('name').textContent = user.name;
    document.getElementById('email').textContent = user.email;
    // V1 handles comma-separated string
    document.getElementById('nationalities').textContent
      = user.nationalities;
  });

// Or with content negotiation
fetch('/api/users/317', {
  headers: {
    'Accept': 'application/vnd.api+json;version=1'
  }
})
  .then(response => response.json())
  .then(user => {
    document.getElementById('name').textContent = user.name;
    document.getElementById('email').textContent = user.email;
    document.getElementById('nationalities').textContent 
      = user.nationalities;
  });

निगरानी

• [x] आधा स्वचालित

आप इस गंध का पता लगा सकते हैं जब आप एपीआई पाते हैं जो फ़ील्ड नाम बदलते हैं, फ़ील्ड हटाते हैं, या वापसी संगतता को बनाए रखने के बिना डेटा संरचनाओं को बदलते हैं।

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

लापता संस्करण शीर्षक या URL संस्करण योजनाओं के लिए जाँच करें।

रिलीज के बाद क्लाइंट असफलताओं में अचानक स्पीक के लिए त्रुटि लॉग की निगरानी करें।

दिन ️

• एपिस

स्तर

• [x] मध्यवर्ती

क्यों होता है गर्भावस्था ️

एक स्थिर स्थिति बनाए रखना चाहिएनक्शेअपने API अनुबंध और ग्राहक अपेक्षाओं के बीच।

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

आप जो ग्राहक प्राप्त करने की उम्मीद करते हैं और आपके एपीआई क्या प्रदान करता है के बीच एक असंगठितता बनाते हैं।

यह एपीआई वादे और एपीआई वितरण के बीच एक-दूसरे के अनुरूपता को तोड़ता है, जिससे सिस्टम विफलताएं और विश्वास खो जाता है।

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

यह असंगतता त्रुटियों, स्टैंडटाइम, विश्वास की कमी और खराब उपयोगकर्ता अनुभव का कारण बनती है।

एक पीढ़ी

एआई जनरेटर अक्सर इस गंध का निर्माण करते हैं जब आप उन्हें मौजूदा एपीआई को "अनुकूलित" या "अनुकूलित" करने के लिए कहते हैं।

वे वापस संगतता पर विचार किए बिना एपीआई को "अच्छा" बनाने पर ध्यान केंद्रित करते हैं।

आपको मौजूदा फ़ील्ड नामों को बनाए रखने के लिए एआई टूल को स्पष्ट रूप से निर्देशित करने की आवश्यकता है और परिवर्तन करते समय संस्करण जोड़ने के लिए।

वे अक्सर स्थिरता के बजाय साफ डिजाइन को पसंद करते हैं जब तक किस्पष्ट रूप सेअन्यथा कह दिया।

पता लगाने के लिए

एआई जनरेटर इस गंध को ठीक कर सकते हैं जब आप एपीआई संस्करण रणनीतियों के बारे में स्पष्ट निर्देश प्रदान करते हैं।

आपको उन्हें सेमेंटिक संस्करण को लागू करने, वापस संगतता बनाए रखने और अपर्याप्त सुविधाओं के लिए प्रवास पथ बनाने के लिए कहा जाना चाहिए।

कोशिश कीजिए!

याद रखें: एआई सहायक कई गलतियां करते हैं

अनुशंसित परामर्श: परिवर्तनों को तोड़ने से रोकने के लिए एपीआई संस्करण बनाएं

अनुशंसित परामर्श: परिवर्तनों को तोड़ने से रोकने के लिए एपीआई संस्करण बनाएं

चैट

चैट

क्लॉड

क्लॉड

संदेह

संदेह

पायलट

पायलट

जुड़वां

जुड़वां

गहराई

गहराई

लक्ष्य क्या है

लक्ष्य क्या है

ग्रोक

ग्रोक

कुंडली

कुंडली

अंतर्दृष्टि

आपको हमेशा अपने एपीआई को संस्करण करना चाहिए ताकि ग्राहक अनुप्रयोगों को प्रभावित करने से टूटे हुए परिवर्तनों को रोका जा सके।

अपने पहले संस्करण से भी।

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

विघटन परिवर्तन अपरिहार्य हैं, लेकिन उन्हें आपके ग्राहकों को तोड़ना नहीं चाहिए।

हमेशा अपने एपीआई को संस्करण करें, सावधानीपूर्वक अपर्याप्त करें, और अनावश्यक बाधाओं से बचने के लिए सक्रिय रूप से संवाद करें।

https://hackernoon.com/misusing-http-status-codes-wrecks-your-api-monitoring-and-client-logic

https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-iv-7sc3w8n

https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xii

https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxii

https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxiv

https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxv

डिस्काउंटर

गंध मेरा हैराय.

क्रेडिट

फोटो सेGiancarlo Revolledoहैअंधेरे

एपीआई हमेशा के लिए हैं, इसलिए उन्हें सावधानी से डिजाइन करें

एपीआई हमेशा के लिए हैं, इसलिए उन्हें सावधानी से डिजाइन करें

मार्टिन फोलर

यह लेख CodeSmell श्रृंखला का हिस्सा है।