Inndata

Validering

Lim inn et GraphQL-skjema til venstre for å se valideringsresultater her.

Hva er GraphQL-validatoren?

Et skjema som kommer tilbake fra en federation-composer, en kodegenerator eller en håndredigering under en code review har nesten alltid minst ett syntaksproblem ved første gjennomgang. En forvillet }, en uavsluttet beskrivelses-streng, en enum-kropp som ble hugget av da noen limte inn en halv skjerm SDL i en chat — og plutselig eksploderer oppstarten av Apollo Server-en din med en parser-feil som peker på linje 1, som sjelden er der det egentlige problemet er. Denne validatoren går gjennom SDL-en token for token og peker på den ekte linjen.

Den sjekker strukturelle regler fra GraphQL-spesifikasjonen fra oktober 2021: hver {, ( og [ trenger en matchende lukker av rett sort; beskrivelser skrevet som """...""" må avsluttes; strenger i anførselstegn inne i argumenter må lukke på samme linje. Validatoren sjekker IKKE semantikk — den vil ikke fortelle deg at Query mangler eller at et felt refererer til en udeklarert type. Til det, kjør skjemaet gjennom referanse-implementasjonen graphql-js. Det denne siden gjør bra er syntaksgjennomgangen og stat-blokken, slik at du med ett blikk ser om skjemaet du nettopp limte inn har 14 typer eller 4, 187 felter eller 12.

Alt kjører i nettleseren din. Ingen opplasting, ingen skjema lagres noe sted. Lim inn, valider, kopier.

Slik bruker du GraphQL-validatoren

Tre raske trinn. Knappene nedenfor matcher de faktiske knappene på siden.

Lim inn, last opp eller hent et eksempel

Lim inn et GraphQL-skjema i det venstre Inndata-panelet — valideringen kjører automatisk en brøkdel av et sekund etter at du slutter å skrive, så det er ingen Validate-knapp. Klikk Last opp for en .graphql-, .graphqls- eller .gql-fil, eller trykk Eksempel for å laste et realistisk e-handels-Order-skjema. En typisk innliming ser slik ut:

type Order { id: ID! placedAt: DateTime! customer: Customer! items: [OrderItem!]! status: OrderStatus! } enum OrderStatus { PENDING PAID SHIPPED }

Både skjemaer i serverstil (med extend type Query) og frittstående typefiler fungerer. Kommentarer (#) og blokk-streng-beskrivelser ("""...""") håndteres på samme måte som GraphQL learn-schema-dokumentasjonen beskriver.

Les stat-blokken

Det høyre panelet viser et grønt banner hvis skjemaet parses rent, et rødt hvis ikke — og uansett får du en oppdeling av hvor mange type-, interface-, enum-, input-, union-, scalar- og directive-definisjoner skjemaet erklærer, pluss totalt antall felter, argumenter og beskrivelser. Nyttig for å sanity-sjekke en federation-merge eller sammenligne to revisjoner av samme skjema. Tellingene speiler det som Relay GraphQL-spesifikasjonen kaller de strukturelle delene av en definisjon.

Fiks og lim inn på nytt

Hvis skjemaet er ugyldig, forteller banneret deg den eksakte linjen for den ubalanserte klammen eller uavsluttede strengen. Fiks det, lim det inn igjen, se banneret bli grønt. Kopier-knappen til høyre gir deg en liten JSON stat-rapport du kan slippe inn i en PR-beskrivelse eller en chat-melding — praktisk når du vil vise en kollega "ja skjemaet er greit, her er stat'ene" uten å dele selve SDL-en.

Når du faktisk ville brukt dette

Sanity-sjekk før merge

Før du merger en federation-gateway-endring eller en schema-stitching-oppdatering, lim inn det sammensatte skjemaet her. Hvis klammebalansen er skjev eller en beskrivelse er uavsluttet, ser du det her på to sekunder i stedet for i en CI-feil ti minutter senere. Passer godt sammen med kommandoen rover subgraph check for den semantiske siden.

Diffing av to revisjoner

Lim inn versjon A, noter stat-tallene (28 typer, 142 felter, 6 enums). Lim inn versjon B og sammenlign. Hvis felttallet har hoppet opp 40 men det bare er lagt til én ny type, har sannsynligvis noen duplisert et fragment. Stat-blokken er mye raskere enn å scrolle gjennom en diff på 2000 linjer.

Onboarding av en ny konsulent

Gi dem skjema-filen, pek dem mot denne siden og si "hvis det blir rødt, er innlimingen din ødelagt; hvis felttallet plutselig er 800 lavere, har du bare kopiert halvparten". Sparer frem-og-tilbake-spørsmålet "er dette alt?" før de i det hele tatt begynner å skrive resolvers.

Liming fra chat

Slack og Discord elsker å rive sund backticks og anførselstegn når de wrapper lange meldinger, så et skjema som noen limte inn i en tråd mister ofte en eller to lukke-klammer. Slipp det her først for å finne ut av det før du åpner det i IDE-en din.

Vanlige spørsmål

Validerer den semantikk, eller bare syntaks?

Bare syntaks — klammebalanse, streng-avslutning og en stat-walk over token-strømmen. Den sjekker IKKE at Query finnes, at refererte typer er definert, at argumenter matcher direktiv-definisjonene sine, eller at en felttype er gyldig. For full semantisk validering, bruk referanse-biblioteket graphql-js eller serverens oppstartssjekker.

Blir skjemaet mitt sendt til en server?

Nei. Valideringen kjører helt i nettleseren din. Ingenting lastes opp, ingenting logges. Trygt å lime inn interne eller upubliserte skjemaer.

Hvilke syntaksproblemer fanger den egentlig?

Umatchede { / ( / [ med linjenummeret der åpneren satt, feilmatchede lukkere som ) der } var ventet, uavsluttede "strings" eller """block strings""", og forvillede tegn som ikke er en del av GraphQL-token-grammatikken.

Hvorfor viser skjemaet mitt 0 typer når det tydelig har typer?

Stat-telleren teller bare en definisjon når både nøkkelordet (type, interface osv.) OG kroppsklammene er til stede. Hvis du limte inn et skjema som er hugget av midt i en type, blir tellingen for den typen stående på 0 til du fullfører kroppen. Validator-banneret er også rødt i det tilfellet og peker på den umatchede åpneren.

Forstår den blokk-streng-beskrivelser?

Ja. """An order placed by a customer.""" gjenkjennes som en beskrivelses-token og telles i Beskrivelser-stat'en. Validatoren håndhever ikke hvor beskrivelser kan dukke opp — det er et stilvalg — men tellingen gir deg en rask avlesning av hvor dokumentert skjemaet er.

Hvor stort skjema kan jeg lime inn?

Hva enn nettleseren din kan rendre komfortabelt. Skjemaer med noen hundre typer og flere tusen felter validerer godt under et sekund. Forbi 5 MB begynner Ace-editoren selv å bli treg, og det er flaskehalsen — ikke validatoren.

Andre GraphQL-verktøy

Validering er bare én del av å jobbe med GraphQL. Disse verktøyene tar seg av resten: