Formatear consultas GraphQL

Cómo funciona

Una consulta GraphQL copiada de la pestaña de red del navegador, de un registro de errores o de código JavaScript suele ser una sola línea larga en la que no se ve qué campo está dentro de cuál. Pegue la consulta en el cuadro izquierdo. A la derecha, cada campo pasa a su propia línea, las selecciones anidadas llevan 2 espacios de sangría y los argumentos (primeros: $cantidad, estado: ENTREGADO) llevan un espacio después de cada dos puntos y cada coma. Por ejemplo, {user(id:1){name}} se convierte en una consulta legible de cinco líneas. Los fragmentos, las definiciones de variables ($cliente: ID!), las directivas (@include) y las definiciones de esquema (type, input, enum) siguen el mismo estilo estándar. Con Una línea se hace lo contrario: se quitan los espacios de más, pero el texto entre comillas no se toca, y la consulta puede ir en una URL o en código. Si hay un error de sintaxis, se muestran su línea y su columna. La impresora estándar no conserva los comentarios escritos con #; la línea de resultado indica cuántos se quitaron.

Esta herramienta también se busca como formatear graphql, graphql formatter, formatear consulta graphql, graphql beautifier, ordenar graphql online, formatear esquema graphql.

¿Qué es GraphQL?

GraphQL es un lenguaje de consultas en el que el cliente describe exactamente qué datos quiere de una API. En REST cada dirección devuelve una respuesta fija; en GraphQL una consulta enviada a una sola dirección enumera los campos deseados entre llaves anidadas, y la respuesta llega exactamente con esa forma. Se creó en Facebook, y lo usan GitHub, Shopify y muchas API de aplicaciones. Consultas, mutaciones (cambios) y fragmentos (grupos de campos reutilizables) son sus piezas principales.

¿Qué es Fragmento?

En GraphQL, un fragmento es un grupo de campos con nombre que se repite en varias consultas: fragment Direccion on Pedido { calle ciudad } se define una vez y se agrega donde haga falta con ...Direccion. Así no hay que volver a escribir la misma lista de campos en cada consulta, y al agregar un campo solo cambia un lugar. El formateador escribe la definición del fragmento como un bloque aparte y el lugar donde se usa como una línea ...Direccion.

¿Cuál es la diferencia entre una consulta GraphQL y un esquema GraphQL?

Una consulta (query, mutation) dice qué quiere el cliente de la API: qué campos y con qué argumentos. Un esquema (SDL) define lo que ofrece el servidor: tipos como type Pedido { id: ID! importe: Float }, sus campos y el tipo de cada campo. Las consultas se validan contra el esquema; si se pide un campo que no está en él, el servidor devuelve un error. Esta herramienta da formato a los dos, pero no valida una consulta contra un esquema; solo revisa la sintaxis.

¿Dar formato cambia el resultado de la consulta?

No. En GraphQL los espacios, los saltos de línea y las comas no tienen significado; el servidor responde igual a la consulta formateada y a la de una línea. La herramienta lee la consulta con el analizador de graphql-js y escribe el mismo árbol con el estilo estándar; se conservan el orden de los campos, los alias, los valores de los argumentos y las cadenas.

La única diferencia son los comentarios: las líneas que empiezan con # no forman parte del árbol de sintaxis, así que la impresora estándar las deja fuera. Si sus comentarios importan, guarde el texto original; la línea de resultado indica cuántas líneas de comentario se quitaron. Las descripciones ("""...""") son parte del esquema y se conservan.

¿Qué revisa esta herramienta y qué no puede revisar?

La herramienta revisa la sintaxis: una llave sin cerrar, dos puntos que faltan, una coma o una comilla fuera de lugar aparecen con su línea y columna. Eso basta para saber si una consulta está rota antes de que llegue al servidor.

No valida contra un esquema: no puede saber si el campo que pide existe ni si un argumento tiene el tipo correcto, porque no tiene el esquema de la API. Para eso use la pantalla GraphiQL o Apollo Studio de la propia API.

• Leer una consulta de una línea sacada de los registros → Legible
• Poner la consulta en un parámetro de URL o en código → Una línea
• ¿Existe el campo, es correcto el tipo? → GraphiQL de la API

Preguntas frecuentes

¿Cómo hago legible una consulta GraphQL de una sola línea?

Pegue la consulta en el cuadro izquierdo de esta página. Cada campo pasa a su propia línea y las selecciones anidadas llevan 2 espacios de sangría. Puede copiar el resultado o descargarlo como archivo .graphql.

¿También se formatean las definiciones de esquema (type, input, enum)?

Sí. Además del lenguaje de consultas, la herramienta lee el lenguaje de definición de esquemas (SDL): las definiciones type, interface, input, enum, union y scalar siguen el mismo estilo estándar y se conservan las descripciones.

¿Por qué desaparecieron mis comentarios?

La impresora oficial de GraphQL no conserva los comentarios con #, porque no forman parte del árbol de sintaxis de la consulta. La línea de resultado indica cuántas líneas de comentario se quitaron; si las necesita, guarde el texto original.

¿Mi consulta se envía a un servidor?

No. El formato se aplica por completo en su navegador; la consulta, con los identificadores o valores que contenga, no sale de esta página y no se envía a ninguna API.