Udostępnij za pośrednictwem

Tworzenie, ewoluowanie i przechowywanie wersji mikrousługowych interfejsów API i kontraktów

Wskazówka

Ta treść jest fragmentem eBooka "Architektura mikrousług .NET dla konteneryzowanych aplikacji .NET", dostępnego na .NET Docs lub jako bezpłatny plik PDF do pobrania i czytania w trybie offline.

Pobierz plik PDF

Miniatura okładki eBooka „Architektura mikrousług platformy .NET dla konteneryzowanych aplikacji platformy .NET”.

Interfejs API mikrousług to kontrakt między usługą a jej klientami. Będziesz w stanie rozwijać mikrousługę niezależnie tylko wtedy, gdy nie przerywasz kontraktu interfejsu API, dlatego kontrakt jest tak ważny. Jeśli zmienisz kontrakt, będzie to miało wpływ na aplikacje klienckie lub usługę API Gateway.

Charakter definicji interfejsu API zależy od używanego protokołu. Jeśli na przykład używasz komunikatów, takich jak AMQP, interfejs API składa się z typów komunikatów. Jeśli używasz usług HTTP i RESTful, interfejs API składa się z adresów URL oraz formatów żądań i odpowiedzi JSON.

Jednak nawet jeśli starannie przemyślisz swój początkowy kontrakt, interfejs API usługi będzie musiał zmieniać się z czasem. W takim przypadku — a zwłaszcza jeśli interfejs API jest publicznym interfejsem API używanym przez wiele aplikacji klienckich — zazwyczaj nie można wymusić uaktualnienia wszystkich klientów do nowego kontraktu interfejsu API. Zazwyczaj konieczne jest przyrostowe wdrożenie nowych wersji usługi w taki sposób, aby zarówno stare, jak i nowe wersje kontraktu usługi działały jednocześnie. Dlatego ważne jest, aby mieć strategię przechowywania wersji usługi.

Gdy zmiany interfejsu API są małe, tak jak w przypadku dodawania atrybutów lub parametrów do interfejsu API, klienci korzystający ze starszego interfejsu API powinni przełączać się i pracować z nową wersją usługi. Może być możliwe podanie wartości domyślnych dla wszystkich brakujących atrybutów, które są wymagane, a klienci mogą ignorować wszelkie dodatkowe atrybuty odpowiedzi.

Czasami jednak należy wprowadzić poważne i niezgodne zmiany w interfejsie API usługi. Ponieważ nie można wymusić natychmiastowego uaktualnienia aplikacji klienckich lub usług do nowej wersji, usługa musi obsługiwać starsze wersje interfejsu API przez pewien okres. Jeśli używasz mechanizmu opartego na protokole HTTP, takiego jak REST, jednym z podejść jest osadzanie numeru wersji interfejsu API w adresie URL lub w nagłówku HTTP. Następnie można zdecydować między wdrożeniem obu wersji usługi jednocześnie w ramach tego samego wystąpienia usługi lub wdrożeniem różnych wystąpień, które obsługują wersję interfejsu API. Dobrym podejściem do tej funkcjonalności jest wzorzec mediatora (na przykład biblioteka MediatR) umożliwiający oddzielenie różnych wersji implementacji do niezależnych procedur obsługi.

Na koniec, jeśli korzystasz z architektury REST, Hypermedia jest najlepszym rozwiązaniem do zarządzania wersjami usług i umożliwienia ewolucji interfejsów API.

Dodatkowe zasoby

PoprzedniNastępny