JSON z introspekcji

GraphQL SDL

Czym jest konwerter JSON z introspekcji do SDL?

Kiedy ściągasz schemat z Apollo Studio, Postmana, Insomnii albo odpalasz get-graphql-schema przeciwko działającemu endpointowi, to co dostajesz to nie ten przyjazny SDL, który napisałeś — to wynik query { __schema { ... } }: 600+ linii zagnieżdżonego JSON-a opisującego każdy typ, każde pole i każdy modyfikator w drzewie obiektów kind / name / ofType. Przydatne dla narzędzia, nieczytelne dla człowieka. Ten konwerter bierze ten JSON i wypluwa go z powrotem jako SDL, który faktycznie wrzuciłbyś do repo, zgodnie z regułami introspekcji ze specyfikacji GraphQL z października 2021.

Wszystko dzieje się w twojej przeglądarce — żadnego uploadu, żadnego AI, żaden schemat nigdzie nie jest wysyłany. Logika konwersji odzwierciedla to, co graphql-js robi wewnętrznie z buildClientSchema i printSchema: chodzi po drzewie __schema, pomija typy zarezerwowane dla introspekcji (__Schema, __Type, __Field, …) oraz wbudowane skalary i wypisuje każdą pozostałą definicję wraz z opisem, polami, argumentami, wartościami domyślnymi i powodami deprecation w nienaruszonej formie. Niezależnie od tego, czy wklejasz pełną kopertę { "data": { "__schema": ... } }, samo { "__schema": ... }, czy nawet gołą wartość __schema — strona ogarnie wszystkie trzy.

Wynik jest pogrupowany: najpierw skalary, potem enumy, interfejsy, unie, typy wejściowe i na końcu typy obiektowe — alfabetycznie w obrębie każdej grupy, z wcięciem dwóch spacji i pustą linią między definicjami. Na tyle idempotentne, że można je wrzucić wprost do pliku <code>.graphql</code> w twoim repo.

Jak korzystać z konwertera

Trzy kroki. Przyciski poniżej to faktyczne przyciski tej strony.

Wklej, wgraj albo wczytaj przykład

Wklej swój JSON z introspekcji do lewego panelu Wejście — konwersja odbywa się automatycznie ułamek sekundy po tym, jak przestaniesz pisać, więc nie ma żadnego przycisku Convert do szukania. Kliknij Wgraj dla pliku .json wyeksportowanego z Apollo Studio lub Postmana albo wciśnij Przykład, by załadować realistyczny wynik introspekcji Order/Customer/Money. Typowe wklejenie zaczyna się tak:

{
  "data": {
    "__schema": {
      "queryType": { "name": "Query" },
      "types": [
        { "kind": "OBJECT", "name": "Order", "fields": [...] },
        ...
      ]
    }
  }
}

Możesz też wkleić wewnętrzną wartość { "__schema": ... } albo goły obiekt __schema — strona próbuje wszystkich trzech form. Narzędzia takie jak get-graphql-schema i endpoint introspekcji Apollo Servera domyślnie produkują jedną z tych form.

Czytaj wynik SDL

Prawy panel Wynik renderuje schemat jako SDL. Każdy typ ma własną definicję z wcięciem dwóch spacji, pola po jednym na linię, opisy zachowane nad typem lub polem jako block stringi w potrójnych cudzysłowach, a powody deprecation renderowane jako @deprecated(reason: "...") w tej samej linii. Wbudowane skalary i typy introspekcji __ są odfiltrowane — to, co dostajesz, to dokładnie ten schemat, który publikuje twój serwer, w sposób zalecany do dokumentowania przez specyfikację GraphQL Relay. Jeśli JSON jest popsuty albo brakuje pola __schema, dostajesz przyjazny komunikat inline zamiast stack trace.

Kopiuj albo pobierz

