177 قراءة٪ s

الكود 303 - كيفية منع إزعاج العملاء الحاليين عند إجراء التغييرات

بواسطة Maximiliano Contieri5m2025/06/13
Read on Terminal Reader

طويل جدا؛ ليقرأ

يجب عليك إصدار API الخاص بك لتجنب إزعاج العملاء الحاليين عند إجراء التغييرات
featured image - الكود 303 - كيفية منع إزعاج العملاء الحاليين عند إجراء التغييرات
Maximiliano Contieri HackerNoon profile picture

عندما تفكك API دون إشعار، يمكنك تفكيك الثقة

TL;DR: يجب عليك إصدار API الخاص بك لتجنب إزعاج العملاء الحاليين عند إجراء التغييرات.

TL;DR: يجب عليك إصدار API الخاص بك لتجنب إزعاج العملاء الحاليين عند إجراء التغييرات.

مشكلات

  • التطبيقات المستخدمة تحطم
  • فشل التكامل
  • انتهاك قواعد التفاؤل الأدنى
  • Downtime
  • الثقة القاتلة
  • لعبة Rollbacks المطلوبة
  • وقت التطوير ضائع
  • تراجع تجربة المستخدم

حلول

  1. اشترى نسخة Semantic
  2. إدخال التوافق الخلفي
  3. إنشاء تحذير من الاكتئاب
  4. إنشاء خطوط الطريق
  5. الاستفادة من التفاوض على المحتوى
  6. إرسال إصدارات متوازنة
  7. تحديد التغيرات في وقت مبكر
  8. إزالة الخصائص تدريجياً
  9. بيانات تغير التغييرات بشكل واضح
  10. تحقق من النماذج المفقودة مع التسجيل
  11. اختبار إصدارات جديدة بشكل كامل
  12. إزالة الوظائف المفقودة بعد الزوال

السياق

عندما تقوم بتعديل API دون تحديد الإصدار الصحيح، يمكنك إنشاء التغييرات التي تؤثر على جميع العملاء الحاليين.


أنت تدفع المستهلكين إلى تحديث رمزهم على الفور أو تواجه مشكلات في النظام.


أنت تقف مع العقد المباشر بين الموردين API والمستهلكين.


وتعتمد البرمجيات الحديثة بشكل كبير على استقرار API ، ويمكن إدخال التغييرات المتكررة دون تحذير من أن تكون قادرة على خلق مشاكل في جميع أنحاء الأنظمة المعتمدة.


هذا مهم اليوم أكثر من أي وقت مضىالعديد من الشركات المصنعة للهواتف الذكية تطبق حلولها باستخدام توثيق API الحالي..


عندما تقوم بتحديث 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] الذكور الذكور

يمكنك اكتشاف هذا الرائحة عند العثور على APIs التي تغير أسماء المجالات، أو إزالة المجالات، أو تغيير هيكلات البيانات دون الحفاظ على التوافق الخلفي.


ابحث عن التطبيقات المستخدمة التي تنتهي بعد تطبيقات API.


تحقق من أخطاء الإصدارات المفقودة أو خطط إصدارات URL.


مراقبة سجلات الأخطاء للارتفاعات المفاجئة في أخطاء المستخدم بعد الإصدارات.

اليوم ️

  • APIs

مستوى

  • [x] المتوسط

لماذا هو مهم ️

يجب عليك الحفاظ على مستقرخريطةبين عقد API الخاص بك ومتطلبات العملاء.


عندما تقطع هذاالتفاعلمن خلال تغيير API دون إصدارات، أنت تتناقض مع المبادئ الأساسية التي يمكن للمستخدمين الاعتماد عليها في وسائل الاتصال المتوافقة.


يمكنك إنشاء تناقض بين ما يتوقع العملاء الحصول عليه وما يقدم API الخاص بك.


هذا يفقد الترابط بين التزامات API و توزيع API ، مما يؤدي إلى فشل النظام وفقدان الثقة.


عندما تفكك الخرائط بين API الخاص بك واللوجستية التجارية التي تعكسها، فإن العملاء لا يمكنهم التفاعل مع النظام بشكل موثوق به.


هذا الاختلاف يؤدي إلى أخطاء، وقت إغلاق، نقص الثقة، وتجربة مستخدمة سيئة.

أجيال

غالبًا ما يخلق منتجات الذكاء الاصطناعي هذه الرغبة عندما تتطلب منهم "تعزيز" أو "تحديث" API موجودة.


إنها تركز على جعل API "أفضل" دون النظر في التوافق المفاجئ.


تحتاج إلى تدريب أدوات الذكاء الاصطناعي بشكل واضح على الحفاظ على أسماء المجالات الموجودة وإضافة إصدارات عند إجراء التغييرات.


غالباً ما يفضلون التصميم النظري على الاستقرار، إلا إذابالتفصيلأخبرني غيره

تقييم

يمكن للمنشآت الذكية إصلاح هذه الرطوبة عند توفير إرشادات واضحة حول استراتيجيات إصدار API.


ينبغي أن تتطلب منهم إدخال إصدارات معيّنة، والحفاظ على التوافق الخلفي، وبناء مسارات التهجير للميزات المفقودة.

احرص على ذلك!

تذكر: المساعدات الذكية تجعل الكثير من الأخطاء

الترجمة الموصى بها: إنشاء نسخة API لتجنب إزالة التغييرات

الترجمة الموصى بها: إنشاء نسخة API لتجنب إزالة التغييرات

Without Proper Instructions

With Specific Instructions

ChatGPT

ChatGPT

Claude

Claude

Perplexity

Perplexity

Copilot

Copilot

Gemini

Gemini

DeepSeek

DeepSeek

Meta AI

Meta AI

Grok

Grok

Qwen

Qwen

كوتشي

كوتشي

كوليد

كوليد

مخاوف

مخاوف

طيار

طيار

اثنين

اثنين

DeepSeek

DeepSeek

الهدف من

الهدف من

غروس

غروس

كوين

كوين

النتيجة

يجب عليك دائمًا إصدار API الخاص بك من أجل منع التغيير من التأثير على التطبيقات المستخدمة.


حتى من النسخة الأولى.


عند الحفاظ على عقود ثابتة من خلال إصدارات مناسبة، يمكنك بناء الثقة مع مستخدمي API وتتيح تطورًا سليمًا من أنظمةك.


التغيرات المزمنة، ولكنها لا ينبغي أن تفقد عملاءك.


دائمًا نسخة 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

Disclaimer

الرائحة الكريهة هي مننظرية.

الائتمان

صورة منجانيارلو RevolledoذاكUnplash


API هي إلى الأبد، لذلك تصميمها بعناية

API هي إلى الأبد، لذلك تصميمها بعناية

مارتن Fowler


هذه المقالة جزء من سلسلة CodeSmell.


Trending Topics

blockchaincryptocurrencyhackernoon-top-storyprogrammingsoftware-developmenttechnologystartuphackernoon-booksBitcoinbooks