Strategie weryfikacyjne API
Dlaczego potrzebna jest wersioning
API zmienia się szybciej niż klienci. Versioning pozwala na uwalnianie funkcji i edycję błędów bez łamania integracji, ustawia rytuał zmian i sprawia, że ewolucja jest przewidywalna. Klucz: domyślne zmiany addytywne, główni - tylko dla złamań, automatycznych kontroli kompatybilności i przemyślanych zasad zachodu słońca.
Podstawowe zasady
1. Dodatek pierwszy: nowe pola/metody/zdarzenia opcjonalne - ok; deletions and meaning changes - major.
2. MGC (minimalny kontrakt gwarancyjny) jest stabilny; wzbogacanie - poprzez możliwości/'? include = '.
3. Tolerancyjny czytnik: klienci ignorują nieznane pola i prawidłowo przetrwają rozszerzenia enum.
4. Wersioning semantyczny: "MAJOR. DROBNE. PATCH 'do artefaktów, SDK i imprez.
5. Automatyzacja: schemat-diff, lintery i testy CDC blokują zmiany łamania.
Gdzie przechowywać wersję (adresowanie mechaniki)
REST/HTTP
Wersja URI: '/v1/orders '→ łatwa w trasie, wygodna w bramach. Minus - „zaciemnia” ewolucję idei.
Media/Nagłówek: 'Akceptuj: aplikacja/vnd. przykład. rozkazy. v1 + json '- dokładne sterowanie formatem; Trudniej się go pozbyć.
Wersja zapytania: '? api-version = 1 '- wygodne dla A/B, ale łatwe do stracenia w buforach/dziennikach.
Zalecenie: URI dla głównych linii + flagi funkcji/możliwości oraz negacja treści dla drobnych rozszerzeń.
gRPC/Protobuf
Pakiety/usługi: "płatności pakietowe. v1; PaymentsV1 usług; "- wyraźne linie.
Numeracja znacznika nie ulega zmianie; usunięte znaczniki nie mogą być ponownie użyte.
Nowe pola - „opcjonalne”; łamanie → nowe '.v2'.
GraphQL
Schemat bez wyraźnych majorów w adresie URL. Ewolucja poprzez @ zdeprecated i okna migracji; „prawdziwy” major to nowy system punktów końcowych.
Złożoność/głębokość kontroli jest częścią umowy.
Napędzane zdarzeniami (Kafka/NATS/Pulsar)
Nazwa zdarzenia: 'płatność. autoryzowany. v1 'to wersja typu.
Rejestr schematu (Avro/JSON Schema/Protobuf) z trybami kompatybilności (BACKWARD/FORWARD/FULL).
Główne → podwójne emisje „v1” i „v2” dla okresu przejściowego.
Model wersji i polityka zmian
Wersioning semantyczny
MAJOR - łamanie zmian: usuwanie/zmienianie nazwy pól, zmiana klawiszy członkostwa, różne znaczenie statusów, zaostrzenie walidacji.
MINOR - dodatek: nowe pola opcjonalne/punkty końcowe/zdarzenia, nowe wartości enum z czytnikiem tolerancyjnym.
PATCH - poprawki bez zmiany kontraktu i semantyki.
Deprecacja i zachód słońca
Znak przestarzały („Deprecated: true”, „@ deprecated”), opublikować datę wygaśnięcia, alternatywę i przewodnik migracji.
W HTTP - nagłówki „Zachód słońca”, „Deprecacja”; w wydarzeniach - osobny '.deprecation. uwaga ".
Telemetria, aby zdecydować, czy usunąć.
Strategie Versioning według stylu
ODPOCZYNEK
Główne linie na/v1 ,/v2.
MINOR: przedłużenie schematu "? fields = ','? include = '; bezpieczne rozszerzenia enum.
ETag/If-Match i idempotent POST dla spójności bez uszkodzenia.
Błędy - format stabilny ('type', 'code', 'trace _ id').
gRPC
Wprowadzenie nowych usług/metod łamania: " V2. Schwytać '.
Status błędu i semantyka terminowa są częścią umowy; zmiana → nowa metoda/usługa.
Streaming: Zgadzaj się na zamówienie wiadomości i nie zmieniaj ich na drobne.
GraphQL
Dodaj pola i typy swobodnie; deletions - via '@ deprecated' + migration window; duża redesign → nowy schemat ('/graphql-v2 ').
Introspekcja i opisy - must-have dla migracji klientów.
Wydarzenia
Rdzeń vs wzbogacony: rdzeń jest stabilny, wzbogaca się w pobliżu i są wersjonowane oddzielnie.
Klucz podziału nie ulega zmianie w obrębie głównej linii.
Główne migracje - „podwójne emisje” + projekcja/migracja konsumentów.
Sztandary negocjacji i zdolności
Możliwości: klient wysyła 'X-Capabilities: risk_score,price_v2'; serwer odpowiada rozszerzonym widokiem.
Preferuj (HTTP) i wskazówki dotyczące częściowych odpowiedzi.
W gniazdach/strumieniach - wiadomość o uścisku dłoni z listą obsługiwanych rozszerzeń.
Zwolnienie głównych wersji bez bólu
1. RFC/ADR: dlaczego potrzebne jest duże, co się łamie, matryca ryzyka.
2. Dual-run: równoległe uruchomienie 'v1' i 'v2' (podwójne wydawanie wydarzeń, dwie bramki, lusterko ruchu).
3. Adaptery migracyjne: serwery proxy/tłumacze dla ciężkich klientów.
4. Canary: by customer group/topic/tag in gateway.
5. Plan zachodu słońca: daty, komunikacja, stoiska, dane testowe, monitorowanie użytkowania.
Role platformy i infrastruktury
API Gateway/Service Mesh: routing według wersji, nagłówków, ścieżek; prędkość graniczna dla każdej wersji.
Schema Registry & Catalog: Source of Truth for Specs/Schemes with Diffuse History.
CI/CD: линтера (Spectral, Buf), schema-diff (OpenAPI-diff, breaking Buf), CDC (Pact).
Obserwacja: wersja powinna być włączona do dzienników/ścieżek/mierników.
Badanie wersji
Schemat różnicy w PR: złamanie bloku.
Umowy konsumenckie: Dostawca jest testowany pod kątem rzeczywistych umów konsumenckich.
Złote próbki: Odpowiedzi referencyjne na wersje.
E2E canary: porównanie p95/p99, błędy i terminy między wersjami.
Powtórka dla zdarzeń: projekcje są przekształcane do v2 bez rozbieżności.
Migracja danych i baz danych
Dla REST/gRPC: migracje baz danych są koordynowane poprzez rozszerzenie i kontrakt (dodaj kolumnę → zacznij pisać → przełącznik czytania → usuń stare).
w przypadku wydarzeń: podwójne emisje i migracja konsumentów; czasami - powtarzanie dziennika na nowych projekcjach.
Nie robić „duże eksplozje” - podzielone na kroki z rolkami.
Stosunek bezpieczeństwa
Skopy na wersję: poszczególne zakresy OIDC/role dla v1/v2.
Tajemnice/roszczenia dotyczące tokenu są częścią umowy; ich zmiana = major.
PII/PCI - nie należy niepotrzebnie rozszerzać ładunku; nowe pola - z minimalnymi uprawnieniami.
Anty-wzory
Swagger-wash: specyfikacja zaktualizowana, serwer nie (lub odwrotnie).
Ponowne użycie znaczników protobufu to cicha korupcja danych.
Zmiana znaczenia enum bez większego.
Globalne '/v2 '„dla dobra kosmetyków”: wersja bez łamania.
Zapomniałem o zachodzie słońca/metryki użytkowania: nie można bezpiecznie usunąć starej wersji.
Jeden wspólny temat dla różnych majorów: mieszanka zamówień i kluczy.
Lista kontrolna przed zwolnieniem
- Zmiany są dodatkiem lub przygotowywany jest oddzielny główny wiersz.
- Lintery i schema-diff są zielone (łamanie nie czołgało się).
- Zaktualizowany SDK/przykłady/dokumentacja, przypisy zgodności.
- Aktywny tolerancyjny czytnik dla klientów; testowany odchylenie enum.
- Dla głównych - podwójny plan, adaptery, kanaryjskie, daty zachodu słońca i mailing.
- Mierniki/kłody/ścieżki zawierają wersję i segmentację.
- Istnieje stojak i złote zestawy do porównywania v1, w2.
- W przypadku zdarzeń rejestr schematu jest w trybie BACKWARD/FULL, klucze partycji są niezmienione.
Przykładowe szablony
ODPOCZYNEK (URI + negocjacje)
Trasa: '/api/v2/orders/{ id} '
Баболововой: "Prefer: include = items, customer", "X-Capabilities: risk_score'
Deprecacja: "Zachód słońca: 2026-06-30", "Link: ; rel = „alternate” '
Protobuf/gRPC
proto package payments.v2;
service PaymentsV2 {
rpc Capture (CaptureRequestV2) returns (CaptureResponseV2);
}Wydarzenia
"płatność. schwytany. v2 „(rdzeń) i” płatność. wzbogacony. v2 "(szczegóły).
W okresie przejściowym producent otrzymuje oznaczenie „v1” i „v2”.
NAJCZĘŚCIEJ ZADAWANE PYTANIA
Kiedy dokładnie jest potrzebne '/v2 '?
Gdy niezmienne/semantyczne zmiany, pola/metody są usuwane, format identyfikatorów, klucz partycji, SLA/czasy zmieniają się tak, że klienci łamią.
Czy możesz żyć bez wyraźnej wersji w REST?
Tylko dla małych systemów. W przypadku integracji zewnętrznych wyraźne główne linie są lepsze.
Jak długo utrzymać przestarzałą wersję?
Zależy od ekosystemu. Dla partnerów zewnętrznych, zwykle 6-12 miesięcy z wczesnym powiadomieniem i kanarka.
W jaki sposób wersioning zdarzeń różni się od API?
Wydarzenia - tylko dodatek; nowa semantyka = nowy typ '.v2' i podwójna emisja. Klucz podziału jest częścią umowy.
Wynik
Strategie wersioning to procesy i narzędzia: domyślna ewolucja addytywna, wyraźne główne linie, funkcje negocjacyjne, podwójne działanie i zachód słońca. Dodaj automatyczne kontrole zgodności, telemetrię użytkowania i dyscyplinę dokumentacji - a Twoje interfejsy API szybko się rozwijają, bez „nocnych migracji” i nieoczekiwanych spadków u klientów.