Casos de uso para el versionado de campos y directivas

Por favor, lee primero la guía Evolucionar el esquema mediante el versionado de campos, que explica la característica de "field versioning" en Gato GraphQL.

Gato GraphQL permite que los campos y directivas reciban el argumento versionConstraint, para elegir qué versión específica (es decir, implementación) del campo/directiva utilizar:

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

Un campo (o directiva) también puede tener una implementación por defecto, que es la que no tiene versión (y es la que se utiliza cuando no se proporciona versionConstraint en la consulta).

Al hacer introspección, solo se recuperan los datos de los campos y directivas por defecto. Como consecuencia, el argumento versionConstraint nunca aparecerá al hacer introspección, ya que el campo o directiva por defecto no lo admite.

Debido a esto, siempre debemos saber de antemano que un campo o directiva tiene dos o más versiones entre las que elegir, y debemos conocer cuáles son esos números de versión. Esta información es, por defecto, no pública.

Entonces, ¿de qué sirve el versionado? Aquí tienes varios casos de uso.

​

Proporcionar una corrección rápida de errores para algún usuario específico

Supongamos que tienes una API GraphQL desplegada en tu sitio web, y un usuario específico se queja de que el campo no funciona como se espera. Pero esto ocurre solo para este usuario; nadie más parece estar experimentando problemas.

Identificas y solucionas el problema, pero quieres asegurarte de que funciona antes de desplegar el cambio para todos. Entonces, puedes desplegar el cambio bajo un nuevo field resolver con versión "1.0.1", y pedirle al usuario con el problema que cambie la consulta GraphQL para apuntar a esta versión del campo:

{
  someBuggyField(versionConstraint: "1.0.1")
}Copy

Si el error realmente se solucionó, solo entonces copia el código al field resolver por defecto.

​

Pedir a usuarios seleccionados que prueben una próxima versión

Si un campo o directiva está versionado, y no tiene una implementación por defecto (es decir, no versionada), entonces no aparecerá en absoluto durante la introspección.

{
  someField
    # Esta directiva no tiene implementación por defecto,
    # por lo que no aparecerá durante la introspección,
    # pero aún puede ser añadida en la consulta GraphQL
    # al proporcionar una restricción que la satisfaga
    @someExperimentalDirective(versionConstraint: ">1.0")
}Copy

Puedes entonces desplegar el campo o directiva y no será visible en la API GraphQL, y pedir a usuarios seleccionados que lo prueben, para lo cual deben introducir el argumento versionConstraint correspondiente en sus consultas para usarlo.

Una vez aceptado, se elimina el versionado, y el campo o directiva pasa a ser visible mediante introspección, y por tanto disponible para todos.