Todo lo que (nunca) quisiste saber sobre la introspección

Hola y bienvenidos. Gracias por acompañarme en mi charla sobre GraphQL Galaxy, donde hablaré sobre la introspección, cómo puede ser útil y todas esas cosas. La idea para esta charla surgió cuando un colega me arrastró a una transmisión en vivo donde querían descubrir cómo obtener el autocompletado de consultas GraphQL en algunas herramientas de API. Y pensé que sería interesante compartir algunos de los conocimientos con otras personas también.

¿Quién soy yo? Mi nombre es Stephan Schneider y he estado trabajando con APIs durante aproximadamente cinco años y comencé a trabajar con GraphQL en 2018 cuando nuestra empresa estaba construyendo nuestra primera API GraphQL. Desde entonces, básicamente no he dejado de trabajar con ella y quiero darte algunos detalles más sobre la introspección. Así que tenemos esta ligera distinción de que generamos mil esquemas cada mes en Contentful porque nuestros clientes pueden definir su propio modelo de contenido y, basado en eso, les generamos una API GraphQL. Y para eso, también utilizamos la introspección en algunas de nuestras pruebas y eso será bastante interesante.

¿Qué es la introspección y por qué debería importarme? La introspección también es un término utilizado en psicología y realmente me gustan esos dos términos sobre la autoconciencia y la auto-descubribilidad y básicamente los he llevado ahora a la parte técnica de la introspección también. La autoconciencia significa que tu API sabe con qué tipo está trabajando y puede darte esa información sobre ellos. La auto-descubribilidad significa que es una forma estandarizada en la que el servidor puede hacer suposiciones sobre tus tipos y que puedes usar para obtener esos tipos del servidor. En comparación con REST, esta es una decisión de diseño anticipada del propio lenguaje. En REST, tienes que confiar en que pueda haber algún estándar que una API esté siguiendo como el especificación de OpenAPI, por ejemplo. Si no cumple con eso, básicamente no tienes más información sobre qué tipo de tipos proporciona y debes confiar en que se haya escrito una buena documentación para desarrolladores.

Veamos un ejemplo del mundo real. La mayoría de ustedes probablemente hayan trabajado con esto antes. GraphiQL. Las interfaces gráficas se incluyen con la mayoría de las implementaciones de servidor que tienes, y te permite realizar consultas en tu servidor GraphQL. Entonces aquí, por ejemplo, puedes ver que tenemos todos los tipos disponibles que nuestro esquema de Contentful conoce, por ejemplo, el Metadata de Contentful o la Etiqueta de Contentful. Luego, para todos esos tipos, también sabe qué campos tienes disponibles. Como puedes ver aquí, por ejemplo, también las descripciones de ellos. No solo eso, también tienes para todos esos campos, sus tipos y sus argumentos para los tipos también. Entonces, al final, GraphQL sabe todo lo que tu esquema contiene y puede darte autocompletado para ello. ¿Cómo funciona? Permíteme presentarte algunos tipos que es posible que nunca hayas visto antes, porque en realidad no forman parte de tu esquema, pero sí forman parte de tu esquema. Están ahí implícitamente. Entonces aquí, por ejemplo, tenemos en el tipo de consulta, dos campos más llamados __schema y __type. Los dos guiones bajos significan que están destinados a uso interno y no se te permite crear tipos que comiencen con dos guiones bajos. Son propiedad de GraphQL como lenguaje. También tenemos el tipo de esquema, que se devuelve cuando consultas el tipo __schema. El tipo de esquema luego contiene más campos que puedes usar para hacer consultas, los verás más adelante.

Por ejemplo, puedes consultar todos los tipos, o incluso un solo tipo en el objeto de consulta, y obtendrás información sobre ese tipo específico, como sus campos. Estos son implícitos, lo que significa que nunca aparecen realmente en tu esquema, no tienes que escribirlos tú mismo.

Luego, hay muchos más, y de todos ellos, creo que el más interesante es el __typename, es posible que ya lo hayas utilizado cuando has trabajado con interfaces o con tipos de unión. Puedes usarlos para diferenciar qué tipo real se devuelve en tiempo de ejecución, así tú y tu resultado pueden razonar sobre qué tipo de los dos o tres disponibles has recibido realmente. También son implícitos, no forman parte de tu esquema.

