Casos de uso para versionamento de campos e diretivas

Leia primeiro o guia Evoluindo o schema por meio do versionamento de campos, que explica o recurso de "field versioning" no Gato GraphQL.

O Gato GraphQL permite que campos e diretivas recebam o argumento versionConstraint, para escolher qual versão específica (ou seja, implementação) do campo/diretiva utilizar:

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

Um campo (ou diretiva) também pode ter uma implementação padrão, que é aquela sem versão (e é a utilizada quando versionConstraint não é fornecido na query).

Durante a introspecção, apenas os dados dos campos e diretivas padrão são recuperados. Como consequência, o argumento versionConstraint nunca aparecerá durante a introspecção, pois o campo ou diretiva padrão não o suporta.

Por causa disso, precisamos sempre saber com antecedência que um campo ou diretiva possui duas ou mais versões para escolher, e precisamos saber quais são esses números de versão. Essa informação, por padrão, não é pública.

Então, de que forma o versionamento é útil? Aqui estão alguns casos de uso.

​

Fornecendo uma correção rápida de bug para um usuário específico

Digamos que você tenha uma API GraphQL implantada no seu site, e um usuário específico reclame que o campo não está funcionando como esperado. Mas isso acontece apenas para esse único usuário; ninguém mais parece estar enfrentando problemas.

Você identifica e corrige o problema, mas quer ter certeza de que funciona antes de implantar a mudança para todos. Então, você pode implantar a mudança sob um novo field resolver com a versão "1.0.1", e pedir ao usuário com o problema que altere a query GraphQL para apontar para esta versão do campo:

{
  someBuggyField(versionConstraint: "1.0.1")
}Copy

Se o bug foi de fato corrigido, só então copie o código para o field resolver padrão.

​

Pedindo a usuários selecionados que testem uma versão futura

Se um campo ou diretiva está versionado/a, e não possui uma implementação padrão (ou seja, não versionada), então não aparecerá de forma alguma durante a introspecção.

{
  someField
    # Esta diretiva não tem implementação padrão,
    # portanto não aparecerá durante a introspecção,
    # mas ainda pode ser adicionada na query GraphQL
    # ao fornecer uma restrição que a satisfaça
    @someExperimentalDirective(versionConstraint: ">1.0")
}Copy

Você pode então implantar o campo ou a diretiva e ele/ela não será visível na API GraphQL, e pedir a usuários selecionados que o/a testem, para o que eles devem inserir o argumento versionConstraint correspondente em suas queries para utilizá-lo/a.

Uma vez aceito/a, o versionamento é removido, e o campo ou diretiva se torna visível por meio da introspecção, e portanto disponível para todos.