Przypadki użycia wersjonowania pól i dyrektyw

Przeczytaj najpierw przewodnik Rozwijanie schematu poprzez wersjonowanie pól, który wyjaśnia funkcję "field versioning" w Gato GraphQL.

Gato GraphQL pozwala polom i dyrektywom przyjmować argument versionConstraint, aby wybrać konkretną wersję (czyli implementację) pola/dyrektywy do użycia:

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

Pole (lub dyrektywa) może również posiadać domyślną implementację, czyli tę bez wersji (używaną gdy versionConstraint nie jest podany w query).

Podczas introspekcji pobierane są tylko dane domyślnych pól i dyrektyw. W konsekwencji argument versionConstraint nigdy nie pojawi się podczas introspekcji, ponieważ domyślne pole lub dyrektywa go nie obsługuje.

Z tego powodu musimy zawsze z góry wiedzieć, że pole lub dyrektywa ma dwie lub więcej wersji do wyboru, i musimy znać te numery wersji. Ta informacja jest domyślnie niepubliczna.

Jak zatem wersjonowanie jest przydatne? Oto kilka przypadków użycia.

​

Szybka naprawa błędu dla konkretnego użytkownika

Powiedzmy, że masz API GraphQL wdrożone na swojej stronie, a konkretny użytkownik skarży się, że pole nie działa zgodnie z oczekiwaniami. Ale dotyczy to tylko tego jednego użytkownika; nikt inny nie wydaje się doświadczać problemów.

Identyfikujesz i naprawiasz problem, ale chcesz się upewnić, że działa, zanim wdrożysz zmianę dla wszystkich. Możesz więc wdrożyć zmianę pod nowym field resolverem z wersją "1.0.1" i poprosić użytkownika z problemem, aby zmienił query GraphQL tak, by wskazywało na tę wersję pola:

{
  someBuggyField(versionConstraint: "1.0.1")
}Copy

Jeśli błąd został rzeczywiście naprawiony, dopiero wtedy skopiuj kod do domyślnego field resolvera.

​

Prośba do wybranych użytkowników o przetestowanie nadchodzącej wersji

Jeśli pole lub dyrektywa jest wersjonowane i nie posiada domyślnej (tj. niewersjonowanej) implementacji, to nie pojawi się w ogóle podczas introspekcji.

{
  someField
    # Ta dyrektywa nie ma domyślnej implementacji,
    # więc nie pojawi się podczas introspekcji,
    # ale nadal można ją dodać w query GraphQL
    # podając ograniczenie, które ją spełnia
    @someExperimentalDirective(versionConstraint: ">1.0")
}Copy

Możesz wtedy wdrożyć pole lub dyrektywę i nie będzie ono/ona widoczne/a w API GraphQL, a następnie poprosić wybranych użytkowników o przetestowanie — w tym celu muszą oni wpisać odpowiedni argument versionConstraint w swoich queries.

Po zaakceptowaniu wersjonowanie jest usuwane, a pole lub dyrektywa staje się widoczne poprzez introspekcję i tym samym dostępne dla wszystkich.