Kompatybilność i aktualizacje API
1) Podstawy kompatybilności
Dodatek-pierwszy: dodać nowy bez łamania starych (nowe opcjonalne pola/punkty końcowe, nowe wartości enum).
Stabilne umowy: „co obiecano w specyfikacji utworów;” Zachowanie udokumentowane.
Wstecz> Naprzód: priorytet kompatybilności wstecznej; do przodu jest dozwolone przez czytniki tolerancyjne.
Dokumenty są podstawowe: jedynym źródłem prawdy jest wersja rejestru systemu (OpenAPI/AsyncAPI/Proto).
Wyraźna ewolucja: łamanie - tylko poprzez nową główną wersję i przewodnik migracyjny.
2) Taksonomia zmian
2. 1 Kompatybilny (MINOR/PATCH)
Dodaj opcjonalne pola/nagłówki, nowe punkty końcowe, parametry zapytania z domyślnymi.
Zwiększenie limitów ('page _ size', TTL), wyjaśnienie błędów bez zmiany kodów/semantyki.
Dodaj wartości enum, jeśli klienci ignorują „nieznane” (tolerancyjny czytnik).
2. 2 Dwuznaczne (behawioralne)
Zmiana domyślności, kolejność sortowania, cienkie czasy, kwoty - może „łamać” logikę biznesową. Wymaga ogłoszenia RFC + i kanarów.
2. 3 Łamanie (MAJOR)
Zmień nazwę/usuń pola, zmień typ/format, zastąpić kody błędów, odwrócić niezgodność umów/systemów uwierzytelniania.
3) Polityka weryfikacyjna
Strategia: „wersioning ścieżki” („/v1 ”, „/v2”).
Minor/patch: „dodać, nie łamać”.
Datowane nagłówki (opcjonalnie): 'X-API-Version-Date' dla miękkich zmian przyrostowych.
Typy mediów (Op.): "Akceptuj: aplikacja/vnd. acme. v1 + json 'do drobnej granulacji.
4) Depresje i zachód słońca
4. 1 Nagłówki komunikacyjne
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </guides/reports-v2>; rel="successor-version"4. 2 Polecenie odstąpienia
1. Ogłoszenie w portalu/lista mailingowa/notatki SDK wydania.
2. Okno ostrzegawcze ≥ 90-180 dni.
3. Statusy w desce adopcyjnej.
4. Po zachodzie słońca - 410 Odszedł lub „tylko do odczytu” tryb na okres łaski, jeśli uzgodnione.
5) Migracja i współistnienie wersji
Podwójne pisanie/podwójne odczytywanie w okresie przejściowym i pojednanie ze sprawozdaniami.
Adaptery (tymczasowe): brama konwersji starego ładunku → nowe systemy; żywotność adaptera jest ograniczona.
Pomoc SDK: wydania, które obsługują obie wersje, z ostrzeżeniami o zmniejszeniu (1 czas na proces).
Flagi funkcji: włączenie nowych semantyków zgodnie z listą kluczy/najemców.
6) Kompatybilność do tyłu i do przodu
6. 1 Wsteczny (starzy klienci i nowy serwer)
Nie zmieniaj formatów/obowiązkowych.
Nowe pola są tylko opcjonalne.
Błędy - old 'error _ code', dodaj nowe kody, nie zastępuj.
6. 2 Naprzód (nowi klienci i stary serwer)
Sprawdź możliwości za pomocą 'OPTIONS '/'/versions'.
Zachowanie Grace: Klient musi tolerować brakujące cechy.
7) Umowy i automatyczne kontrole
Rejestr: przechowywać wersje schematu; PR digs → breaking/non-breaking reports.
Linter: nazwy/typy, idempotencja, paginacja, stabilne kody.
CDC (Consumer-Driven Contracts): Testy integratora w CI dostawcy (Pakt i analogi).
Bramka: PR jest zablokowany podczas łamania bez 'major bump '/RFC.
yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml8) Przedłużenie kanaryjskie i odwrotne
Kanaryjski: 10% → 25% → 50% → 100% ruchu; auto-rollback na degradacji SLO (5xx/latency/429).
Klucze beta: dostęp do nowych wersji według listy dopuszczalnej.
Zwolnienie zamrożenie: błąd-budżet podczas spalania.
Analityka akceptacji: udział ruchu/klientów w nowej wersji, czas migracji.
9) Szczegółowa zgodność: błędy, paginacja, idempotencja
9. 1 Błędy
Nie zmieniaj statusów HTTP w istniejących skryptach.
„error _ code” - stabilny; nowe kody tylko dodać.
'application/problem + json' jest jednym formatem.
9. 2 Paginacja
Przełącz na kursor/klawisz = MINOR, jeśli obsługiwany jest stary 'offset/limit'.
Dokumentuj rodzaj „(updated_at,id)” i stabilność kursora.
9. 3 Idempotencja
Do napisania - 'Idempotency-Key' + '409 IDEMP_REPLAY' w przypadku konfliktu.
Migracja nie powinna zmieniać semantyki idempotencji.
10) Transformacje bramowe (w stosownych przypadkach)
Mapa v1 → v2 pola, normalizacja błędów, konwersja danych/formatów pieniędzy.
Poręcze: transformacje są przezroczyste i logowalne; nie ukrywać łamania, ale używać jako ograniczony w czasie most.
11) Komunikacja i portal
Changelog i inne produkty („dodane/zmienione/deprecated/deleted/fixed”).
Karta wersji: status (beta/GA/zdeprecated), data zachodu słońca, linki do przewodników.
Haki internetowe powiadomień: "deprecacja. uwaga „,” wersja. zwolniony „,” plan. zmiana ".
Notatki do wydania SDK + baner portalu.
12) Wskaźniki sukcesu
Wskaźnik adopcji v2 (na żądanie/klienta).
Incydenty wsteczne.
Mix błędów (4xx/5xx/429 akcji) przed/po zwolnieniu.
Mediana czasu do przyjęcia.
Obciążenie pomocnicze (bilety/tydzień).
Koszt do obsługi.
13) Szablony i przykłady
13. 1 Tytuły wersji i dekrety
X-API-Version: v1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </v2/reports>; rel="successor-version"13. 2 Polityka wersji (fragment YAML)
yaml versioning:
strategy: "path"
compatibility:
minor: "additive-only"
patch: "bugfix/perf, no schema change"
deprecation:
min_notice_days: 120 rollout:
canary_steps: [10,25,50,100]
rollback_checks: ["5xx_rate","p95_latency","429_rate","adoption"]13. 3 OpenAPI Field Append Compatible
yaml components:
schemas:
Report:
type: object required: [id, createdAt]
properties:
id: { type: string }
createdAt: { type: string, format: date-time }
cursor: { type: string, description: "optional for v1. 2+" } # additive14) Lista kontrolna wydania (MINOR/MAJOR)
NIELETNI
- DIFF: non-breaking, linter green
- Aktualizacja dokumentacji/SDK (przykłady/kodeki)
- Canary + auto-SLO rollback
- Comm Plan, strona portalu
- Tablice odbioru i błędu
MAJOR
- RFC/ADR, data zachodu słońca i ≥ 90 okien -180 dni
- Most i przewodnik wędrowny v1 i v2
- Podwójne zapisy/odczyty i pojednania
- SDK z obydwoma wpisami API +
- Pilot z kluczowymi integratorami
15) Plan realizacji (3 iteracje)
1. Fundacja (2 tygodnie):
Rejestr schematów, łączy i auto-diff w CI; polityka kompatybilności; Tytuły „Deprecation/Sunset”.
2. Zarządzane wydania (3-4 tygodnie):
Kanarki, flagi funkcyjne, wpisy SLO; portal wersji; Wersje SDK z obsługą 2 gałęzi.
3. Automatyzacja i skala (ciągła):
Testy CDC konsumentów w CI, prognoza zachodu słońca na temat trendów adopcyjnych, automatyczne powiadomienia i przypomnienia.
16) Mini-FAQ
Czy mogę zmienić typ pola bez większego?
Nie, nie jest. Nawet „stroka → chislo” łamie. Wprowadź nowe pole, stare jest zdeprecate.
Enum: czy można dodać wartości?
Tak, jeśli klienci są tolerancyjni. W przeciwnym razie - najpierw alert i beta.
Ile trzymać starą wersję?
Dotychczas utrzymano przyjęcie nowego ≥ 95%. Ustal termin w polityce.
Razem
Kompatybilność API jest dyscypliną: podejście addytywne, formalne schematy i siatki, uwolnienia kanarkowe, wyraźne spadki i zarządzane migracje. Skonsoliduj politykę zmian, automatyzuj kontrole i komunikację, mierz adopcję - a Twoje aktualizacje przestaną łamać klientów, a szybkość ewolucji wzrośnie bez utraty niezawodności.