Esos tipos de introspección, ¿qué significa que son implícitos? Significa que no tienes que escribirlos, estarán ahí, y no hay forma de que olvides implementarlos o los implementes de manera diferente. Cada objeto de tipo siempre tendrá un campo de campos, y ese campo de campos no puede ser implementado de manera diferente, es parte de la implementación del servidor que estás utilizando. Si no te adhieres a esa implementación, básicamente no cumples con las especificaciones. Te brindan, por lo tanto, una interfaz estandarizada para trabajar con los tipos en tu sistema, y técnicamente puedes deshabilitarla, pero no puedes eliminarlos implícitamente de tu esquema. La deshabilitación se puede hacer en la implementación de referencia de GraphQL.js, por ejemplo, a través de una regla personalizada de introspección sin esquema, un nombre bastante práctico, pero implica que es una regla personalizada. Con eso, estás confiando en la fase de validación para evitar consultar el esquema o las propiedades del tipo o los otros tipos que están ahí implícitamente. Al prohibir la consulta de cualquiera de ellos, los has eliminado efectivamente de tu esquema, pero ten en cuenta que esto no significa que tu esquema esté a salvo de ser inspeccionado. GraphQL es bastante útil cuando se trata de errores. Dentro de esos errores, obtienes algunas sugerencias de completado, y esas sugerencias seguirán apareciendo incluso si tienes la introspección deshabilitada. Podrías forzar bruta tu API para que te devuelva esos nombres, así que no lo tomes como una medida de seguridad.

Echemos un vistazo a la consulta de introspección. Esta es la consulta de introspección en una forma muy abreviada porque la real tiene más de 100 líneas y no sería muy bueno mostrarla aquí en una diapositiva. Esta es una forma breve de ella y puedes importarla desde la implementación de referencia de GraphQL.js y te dará básicamente todo lo que el sistema de tipos sabe. Así que puedes verlo como una consulta de introspección completa.

Lo que hace es que te da todos los tipos, el tipo de tipo, por ejemplo, si es un objeto, un enum, una directiva, el nombre, la descripción y si está disponible, los campos están ahí. Así que realmente se basan en la característica de nulabilidad de GraphQL. Cada tipo tendrá la misma estructura y no necesitas hacer fragmentos o algo así para obtener los campos. Podrían ser simplemente nulos, entonces los campos serán nulos en la respuesta. Sin embargo, en el caso de objetos, realmente obtendrás los campos devueltos.

También podemos escribir nuestras propias consultas de introspección. Como dije anteriormente en la introducción, en Contentful estamos generando diferentes esquemas basados en la entrada del cliente. Así que pensamos que sería bastante útil probar que nuestras suposiciones de generación realmente sean correctas. Para una entrada dada, queremos comprobar que se generen un conjunto específico de tipos. Lo que hicimos fue escribir nuestra propia consulta de introspección, que llamamos aquí introspectar todos los nombres de tipo , que nos devuelve en el esquema todos los tipos y sus nombres. Luego, en una afirmación de prueba, podemos verificar que, por ejemplo, la consulta o el tipo de prueba CT estén disponibles en nuestra API. Con eso, básicamente puedes probar todas esas suposiciones con tus propias consultas de introspección sin tener que escribir las 100 líneas completas de código.

En este punto, es posible que te preguntes, bueno, ya tenemos el lenguaje de definición de esquema, ¿por qué no podemos usar eso? Sí, esto sería posible. Podrías tomar la cadena SDL, podrías analizarla en los tipos de objeto y luego podrías trabajar con ellos. Esto no es realmente la mejor experiencia. Además, hay otro problema. GraphQL es independiente del transporte. Si bien generalmente se sirve a través de HTTP, y es tan común que incluso hay una especificación de GraphQL sobre HTTP , técnicamente también podrías usar llamadas RPC, por ejemplo, o podrías tener algunas interacciones de web sockets. En esos casos, también quieres poder obtener tus resultados de introspección. Lo que no podemos hacer es simplemente crear otro punto final HTTP, porque esos no están disponibles, como RPC o web socket. Luego podrías pensar, bueno, podríamos ponerlos en un campo en algún lugar. Sí, puedes, y luego simplemente devolver una cadena muy larga que contenga tu SDL completa. En realidad, eso es lo que Apollo está haciendo cuando usas la Federación. En la Federación, luego tienes, creo que se llama tipo de servicio, y en ese servicio, tienes un campo SDL que te devuelve la cadena completa del SDL nuevamente. Para mí, eso se siente un poco hacky, pero entiendo el razonamiento, y también aprenderás sobre eso hoy. Los esquemas a menudo también se pueden filtrar o unir y todo, y solo quieres servir el final real, y tendrías que asegurarte de siempre devolver el correcto.

