Όταν σπάτε τα API χωρίς προειδοποίηση, σπάτε την εμπιστοσύνη
TL;DR: Θα πρέπει να εκδόσετε την έκδοση των API σας για να αποτρέψετε την παραβίαση των υφιστάμενων πελατών όταν κάνετε αλλαγές.
TL;DR: Θα πρέπει να εκδόσετε την έκδοση των API σας για να αποτρέψετε την παραβίαση των υφιστάμενων πελατών όταν κάνετε αλλαγές.
Προβλήματα
- Εφαρμογές πελατών καταρρέουν
- Η αποτυχία της ολοκλήρωσης
- Παραβίαση της αρχής της ελάχιστης έκπληξης
- downtime
- Σπασμένη εμπιστοσύνη
- Απαιτούνται rollbacks
- Χάθηκε χρόνος ανάπτυξης
- Υποβάθμιση της εμπειρίας χρήστη
Λύσεις
- Εισαγωγή σε σημασιολογική εκδοχή
- Εφαρμογή της αντίστροφης συμβατότητας
- Δημιουργία προειδοποιήσεων απομείωσης
- Δημιουργία οδικών χαρτών
- Χρησιμοποιήστε τη διαπραγμάτευση περιεχομένου
- Παράλληλες εκδόσεις
- Ενημερώστε τις αλλαγές νωρίς
- Αφαίρεση χαρακτηριστικών σταδιακά
- Το έγγραφο σπάει τις αλλαγές σαφώς
- Ελέγξτε τις εξαντλημένες παραμέτρους με logging
- Δοκιμάστε προσεκτικά τις νέες εκδόσεις
- Αφαίρεση εξαντλημένων λειτουργιών μετά το ηλιοβασίλεμα
ΠΕΡΙΓΡΑΦΟ
Όταν τροποποιείτε 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] Ημι-αυτόματη
Μπορείτε να ανιχνεύσετε αυτή τη μυρωδιά όταν βρείτε API που αλλάζουν ονόματα πεδίων, αφαιρούν πεδία ή αλλάζουν δομές δεδομένων χωρίς να διατηρούν αντίστροφη συμβατότητα.
Αναζητήστε εφαρμογές-πελάτες που διακόπτουν μετά την ανάπτυξη του API.
Ελέγξτε για λείπουν επικεφαλίδες εκδόσεων ή προγράμματα εκδόσεων URL.
Παρακολουθήστε τα αρχεία καταγραφής σφαλμάτων για ξαφνικές αιχμές σε αποτυχίες του πελάτη μετά από εκδόσεις.
️️
- ΑΠΙ
Επίπεδα
- [x] Μέσος όρος
Γιατί είναι σημαντική η προετοιμασία ️
Πρέπει να διατηρήσετε σταθερήΧάρτηςμεταξύ της σύμβασης API και των προσδοκιών του πελάτη.
Όταν σπάσεις αυτό τοΟΜΟΡΦΩΣΗαλλάζοντας το API χωρίς εκδόσεις, παραβιάζετε τη θεμελιώδη αρχή ότι οι πελάτες μπορούν να βασίζονται σε συνεπείς διεπαφές.
Δημιουργείτε μια ασυμφωνία μεταξύ αυτού που οι πελάτες αναμένουν να λάβουν και αυτού που παρέχει το API σας.
Αυτό σπάει την αλληλογραφία μεταξύ των υποσχέσεων API και της παράδοσης API, οδηγώντας σε αποτυχίες του συστήματος και απώλεια εμπιστοσύνης.
Όταν σπάσετε τη χαρτογράφηση μεταξύ του API και της επιχειρηματικής λογικής που αντιπροσωπεύει, οι πελάτες δεν μπορούν να αλληλεπιδρούν αξιόπιστα με το σύστημά σας.
Αυτή η αναντιστοιχία οδηγεί σε ελαττώματα, χρόνους απενεργοποίησης, έλλειψη εμπιστοσύνης και κακή εμπειρία χρήστη.
Η γενιά μας
Οι γεννήτριες AI συχνά δημιουργούν αυτή τη μυρωδιά όταν τους ζητάτε να «βελτιώσουν» ή να «ενημερώσουν» τα υπάρχοντα API.
Εστιάζουν στο να κάνουν το API "καλύτερο" χωρίς να εξετάζουν την αντίστροφη συμβατότητα.
Πρέπει να δίνετε ρητές οδηγίες στα εργαλεία AI για να διατηρήσετε τα υπάρχοντα ονόματα πεδίων και να προσθέσετε εκδόσεις όταν κάνετε αλλαγές.
Συχνά προτιμούν τον καθαρό σχεδιασμό έναντι της σταθερότητας, εκτός ανΕΞΑΙΡΕΤΙΚΑΕίπε το αντίθετο.
Η ανίχνευση
Οι γεννήτριες AI μπορούν να διορθώσουν αυτή τη μυρωδιά όταν παρέχετε σαφείς οδηγίες σχετικά με τις στρατηγικές έκδοσης του API.
Θα πρέπει να τους ζητήσετε να εφαρμόσουν τη σημασιολογική έκδοση, να διατηρήσουν την αντίστροφη συμβατότητα και να δημιουργήσουν διαδρομές μετεγκατάστασης για εξαντλημένα χαρακτηριστικά.
Δοκιμάστε το!
Θυμηθείτε: Οι βοηθοί AI κάνουν πολλά λάθη
Προτεινόμενη προειδοποίηση: Δημιουργία έκδοσης API για την αποφυγή τροποποιήσεων
Προτεινόμενη προειδοποίηση: Δημιουργία έκδοσης API για την αποφυγή τροποποιήσεων
|
Without Proper Instructions |
With Specific Instructions |
|---|---|
Συμπέρασμα
Θα πρέπει πάντα να εκδίδετε εκδόσεις των 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
Αποκάλυψη
Η μυρωδιά είναι δική μουΓνώμη.
Πιστωτικές
Φωτογραφία απόΤζιανκάρλο ΡεβόλεδοείναιΜυστηριώδης
Τα API είναι για πάντα, οπότε σχεδιάστε τα προσεκτικά
Τα API είναι για πάντα, οπότε σχεδιάστε τα προσεκτικά
Μάρτιν Φόουλερ
Αυτό το άρθρο είναι μέρος της σειράς CodeSmell.
