Arbeiten mit integrierten GraphQL-Anweisungen

Richtlinien sind eine der besten - und unausgesprochensten - von GraphQLs.

Lassen Sie uns die Arbeit mit integriertem Schema- und Betriebsrichtlinien von GraphQL untersuchen, die alle APIs mit GraphQL-Spezifikationen implementieren müssen. Sie sind äußerst nützlich, wenn Sie mit einem dynamischen Front-End arbeiten, da Sie die Kontrolle haben, um die Antwortnutzlast abhängig von der Interaktion des Benutzers zu reduzieren.

Ein Überblick über Richtlinien

Stellen Sie uns eine Anwendung vor, bei der Sie die in einer Tabelle gezeigten Spalten anpassen können. Wenn Sie zwei oder drei Spalten ausblenden, müssen die Daten für diese Zellen nicht abgerufen werden. Mit GraphQL -Anweisungen können wir diese Felder einschließen oder überspringen.

Die GraphQL -Spezifikation definiert, welche Richtlinien sind und wie sie verwendet werden können. Insbesondere können Richtlinien von Verbraucherbetrieb (z. B. einer Abfrage) und dem zugrunde liegenden Schema selbst verwendet werden. ODER in einfachen Worten basieren Richtlinien entweder auf Schema oder Betrieb. Schema -Direktiven werden verwendet, wenn das Schema generiert wird und die Betriebsrichtlinien ausgeführt werden, wenn eine Abfrage ausgeführt wird.

Kurz gesagt, Richtlinien können für die Zwecke von Metadaten, Laufzeit -Tipps, Laufzeit -Parsen (wie Rückgabedaten in einem bestimmten Format) und erweiterten Beschreibungen (wie veraltet) verwendet werden.

Vier Arten von Anweisungen

GraphQL verfügt über vier Hauptanweisungen, die im Spezifikationsentwurf definiert sind, wobei einer als Arbeitsentwurf unveröffentlicht ist.

• @enthalten
• @überspringen
• @veraltet
• @Specifiedby (Arbeitsentwurf)

Wenn Sie GraphQL genau verfolgen, werden Sie auch feststellen, dass zwei zusätzliche Anweisungen mit der JavaScript -Implementierung zusammengeführt wurden, die Sie heute ausprobieren können - @stream und @Defer. Diese sind noch nicht Teil der offiziellen Spezifikation, während die Community sie in realen Anwendungen testet.

@enthalten

Die @Include -Anweisung, die ihrem Namen treu ist, ermöglicht es uns, bedingte Felder durch Übergeben eines IF -Arguments. Da es bedingt ist, ist es sinnvoll, eine Variable in der Abfrage zu verwenden, um nach Wahrheit zu überprüfen.

Wenn beispielsweise die Variable in den folgenden Beispielen wahrheitsgemäß ist, wird das Feld Name in die Abfrageantwort aufgenommen.

 Abfragethere ($ zeitlich: boolean) {
  Benutzer {
    Ausweis
    Name @Include (wenn: $ teamname)
  }
}

Umgekehrt können wir das Feld nicht einfügen, indem wir den Variablen $ teamname zusammen mit der Abfrage als Falsch übergeben. Wir können auch einen Standardwert für die Variable "$ destnameame" angeben, sodass sie mit jeder Anfrage nicht übergeben werden müssen:

 Abfragetusers ($ zeigteame: boolean = true) {
  Benutzer {
    Ausweis
    Name @Include (wenn: $ teamname)
  }
}

@überspringen

Wir können dasselbe mit Just Did ausdrücken, aber stattdessen @Skip -Richtlinie. Wenn der Wert wahrheitsgemäß ist, überspringen Sie, wie Sie vielleicht erwarten, dieses Feld.

 Abfragethere ($ HIDENAME: boolean) {
  Benutzer {
    Ausweis
    Name @skip (wenn: $ hidename)
  }
}

Während dies für einzelne Felder hervorragend funktioniert, gibt es Zeiten, in denen wir mehr als ein Feld einbeziehen oder überspringen möchten. Wir könnten die Verwendung von @include und @Skip über mehrere Zeilen wie folgt duplizieren:

 Abfragen GetUsers ($ includefields: boolean) {
  Benutzer {
    Ausweis
    Name @include (wenn: $ includefields)
    E -Mail @include (wenn: $ includefields)
    Rolle @include (wenn: $ includefields)
  }
}

Sowohl die @skip- als auch die @include -Direktiven können auf Feldern, Fragmentverbreitungen und Inline -Fragmenten verwendet werden, was bedeutet, dass wir etwas anderes tun können, stattdessen mit Inline -Fragmenten:

 Abfragethere ($ exkludefields: boolean) {
  Benutzer {
    Ausweis
    ... auf user @skip (wenn: $ exkludefields) {
      Name
      E-Mail
      Rolle
    }
  }
}