Pero la API unida en su introspección siempre conocerá todos los tipos que están unidos a ella, y no puede haber errores. No puede desincronizarse. Por lo tanto, las similitudes y diferencias entre SDL e introspección, creo que es bueno explicar por qué es tan útil tener la introspección, y también explicar por qué no podemos usar la introspección para la unión de esquemas.

Entonces, cuando tenemos un esquema, el esquema de GraphQL es como el tipo de dominio con el que siempre estamos trabajando. Por ejemplo, cuando lo pasamos a un servidor Apollo GraphQL en Express, todos trabajan en segundo plano con el objeto de esquema de GraphQL. El objeto de esquema de GraphQL se puede utilizar para ejecutar consultas en ellos, ejecutar validaciones en ellos, etc. Por lo general, construirías tu esquema a partir de una cadena SDL y lo pasarías a buildSchema. buildSchema también es proporcionado por la implementación de referencia de GraphQL.js, al igual que todas las demás funciones que estaré utilizando en esta sección. Puedes inspeccionar sus tipos a través de la introspección en el esquema y obtendrías un resultado de introspección que es la respuesta JSON que obtienes y puedes ver de la misma manera que, por ejemplo, GraphiQL recibiría. Incluso puedes tomar el esquema e imprimirlo nuevamente y obtendrías la SDL a partir de él. Aquí se conservan los espacios en blanco porque cuando lo estás analizando a partir de una cadena SDL, los tipos en el esquema conocen su posición y los espacios en blanco, por lo que al final debería ser una representación uno a uno de la cadena inicial que has analizado.

Hasta aquí todo bien. Veamos cómo funciona con la introspección. Cuando tienes un resultado de introspección, como puedes ver aquí, es simplemente una forma de objeto JavaScript en formato JSON, y puedes pasarlo a algo llamado Build Client Schema. Esto también es proporcionado por GraphQLJS. Una vez que lo hayas pasado allí, también estarás trabajando con un esquema, lo que significa que en ese esquema podrías llamar al método printSchema nuevamente y obtendrías una cadena SDL. Esta cadena SDL no conserva ningún espacio en blanco porque la introspección no es consciente de ellos, por lo que solo obtienes el formato predeterminado. Lo que también puedes hacer es tomar el esquema que has construido a partir de una consulta de introspección y realmente inspeccionarlo nuevamente. Esto es volver al punto de partida y el objeto inicial que has pasado y el nuevo que obtienes deberían ser iguales en profundidad. Esto significa que ahora hemos aprendido que realmente podemos tomar una SDL o una introspección y transformarla entre sí, lo cual es bastante útil. Entonces, ¿cuáles son las diferencias cuando podemos tomar ambas? Ambas pueden ser un esquema. ¿Por qué tenemos las dos formas diferentes? En la SDL, podemos tener algo llamado una directiva definida. Aquí tenemos la directiva add auth en un campo y luego podemos usar esto, por ejemplo, en un tipo de acceso mixto. El tipo de acceso mixto tiene un campo que es público y cualquiera puede acceder a él. Pero también puede tener campos privados, que simplemente llamamos privados aquí por conveniencia. Este solo puede ser utilizado por administradores. Entonces, el uso de la directiva add auth, decimos que solo puede ser consultado por un administrador. En la SDL, esta información se conservará, por lo que puedes construir un esquema a partir de ella e imprimirlo nuevamente como una cadena SDL. Se conservarán estos usos y sabrás qué campo tiene qué directivas aplicadas.

En el resultado de la introspección, por otro lado, no verás eso. Solo sabrás que hay una directiva definida en el esquema, pero no sabrás dónde se ha utilizado. Personalmente, creo que la razón de esto es que las directivas pueden tener cierta lógica de negocio que no quieres que se exponga, pero también hay una discusión extensa en el repositorio de GitHub. Si te interesa mucho, siéntete libre de participar allí y tal vez, algún día, no necesitemos la cadena SDL para usar federación u otro tipo de unión.

