Code Smell 303 - Kako sprečiti razbijanje postojećih klijenata kada napravite promene

Kada razbijete API-je bez upozorenja, razbijete povjerenje

TL;DR: Trebali biste da verzišete svoje API-je kako biste spriječili slom postojećih klijenata kada napravite promene.

TL;DR: Trebali biste da verzišete svoje API-je kako biste spriječili slom postojećih klijenata kada napravite promene.

Problemi

Klijent aplikacije crashes
Neuspeh integracije
Kršenje principa najmanje iznenađenja
Dolazak
Slomljeno poverenje
Potrebni rollbacks za ugradnju
Potrošeno vreme za razvoj
Degradacija korisničkog iskustva

Rešenja

Dodavanje semantičke verzije
Uvođenje retroaktivne kompatibilnosti
Stvaranje upozorenja o deprecijaciji
Stvaranje Roadmapa
Koristite sadržaj pregovaranja
Održavanje paralelnih verzija
Ranije obavijestite o promjenama
Postupno smanjite karakteristike
Dokument koji prelomi promene jasno
Provjerite deprecated parametre sa loggingom
Test nove verzije temeljito
Uklanjanje deprecirane funkcionalnosti nakon zalaska sunca

Kontekst

Kada modificirate API-je bez pravilnog izdavanja verzija, kreirate promene koje utiču na sve postojeće klijente.

Prisiljavate potrošače da odmah ažuriraju svoj kod ili se suočavaju sa sistemskim kvarovima.

Prekršite implicitni ugovor između pružatelja API-ja i potrošača.

Moderan softver uvelike se oslanja na stabilnost API-ja, a uvođenje promjena bez upozorenja može stvoriti kaskadne neuspehe u zavisnim sistemima.

To je danas važnije nego ikad od tadamnoge IA grade svoja rešenja koristeći postojeće API dokumentacije.

Kada ažurirate API bez održavanja retroaktivne kompatibilnosti, rizikujete da prekinete sve aplikacije koje ovise o njemu.

To stvara nestabilnost, frustracije i skupe popravke za korisnike.

Ljudi često tolerirajuNedostaciu novim funkcionalnostima, ali nikada prethodno stabilno ponašanje nije prekinuto.

Pravilna verzija osigurava glatke tranzicije i održava pouzdanost vašeg sustava.

Sample kod

Pogrešno 🙂

// user-api-v1.json - Original API response
{
  "id": 317,
  "name": "Mr Nimbus",
  "email": "[email protected]",
  "nationalities": "Brazilian,Canadian,Oceanic"
}

// Later changed to this without versioning:
{
  "userId": 317,
  "fullName": "Mr Nimbus", 
  "emailAddress": "[email protected]",
  "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;
  });

Right 👉

// user-api-v1.json - Version 1 (maintained)
{
  "id": 317,
  "name": "Mr Nimbus",
  "email": "[email protected]",
  "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": "[email protected]",
  "emailAddress": "[email protected]",
  "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": "[email protected]",
  "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;
  });

Detekcija

[x] Poluautomatski

Ovaj miris možete otkriti kada pronađete API-je koji mijenjaju imena polja, uklanjaju polja ili mijenjaju strukturu podataka bez održavanja retroaktivne kompatibilnosti.

Potražite aplikacije klijenta koje se prekidaju nakon implementacije API-ja.

Provjerite da li nedostaju naslovi verzija ili sheme za verziju URL-a.

Praćenje dnevnika grešaka za iznenadne pike u neuspjehu klijenta nakon izdavanja.

U toku dana ️

Apis

Nivo

[x] Posrednik

Zašto je bijecija važna ️

Potrebno je održati stabilanMapaizmeđu vašeg API ugovora i očekivanja klijenata.

Kada razbijete ovoBijecijapromjenom API-ja bez verziranja kršite temeljni princip da se klijenti mogu osloniti na dosljedne sučelje.

You create a mismatch between what clients expect to receive and what your API provides.

To prekida jedan-na-jedan korespondenciju između API obećanja i API isporuke, što dovodi do neuspjeha sistema i gubitka poverenja.

Kada prekinete mapiranje između vašeg API-ja i poslovne logike koju predstavlja, klijenti ne mogu pouzdano komunicirati sa vašim sistemom.

Ova neusklađenost dovodi do nedostataka, prekida vremena, nedostatka poverenja i lošeg korisničkog iskustva.

Ova generacija

AI generatori često stvaraju ovaj miris kada ih zamolite da "izboljeđuju" ili "aktualiziraju" postojeće API-je.

Oni se fokusiraju na to da API bude "bolji" bez razmatranja retroaktivne kompatibilnosti.

Potrebno je eksplicitno uputiti AI alate za održavanje postojećih imena polja i dodati verziju prilikom izrade promena.

Često preferiraju čisti dizajn u odnosu na stabilnost, osim akoEksplicitnoRekli su drugačije.

Detekcija

AI generatori mogu popraviti ovaj miris kada pružite jasne upute o strategijama za verziju API-ja.

Trebali biste ih zamoliti da implementiraju semantičko verzijiranje, održavaju retroaktivnu kompatibilnost i kreiraju migracijske staze za deprecirane funkcije.