Casi d'uso per il versionamento di campi e direttive
Leggi prima la guida Far evolvere lo schema tramite il versionamento dei campi, che spiega la funzionalità di « field versioning » in Gato GraphQL.
Gato GraphQL consente ai campi e alle direttive di ricevere l'argomento versionConstraint, per scegliere quale versione specifica (cioè l'implementazione) del campo/della direttiva utilizzare:
query GetPosts {
posts(versionConstraint: "^1.0") {
id
title(versionConstraint: ">=2.1")
excerpt @strUpperCase(versionConstraint: "~1.5.3")
}
}Un campo (o una direttiva) può anche avere un'implementazione predefinita, che è quella priva di versione (ed è quella utilizzata quando versionConstraint non viene fornito nella query).
Durante l'introspezione, vengono recuperati solo i dati dei campi e delle direttive predefiniti. Di conseguenza, l'argomento versionConstraint non apparirà mai durante l'introspezione, poiché il campo o la direttiva predefiniti non lo supportano.
Per questo motivo, dobbiamo sempre sapere in anticipo che un campo o una direttiva dispone di due o più versioni tra cui scegliere, e dobbiamo conoscere quei numeri di versione. Questa informazione, per impostazione predefinita, non è pubblica.
Allora, in che modo il versionamento è utile? Ecco diversi casi d'uso.
Fornire una correzione rapida di un bug per un utente specifico
Immaginiamo che tu abbia un'API GraphQL distribuita sul tuo sito web, e che un utente specifico si lamenti che il campo non funziona come previsto. Ma questo accade solo per questo utente; nessun altro sembra riscontrare problemi.
Identifichi e correggi il problema, ma vuoi assicurarti che funzioni prima di distribuire la modifica a tutti. Puoi allora distribuire la modifica sotto un nuovo field resolver con la versione "1.0.1", e chiedere all'utente interessato di modificare la query GraphQL per puntare a questa versione del campo:
{
someBuggyField(versionConstraint: "1.0.1")
}Se il bug è stato effettivamente corretto, solo allora copia il codice nel field resolver predefinito.
Chiedere a utenti selezionati di testare una versione imminente
Se un campo o una direttiva è versionato/a, e non ha un'implementazione predefinita (cioè non versionata), allora non apparirà affatto durante l'introspezione.
{
someField
# Questa direttiva non ha un'implementazione predefinita,
# quindi non apparirà durante l'introspezione,
# ma può comunque essere aggiunta nella query GraphQL
# fornendo un vincolo che la soddisfa
@someExperimentalDirective(versionConstraint: ">1.0")
}Puoi allora distribuire il campo o la direttiva e non sarà visibile nell'API GraphQL, e chiedere a utenti selezionati di testarlo/a, per cui devono inserire l'argomento versionConstraint corrispondente nelle loro query per utilizzarlo/a.
Una volta accettato/a, il versionamento viene rimosso, e il campo o la direttiva diventa visibile tramite l'introspezione, e quindi disponibile per tutti.