Jaki diagram wybrać do backendu i API?

28 października 2026

Diagram przedstawia architekturę mikroserwisów: aplikacje klienckie (mobilna i webowa) komunikują się z trzema mikroserwisami w chmurze.

Projektujesz endpoint zamówień i po chwili masz na ekranie kilka strzałek, trzy usługi oraz bazę danych, ale nadal nie widać, co właściwie dzieje się po kliknięciu „Kupuję”. Do backendu zwykle dobiera się diagram do pytania: C4 pokazuje strukturę systemu, diagram sekwencji przebieg żądania, a model danych relacje w bazie, choć jeden widok rzadko odpowiada na wszystko.

Diagram przedstawia różne rodzaje diagramów przepływu danych w systemie SmartGym, w tym silniki rekomendacji i reguł.

Dobry diagram pokazuje jedną warstwę systemu naraz

  • C4 przedstawia system w kilku poziomach szczegółowości, od otoczenia po komponenty.
  • Diagram sekwencji pomaga prześledzić kolejność wywołań API, usług i baz danych.
  • ERD porządkuje encje oraz relacje w modelu danych.
  • Diagram wdrożenia pokazuje, gdzie działają usługi i infrastruktura.
  • OpenAPI opisuje kontrakt HTTP, ale nie zastępuje diagramu architektury.

Rodzaje diagramów dobieraj do pytania, nie do narzędzia

Wyobraź sobie, że nowa osoba w zespole pyta, gdzie trafia żądanie z aplikacji i co dzieje się z nim dalej. Diagram architektury powinien odpowiedzieć na to pytanie bez konieczności czytania całego repozytorium. Jeden widok, jeden cel zwykle działa lepiej niż plansza z każdą klasą, tabelą i usługą.

W backendzie spotkasz przede wszystkim diagramy struktury, przepływu i danych. Różnią się tym, co uwypuklają: statyczne połączenia między elementami, kolejność komunikatów albo kształt przechowywanych informacji. Uważam, że właśnie ten wybór, a nie styl graficzny, decyduje, czy ktoś szybko zrozumie diagram.

C4 prowadzi od obrazu systemu do jego elementów

Gdy odbiorcy nie znają jeszcze projektu, zacznij od szerokiego kadru. Diagram kontekstu systemu pokazuje aplikację jako całość, użytkowników i zewnętrzne systemy, z którymi się komunikuje. Przykładowo sklep internetowy może mieć na nim klienta, platformę sklepu, operatora płatności i firmę kurierską, bez rozrysowywania wnętrza backendu.

Poziom kontenerów przybliża obraz i pokazuje główne uruchamialne części, takie jak aplikacja webowa, API, baza danych czy broker wiadomości. Diagram komponentów schodzi jeszcze niżej, do odpowiedzialności wewnątrz wybranego kontenera. Model C4 opisuje te poziomy jako kontekst, kontenery, komponenty i kod, ale podkreśla, że nie trzeba tworzyć wszystkich, jeśli prostszy zestaw wystarcza.

Tu łatwo przesadzić: diagram komponentów szybko staje się nieczytelną mapą klas. Dla typowego przeglądu architektury zacząłbym od kontekstu i kontenerów; niższy poziom dodałbym dopiero wtedy, gdy trzeba wyjaśnić granice modułu lub odpowiedzialność konkretnej usługi.

Diagram sekwencji ujawnia, gdzie zatrzymuje się żądanie

Architektura może wyglądać poprawnie na statycznym obrazku, a mimo to ukrywać problem w kolejności wywołań. Diagram sekwencji rozpisuje uczestników w pionowych liniach życia, a komunikaty umieszcza od góry do dołu. W scenariuszu zakupu widać więc, czy API najpierw weryfikuje koszyk, rezerwuje towar, pobiera płatność, czy może czeka na odpowiedź zewnętrznego dostawcy.

To szczególnie przydatne przy błędach, ponowieniach i operacjach asynchronicznych. Jeśli płatność się powiedzie, ale zapis zamówienia zawiedzie, diagram może pokazać, czy system ma krok kompensujący, ponawia operację, czy pozostawia niespójny stan. Diagram sekwencji należy do notacji UML, ale da się go narysować prostymi symbolami, o ile kierunek i warunki komunikatów pozostają jasne.

Gdy problem brzmi „które elementy są połączone?”, sekwencja może być nadmiarem. Gdy brzmi „co wywołuje co i w jakiej kolejności?”, sam diagram kontenerów nie wystarczy.

ERD i OpenAPI odpowiadają na dwa różne pytania o API

Żądanie może przejść przez usługę bez błędu, a mimo to zapisać dane w nieodpowiedniej strukturze. ERD, czyli diagram encji i relacji, pokazuje obiekty domenowe, ich atrybuty oraz związki. Dla sklepu może przedstawić relację między zamówieniem, pozycją zamówienia i produktem, dzięki czemu łatwiej zauważyć, czy cena produktu jest zapisana jako historyczna wartość zamówienia, czy odczytywana wyłącznie z bieżącego katalogu.

