Schemat A (stary)

Schemat B (nowy)

Diff

Wklej schemat w każdym panelu — diff aktualizuje się w trakcie pisania.

Czym jest Diff schematów GraphQL?

Każda zmiana API psuje czyjegoś klienta. Pierwszą rzeczą, której potrzebujesz przed zmergeowaniem PR-a ze schematem, jest jasna lista tego, co naprawdę się zmieniło — a nie 600-liniowy diff GitHub-a, który miesza białe znaki, reformatowanie i prawdziwe zmiany w jedną ścianę czerwieni i zieleni. Wklej stary schemat po lewej, nowy po prawej, a to narzędzie da ci trzy listy: co dodano, co usunięto i które istniejące pola zmieniły typ. Schematy są parsowane zgodnie ze specyfikacją GraphQL z października 2021, więc to, co narzędzie uznaje za "typ" lub "pole", odpowiada temu, co tak rozumie twój serwer.

Diff jest strukturalny, nie tekstowy. Zmiana kolejności pól w obrębie typu jest niewidoczna. Reformatowanie SDL jest niewidoczne. Zmiana nazwy argumentu się pojawi. Zamiana Int na Float w Order.total się pojawi. Nowe wartości enum jak OrderStatus.REFUNDED pojawią się w dodaniach. Usunięcie członka union pojawi się w usunięciach. Styl wyjścia odpowiada kategoryzacji używanej przez GraphQL Inspector i Apollo schema checks, więc workflow przekłada się na te narzędzia, gdy w końcu przeniesiesz check do CI.

Wszystko działa w twojej przeglądarce. Bez uploadu, nic nie jest logowane. Bezpieczne dla niewydanych wewnętrznych schematów.

Jak używać Diff schematów GraphQL

Wklej, wklej, czytaj. Nie ma przycisku Porównaj — diff aktualizuje się w trakcie pisania.

Wklej stary schemat w panelu A

Wrzuć aktualny schemat produkcyjny do lewego panelu opisanego Schemat A (stary). Kliknij Wgraj dla pliku .graphql, .graphqls lub .gql, albo wciśnij Przykład, aby załadować sparowany przykład starter / iteracja. Schemat nie musi być ładny — różnice w formatowaniu są ignorowane.

Wklej nowy schemat w panelu B

Wrzuć kandydujący schemat (ten z twojego PR-a) do prawego panelu opisanego Schemat B (nowy). Narzędzie tokenizuje oba schematy, przechodzi po każdej definicji typu i przelicza diff ułamek sekundy po tym, jak przestaniesz pisać. Semantyka parsera referencyjnego trzyma się graphql-js na tyle blisko, że to, co tu widzisz, to to samo, co zobaczyłby twój serwer.

Przeczytaj trzy listy

Dolny panel ma trzy sekcje. Dodania (zielone) zawierają nowe typy, nowe pola, nowe wartości enum i nowych członków union. Usunięcia (czerwone) zawierają te same kategorie w odwrotną stronę — to zwykle są breaking changes, więc skanuj tę listę pierwszą. Zmiany (bursztynowe) zawierają pola i argumenty, których typ się zmienił, np. Order.total: Int → Float. Jeśli schematy są równoważne, dostajesz pojedynczy zielony banner mówiący o tym.

Kiedy faktycznie tego użyjesz

Review PR-a

Kolega z zespołu otwiera PR-a, który dodaje pięć nowych pól i zmienia nazwę argumentu. Diff GitHub-a jest nieczytelny, bo przepuścił też schemat przez formatter. Wklej obie wersje tutaj i zdobądź prawdziwą listę zmian — zwykle trzy lub cztery pozycje, nie trzysta. Reviewerzy mogą kłócić się o faktyczną semantykę, a nie o wcięcia.

Wyłapywanie breaking changes

Usunięcie pola, zwężenie typu zwracanego lub zmiana nazwy wymaganego argumentu to breaking changes dla klientów na produkcji. Listy Usunięcia i Zmiany pokazują je bezpośrednio. Uruchom diff przed merge'em, by potwierdzić, że breaking change jest zamierzony. Ten sam check w końcu należy do CI — zobacz dokumentację Apollo schema checks dla produkcyjnej wersji tego workflow.

Dokumentacja onboardingowa

Gdy nowy inżynier pyta "co się zmieniło w zeszłym sprincie?", wklej wersję z poniedziałku i wersję z piątku do paneli i skopiuj diff do swoich notatek sprintowych. Szybsze niż przewijanie commitów i o wiele czytelniejsze.

Sanity check federacji

Po uruchomieniu federowanego composera jak Apollo Rover wklej poprzedni złożony schemat i nowy. Diff powie ci, czy kompozycja podchwyciła zmianę, której oczekiwałeś z PR-a subgraph-a — czy też coś po cichu zmieniło się gdzie indziej.

Częste pytania

Czy diff wyłapuje konkretnie breaking changes?

Wszystko, co jest na listach Usunięcia i Zmiany, jest potencjalnie łamiące — usunięcie pola, zwężenie typu zwracanego, zmiana nazwy argumentu. Narzędzie nie klasyfikuje każdej zmiany jako "breaking" vs "non-breaking" tak jak GraphQL Inspector, ale ustrukturyzowana lista czyni oczywistym, na które popatrzeć.

Czy kolejność pól liczy się jako zmiana?

Nie. Zmiana kolejności pól w typie jest strukturalnie identyczna i jest ignorowana. To samo dla zmiany kolejności wartości enum, członków union i argumentów. Raportowane są tylko elementy dodane, usunięte lub o zmienionym typie.

A opisy i komentarze?

Opisy block-string i komentarze są ignorowane przy porównaniu strukturalnym. Dodanie opisu do pola nie pojawia się w diffie. Jeśli chcesz śledzić zmiany w dokumentacji, rób to w sformatowanym diffie SDL w swoim PR-rze, nie tutaj.

Czy moje schematy są wysyłane na serwer?

Nie. Tokenizer i diff działają w całości w twojej przeglądarce. Nic nie jest uploadowane, nic nie jest logowane. Bezpiecznie wklejać wewnętrzne lub niewydane schematy.

Jak duży schemat mogę wkleić?

Strona ogranicza każdy input do 5 MB. Powyżej sam edytor Ace zaczyna mulić. Schematy z kilkuset typami nie są problemem.

Czy mogę uruchomić to w CI?

Do lokalnych sanity checków przed wypchnięciem PR-a ta strona jest okej. Do bramek CI, które oblewają build na breaking change, użyj dedykowanego CLI GraphQL Inspector lub Apollo schema checks — oba mają porządną semantykę exit-code i konfigurację polityk.

Inne narzędzia GraphQL

Diffowanie to tylko część pracy z GraphQL. Te narzędzia ogarniają resztę: