Anwendungsfälle für die Versionierung von Feldern und Direktiven

Lies zuerst die Anleitung Das Schema durch Field Versioning weiterentwickeln, die das Feature „field versioning" in Gato GraphQL erklärt.

Gato GraphQL erlaubt es Feldern und Direktiven, das Argument versionConstraint zu empfangen, um festzulegen, welche spezifische Version (d. h. Implementierung) des Feldes oder der Direktive verwendet werden soll:

query GetPosts {
  posts(versionConstraint: "^1.0") {
    id
    title(versionConstraint: ">=2.1")
    excerpt @strUpperCase(versionConstraint: "~1.5.3")
  }
}Copy

Ein Feld (oder eine Direktive) kann auch eine Standard-Implementierung haben, also diejenige ohne Versionsangabe (die verwendet wird, wenn versionConstraint in der Query nicht angegeben wird).

Bei der Introspektion werden nur Daten der Standard-Felder und -Direktiven abgerufen. Daher erscheint das Argument versionConstraint bei der Introspektion niemals, da das Standard-Feld oder die Standard-Direktive es nicht unterstützt.

Deshalb müssen wir immer im Voraus wissen, dass ein Feld oder eine Direktive zwei oder mehr Versionen zur Auswahl hat, und wir müssen diese Versionsnummern kennen. Diese Information ist standardmäßig nicht öffentlich.

Wozu ist die Versionierung dann nützlich? Hier sind einige Anwendungsfälle.

​

Einen schnellen Bugfix für einen bestimmten Nutzer bereitstellen

Stell dir vor, du hast eine GraphQL API auf deiner Website deployt, und ein bestimmter Nutzer beschwert sich, dass das Feld nicht wie erwartet funktioniert. Das passiert aber nur bei diesem einen Nutzer; niemand sonst scheint Probleme zu haben.

Du identifizierst und behebst das Problem, möchtest aber sicherstellen, dass es funktioniert, bevor du die Änderung für alle ausrollst. Du kannst die Änderung dann unter einem neuen Field Resolver mit der Version "1.0.1" deployen und den betroffenen Nutzer bitten, die GraphQL-Query so anzupassen, dass sie auf diese Version des Feldes zeigt:

{
  someBuggyField(versionConstraint: "1.0.1")
}Copy

Wenn der Bug tatsächlich behoben wurde, kopierst du den Code erst dann in den Standard-Field-Resolver.

​

Ausgewählte Nutzer bitten, ein bevorstehendes Release zu testen

Wenn ein Feld oder eine Direktive versioniert ist und keine Standard-Implementierung (d. h. keine nicht-versionierte) hat, erscheint es bei der Introspektion überhaupt nicht.

{
  someField
    # This directive has no default implementation,
    # so it won't appear during introspection,
    # but it can still be added in the GraphQL query
    # when providing a constraint that satisfies it
    @someExperimentalDirective(versionConstraint: ">1.0")
}Copy

Du kannst das Feld oder die Direktive dann deployen, ohne dass es in der GraphQL API sichtbar ist, und ausgewählte Nutzer bitten, es zu testen – dafür müssen sie das entsprechende Argument versionConstraint in ihren queries angeben.

Sobald es akzeptiert ist, wird die Versionierung entfernt, und das Feld oder die Direktive wird über die Introspektion sichtbar und damit für alle verfügbar.