Wenn ein Fragment bereits definiert ist, können wir auch @Skip und @include verwenden, wenn wir ein Fragment in die Abfrage verbreiten:

 Fragment -Benutzer auf Benutzer {
  Name
  E-Mail
  Rolle
}

Abfragethere ($ exkludefields: boolean) {
  Benutzer {
    Ausweis
    ... user @skip (falls: $ exkludefields)
  }
}

@veraltet

Die @Deprecated -Richtlinie erscheint nur im Schema und ist nicht etwas, das ein Benutzer als Teil einer Abfrage bereitstellen würde, wie wir es oben gesehen haben. Stattdessen wird die @Deprecated -Richtlinie vom Entwickler angegeben, der das GraphQL -API -Schema beibehält.

Wenn wir als Benutzer versuchen, ein Feld zu holen, das im Schema veraltet wurde, erhalten wir eine solche Warnung, die kontextbezogene Hilfe bietet.

Um ein Feld veraltet zu markieren, müssen wir die @deprecated -Richtlinie innerhalb der Schema -Definitionssprache (SDL) verwenden und einen Grund innerhalb der Argumente wie folgt übergeben:

 Geben Sie Benutzer ein {
  ID: ID!
  Titel: String @Deprecated (Grund: "Name stattdessen verwenden")
  Name: String!
  E -Mail: Zeichenfolge!
  Rolle: Rolle
}

Wenn wir dies mit der @Include -Richtlinie kombiniert haben, können wir das veraltete Feld basierend auf einer Abfragevariablen bedingt abrufen:

 Fragment -Benutzer auf Benutzer {
  Titel @include (wenn: $ includededFields)
  Name
  E-Mail
  Rolle
}

Abfragetuser ($ includededFields: boolean! = false) {
  Benutzer {
    Ausweis
    ...Benutzer
  }
}

@Specifiedby

@Specifiedby ist das vierte der Richtlinien und derzeit Teil des Arbeitsentwurfs. Es soll von benutzerdefinierten skalaren Implementierungen verwendet werden und ein URL -Argument aufnehmen, das auf eine Spezifikation für den Skalar hinweisen sollte.

Wenn wir beispielsweise einen benutzerdefinierten Skalar für die E -Mail -Adresse hinzufügen, möchten wir die URL an die Spezifikation für die Regex weitergeben, die wir als Teil davon verwenden. Unter Verwendung des letzten Beispiels und des in RFC #822 definierten Vorschlags würde ein Skalar für E -MailAddress im Schema wie SO definiert:

 Scalar Emailaddress @SpecifiedBy (URL: "https://www.w3.org/protocols/rfc822/"))

Es wird empfohlen, dass benutzerdefinierte Direktiven einen vorangestellten Namen haben, um Kollisionen mit anderen zusätzlichen Anweisungen zu verhindern. Wenn Sie nach einer Beispiel für benutzerdefinierte Richtlinie suchen und wie sie erstellt wird, schauen Sie sich das öffentliche Schema von GraphQL an. Es handelt sich um eine benutzerdefinierte GraphQL-Richtlinie, die sowohl Code- als auch Schema-First-Unterstützung für die Annotation bietet, welche API in der Öffentlichkeit konsumiert werden kann.

Einpacken

Das ist also ein hochrangiger Blick auf GraphQL-Anweisungen. Ich glaube, Richtlinien sind eine Art unbesungener Held, der von anderen GraphQL -Funktionen überschattet wird. Wir haben bereits eine Menge Kontrolle über das GraphQL-Schema, und Richtlinien geben uns noch mehr feinkörnige Kontrolle, um genau das zu bekommen, was wir von Fragen wollen. Das ist die Art von Effizienz, und das macht die GraphQL -API so schnell und letztendlich freundlicher, mit denen man arbeiten kann.

Und wenn Sie eine GraphQL -API erstellen, geben Sie diese Richtlinien in die Introspection -Abfrage auf. Wenn Sie sie dort nicht nur den Vorteilen einer zusätzlichen Kontrolle, sondern auch eine bessere Entwicklererfahrung geben. Denken Sie nur daran, wie hilfreich es wäre, Felder ordnungsgemäß zu @deprecate, damit Entwickler wissen, was sie tun sollen, ohne jemals den Code zu verlassen? Das ist an und für sich mächtig.

Header -Grafik mit freundlicher Genehmigung von Isabel Gonçalves auf Unsplash

Das obige ist der detaillierte Inhalt vonArbeiten mit integrierten GraphQL-Anweisungen. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!