Kontrakt endpointów opisuje inne zagadnienie. Specyfikacja OpenAPI definiuje maszynowo czytelny opis HTTP API, obejmujący między innymi operacje, parametry i odpowiedzi. Nie jest diagramem architektury: mówi, jak klient może wywołać interfejs, a nie jak wewnętrznie rozłożono backend.

W praktyce te materiały mogą się uzupełniać. OpenAPI pozwala sprawdzić kształt żądania i odpowiedzi, diagram sekwencji pokazuje jego drogę przez usługi, a ERD wyjaśnia, jak dane trafiają do modelu. Rozdzielenie tych pytań zapobiega jednemu z częstszych nieporozumień: oczekiwaniu, że dokumentacja endpointu wyjaśni całą architekturę.

Wybór diagramu zależy od tego, co trzeba rozstrzygnąć

Gdy nie wiadomo, od czego zacząć, nazwij konkretną niewiadomą. Czy zespół nie zna granic systemu, myli kolejność wywołań, czy nie rozumie relacji między danymi? Rodzaj diagramu powinien wynikać z odpowiedzi, a nie z tego, który szablon ma otwarty edytor.

SytuacjaCo prawdopodobnie jest niejasneCo narysować
Nowa osoba nie wie, jakie systemy łączą się z aplikacjąOtoczenie i granice rozwiązaniaDiagram kontekstu C4
Zespół nie rozumie, z jakich uruchamialnych części składa się backendPodział na aplikacje, usługi i magazyny danychDiagram kontenerów C4
Błąd pojawia się po kilku kolejnych wywołaniachKolejność komunikatów, warunki lub obsługa błęduDiagram sekwencji
Trudno ustalić, jak zamówienie łączy się z produktemEncje, atrybuty i relacje w bazieERD
Nie wiadomo, gdzie działają usługi w środowiskuWęzły infrastruktury i rozmieszczenie instancjiDiagram wdrożenia

Na przykład przy incydencie, w którym klient otrzymuje błąd po zatwierdzeniu płatności, zacząłbym od diagramu sekwencji, bo trzeba odtworzyć kolejność operacji i sprawdzić zachowanie po awarii. Jeśli problemem jest natomiast pytanie, czy usługa płatności należy do własnego systemu czy jest zewnętrzną zależnością, lepszy będzie diagram kontekstu. Ten sam przypadek biznesowy może wymagać dwóch diagramów, ale każdy powinien rozstrzygać inną niewiadomą.

Diagram ma pomagać w rozmowie, a nie udawać cały kod

Łatwo dopisać każdą klasę i każdy endpoint, aż zniknie główna myśl. Zostaw szczegóły w kodzie, specyfikacji API lub dokumentacji danych, a na diagramie pokaż elementy potrzebne do konkretnej decyzji. Prawdę mówiąc, diagram, którego nie da się odczytać bez przewijania i lupy, zwykle wymaga podziału na mniejsze widoki.

Przy każdej strzałce dodaj sensowną etykietę, na przykład „wysyła żądanie płatności” zamiast ogólnego „komunikuje się”. Zaznacz granice systemu, odróżnij zależności zewnętrzne i utrzymuj spójne nazwy z kodem oraz kontraktem API. Wtedy diagram backendu staje się mapą, która prowadzi od pytania do właściwego poziomu szczegółu, zamiast kolejnym obrazkiem do aktualizacji.

FAQ - Najczęstsze pytania

Diagram kontekstu C4 pokazuje system jako całość, jego użytkowników oraz zewnętrzne systemy, na przykład operatora płatności lub firmę kurierską. Diagram kontenerów warto wybrać wtedy, gdy trzeba przedstawić główne uruchamialne części backendu, takie jak API, aplikacja webowa, baza danych czy broker wiadomości.

Diagram sekwencji przedstawia kolejność komunikatów między API, usługami i bazą danych, więc pozwala ustalić, co dzieje się przed awarią i po niej. W scenariuszu nieudanej operacji może pokazać, czy system ponawia działanie, wykonuje krok kompensujący, czy pozostawia niespójny stan, na przykład opłaconą płatność bez zapisanego zamówienia.

ERD opisuje model danych: encje, atrybuty i relacje, takie jak powiązanie zamówienia, jego pozycji oraz produktu. OpenAPI definiuje kontrakt HTTP, czyli operacje, parametry i odpowiedzi endpointów. OpenAPI pokazuje, jak klient wywołuje interfejs, ale nie wyjaśnia wewnętrznej architektury backendu ani relacji w bazie.

Każdy widok powinien odpowiadać na jedno pytanie i pokazywać tylko elementy potrzebne do konkretnej decyzji. Warto etykietować strzałki konkretnymi działaniami, zaznaczać granice systemu, odróżniać zależności zewnętrzne oraz stosować nazwy zgodne z kodem i kontraktem API. Jeśli diagram wymaga przewijania lub lupy, lepiej podzielić go na mniejsze widoki.
Oceń artykuł

Średnia: 4.6 / 5 · 7 ocen

Tagi

openapi c4 diagramy sekwencji erd diagram wdrożenia

Udostępnij artykuł

Komentarze (0)
Dodaj komentarz