Πώς εκδίδεις έκδοση API και διατηρείς την οπισθοχωρητική συμβατότητα σε υπηρεσίες;

Question

Accepted Answer

Επειδή οι υπηρεσίες αναπτύσσονται ανεξάρτητα, δεν μπορείς ποτέ να υποθέσεις ότι οι καλούντες αναβαθμίζονται σταθμευμένα. **Έκδοση API** συν **οπισθοχωρητική συμβατότητα** επιτρέπει στους παραγωγούς να εξελίσσονται χωρίς να σπάσουν υπάρχοντες καταναλωτές.

## Στρατηγικές έκδοσης

| Στρατηγική | Παράδειγμα |
|---|---|
| διαδρομή URI | `GET /v2/orders/42` |
| κεφαλίδα | `Accept: application/vnd.api.v2+json` |
| εξέλιξη σχήματος | προσθήκη πεδίων, ποτέ κατάργηση/μετονομασία |

## Προτίμησε προσθετικές (μη-σπάζουσες) αλλαγές

```text
NON-BREAKING (safe):
  ✓ add a new optional field
  ✓ add a new endpoint
  ✓ add a new enum value (if clients tolerate unknowns)

BREAKING (needs a new version):
  ✗ remove or rename a field
  ✗ change a type or make a field required
  ✗ change semantics of an existing field
```

## Protobuf είναι φιλικό για αυτό

```proto
message Order {
  string id = 1;
  double total = 2;
  string currency = 3;  // NEW field 3 — old clients ignore it safely
}
```

Οι αριθμοί πεδίων, όχι τα ονόματα, ορίζουν τη μορφή σύρματος, επomένως η προσθήκη πεδίων είναι οπισθοχωρητικά συμβατή.

## Κύκλος ζωής

```text
Release v2 ─▶ run v1 + v2 together ─▶ migrate consumers ─▶ deprecate v1 ─▶ remove v1
```

## Παγίδα

Μην αφαιρέσεις ποτέ μια έκδοση ενώ πραγματικός κίνηση χρησιμοποιεί ακόμα. Παρακολούθησε τη χρήση πριν την αποχώρηση.

## Γιατί έχει σημασία

Η ανεξάρτητη αναπτυξιμότητα λειτουργεί μόνο εάν ένας παραγωγός μπορεί να αποστείλει μια αλλαγή χωρίς να συντονίσει την κυκλοφορία κάθε καταναλωτή.

Σχεδιασμός για προσθετικές αλλαγές και υποστήριξη παλιών εκδόσεων κατά τη μετεγκατάσταση είναι αυτό που διατηρεί αυτή την ανεξαρτησία αντί να εξαναγκάζει εύθραυστες αναβαθμίσεις big-bang.

διαδρομή URI	`GET /v2/orders/42`
κεφαλίδα	`Accept: application/vnd.api.v2+json`
εξέλιξη σχήματος	προσθήκη πεδίων, ποτέ κατάργηση/μετονομασία