Para ver otro ejemplo bastante interesante de lo que puedes hacer con la introspección, está GraphQL Tools. GraphQL Tools es construido por el gremio. El gremio está haciendo muchas herramientas impresionantes en el ecosistema de GraphQL y permite transformar tu esquema de varias formas. Podrías decir que queremos agregar un prefijo a todos nuestros tipos con Contentful, porque lo estamos uniendo con, por ejemplo, el esquema de GitHub. No queremos tener conflictos en los tipos, así que simplemente los prefijamos. No hay problema con eso. También puedes filtrar tu esquema para exponer solo tipos específicos. Todos estos métodos de herramientas funcionan básicamente con dos primitivas que GraphQL ha definido, que son el esquema o el documento, también conocido como la cadena de consulta analizada. Una consulta siempre se analiza en un documento, y luego un documento se puede ejecutar contra el esquema. Esas son las dos primitivas, y cómo puedes obtener un esquema es mediante diferentes cargadores. Esos cargadores pueden tomar fuentes como una cadena, un archivo o incluso una URL. Y a partir de todo esto, generará un esquema con el que puedes trabajar. Aquí puedes ver ejemplos de cargadores.

El más fácil es simplemente una cadena como en un ejemplo anterior. Puedes simplemente pasar la cadena y delegará internamente a la función buildSchema y ahora tienes un esquema disponible. También puede tomar un archivo, para que no necesites leer el archivo por ti mismo antes de llamarlo, y puedes usar el cargador de archivos, pasarle un archivo.graphql y leerá el archivo, luego usa el método buildSchema, y nuevamente tienes un esquema con el que puedes trabajar. Creo que el más interesante para nuestra charla aquí es la URL. Puedes pasar a loadSchema una URL de tu punto final de GraphQL, y usar el cargador de URL. Una vez que hayas hecho eso, lo que sucede internamente es que se utiliza la consulta completa de introspección que proporciona GraphQL.js y se envía a tu punto final de GraphQL para que se ejecute allí. Luego, el resultado se alimenta de nuevo al buildClient schema, y tienes un esquema nuevamente. Básicamente hace exactamente lo que te he mostrado con más detalle anteriormente. Una vez que tienes un esquema ahora, puedes adjuntar resolutores a ellos si es necesario, si realmente quieres hacer ejecución o delegación. Básicamente puedes proporcionarles resolutores. En este punto, básicamente no hay distinción para ti de dónde proviene ese esquema. Simplemente puedes trabajar con él.

Para resumir lo que acabamos de aprender, la introspección te proporciona una forma estándar de trabajar con tu API y con los tipos que tiene.

Puedes, pero en realidad no necesitas escribir tu propia consulta de introspección. De hecho, la mayoría de las personas están bien con solo usar la consulta completa de introspección que proporciona la implementación de referencia. Si alguna vez necesitas hacerlo, simplemente puedes consultar partes de tu sistema de tipos.

El resultado en formato JSON que obtenemos, este resultado de la introspección, se puede utilizar para generar muchas herramientas tooling poderosas. Podemos tener interfaces para lenguajes de tipos como en JavaScript o en Java. Podemos obtener tipos de ellos que luego podemos usar para razonar mejor sobre con qué estamos trabajando. Podemos obtener una representación visual de nuestro esquema de API y ver cómo se relacionan diferentes tipos entre sí, lo cual puede ser bastante interesante, especialmente en un modelo más complejo, donde puedes ver, por ejemplo, que este campo apunta a este otro tipo y puedes ver cómo fluye a través de tu sistema.

Podemos obtener autocompletado de código, que es básicamente la razón de esta charla, como lo hace GraphicCode, que cuando escribes obtendrás todos los nombres de campo que coincidan con él, para que puedas usar el autocompletado y saber qué campos están disponibles. Lo cual también es bastante útil, puedes usarlo en tu pipeline de CI o CD para tomar el nuevo esquema de tu código actual y compararlo con lo que está en producción actualmente y detectar cualquier cambio que pueda romper la compatibilidad y adjuntarlo automáticamente a tu solicitud de extracción, por ejemplo. Incluso hay una tooling para eso, creo que incluso del Gremio, que hace exactamente esto.

El resultado de la introspección puede generar un esquema no ejecutable, por supuesto, toda la lógica de negocio que está en los resolutores no forma parte de la introspección, pero puedes generar un esquema a partir de ella y luego usarlo como desees. Y con eso, les agradezco su atención, si tienen alguna pregunta o comentario pueden contactarme en el enlace de Twitter aquí. Con eso, ¡diviértanse en la conferencia y adiós!