Wciśnij Kopiuj, żeby zabrać SDL do opisu PR-a, doca albo czatu. Wciśnij Pobierz, żeby zapisać jako schema.graphql — wrzuć wprost do repo. Przycisk czyszczenia w panelu wejścia resetuje cię do pustego stanu. Konwersja jest w pełni po stronie klienta; wynik introspekcji nigdy nie opuszcza strony.

Kiedy faktycznie tego użyjesz

Wyciągnij schemat z działającego endpointu

Dziedziczysz serwis GraphQL, który nie ma pliku schematu w repo — tylko działający serwer. Odpal zapytanie introspekcji, wklej JSON tutaj i w pięć minut masz początkowe schema.graphql zacommitowane. Łatwiejsze niż okablowanie buildClientSchema i printSchema z graphql-js tylko po to, by zrobić to raz.

Czytaj eksport z Apollo Studio albo Postmana

Eksport schematu z Apollo Studio to JSON z introspekcji. Tak samo z przyciskiem "Save schema" w Postmanie przy zapytaniu GraphQL. Skonwertuj tutaj i możesz faktycznie przelecieć schemat wzrokiem w edytorze kodu, zamiast mrużyć oczy nad JSON-em.

Diff dwóch snapshotów działającego schematu

Odpal introspekcję na staging i produkcji, skonwertuj każdy do SDL, potem zrób diff dwóch plików. Wyłapanie brakującego pola czy zmienionej nazwy wartości enum jest banalne w SDL i praktycznie niemożliwe w surowym JSON-ie introspekcji.

Wygeneruj stuby typów z serwisu, który nie jest twój

Potrzebujesz typów TypeScript albo hooków React dla zewnętrznego API GraphQL? Większość generatorów kodu chce SDL, nie JSON-a z introspekcji. Skonwertuj tutaj, a potem podaj SDL do swojego pipeline'u codegen — graphql-react, graphql-codegen albo czegokolwiek używa twój stack.

Częste pytania

Czy potrzebna jest pełna koperta { "data": { "__schema": ... } }?

Nie. Strona przyjmuje trzy formy: pełną kopertę odpowiedzi GraphQL, samo { "__schema": ... } albo nawet goły obiekt __schema. Cokolwiek wkleisz, znajdzie korzeń __schema i pracuje od tego miejsca.

A jeśli mój JSON nie ma pola __schema?

Dostajesz przyjazny komunikat: "Expected an introspection result. Couldn't find __schema field. Paste the JSON returned by the GraphQL introspection query." Bez crashu, bez stack trace.

Czy opisy i powody deprecation są zachowane?

Tak. Opisy typów i pól są emitowane jako block stringi w potrójnych cudzysłowach nad definicją. Pola i wartości enum oznaczone jako deprecated dostają @deprecated(reason: "...") w tej samej linii. To pasuje do wyniku printSchema z graphql-js.

A co z wbudowanymi skalarami i typami introspekcji __?

Odfiltrowane. String, Int, Float, Boolean i ID są w SDL niejawne — pojawiają się tylko w typach pól, nie jako definicje na najwyższym poziomie. To samo z __Schema, __Type, __Field i resztą metatypów introspekcji.

Czy wynik gwarantuje round-trip do tego samego rezultatu introspekcji?

Semantycznie tak — SDL opisuje ten sam schemat. Bajt po bajcie nie, bo kolejność typów i pól może się różnić od twojego oryginalnego pliku źródłowego. Wynik jest sortowany alfabetycznie w obrębie każdej grupy definicji dla stabilnych diffów.

Czy mój wynik introspekcji jest wysyłany na serwer?

Nie. Konwersja odbywa się w całości w twojej przeglądarce. Nic nie jest wysyłane, nic nie jest logowane. Bezpieczne do wklejania schematów z wewnętrznych albo niewydanych jeszcze serwisów.

Inne narzędzia GraphQL

Kiedy już masz SDL, te zajmują się resztą:

JSON z introspekcji do GraphQL SDL