Desarrollo de GraphQL impulsado por directivas

Hola, mi nombre es Lenny Burdett y soy un arquitecto de soluciones en Apollo. Estoy emocionado de estar aquí hoy en GraphQL Galaxy para hablar sobre un prototipo en el que he estado trabajando, basado en un concepto que llamo GraphQL dirigido por directivas. Comenzaré con una breve discusión sobre los diferentes enfoques para construir APIs de GraphQL y cómo se puede elegir entre ellos. Luego haré una demostración rápida de mi prototipo para construir APIs de GraphQL sobre APIs de GRPC. Luego profundizaré en algunas decisiones de diseño en el prototipo que ilustran el poder del enfoque dirigido por directivas. Propongo que existen cuatro enfoques distintos para construir una API de GraphQL. Los primeros dos son términos conocidos en la comunidad de GraphQL, esquema primero y código primero. Con el enfoque de esquema primero, se escribe el esquema y los archivos de GraphQL y luego se escriben los resolvers en código. Con el enfoque de código primero, se escriben los resolvers y luego se deriva el esquema, probablemente utilizando metaprogramación o reflexión. Y hay mucha literatura sobre cómo elegir entre estos enfoques. Así que no voy a dedicar tiempo a esa discusión. En cambio, quiero dedicar tiempo a los otros dos enfoques que no tienen nombres conocidos hasta donde yo sé. Si los tienen, por favor avísenme. Para esta charla, los llamaré enfoque basado en datos y dirigido por directivas. Con un enfoque basado en datos, se genera tanto el esquema como los resolvers a partir de una descripción de la fuente de datos. Algunos ejemplos de este enfoque son post GraphQL para Postgres y GraphQL Mesh para una variedad de fuentes de datos. El enfoque dirigido por directivas, que definiré en un momento, todavía es bastante novedoso. Aún no conozco muchos ejemplos en la comunidad de GraphQL. Me encontré con este enfoque por primera vez cuando un colega mío en Square construyó una implementación realmente interesante dirigida por directivas para Elasticsearch. Trabajo con muchas empresas que construyen plataformas de GraphQL realmente grandes. Elegir un enfoque de desarrollo es una de las primeras decisiones que deben tomar. Como cualquier decisión de ingeniería, siempre se trata de equilibrar los compromisos. Tener un conjunto de valores ayuda a guiar el proceso de toma de decisiones. Aquí hay algunos de los valores que tengo, basados en mis experiencias personales y en el trabajo con clientes, que utilizaré para evaluar los enfoques de desarrollo de GraphQL en esta charla. Si tienes valores diferentes, probablemente tomarás decisiones diferentes, y eso está completamente bien. En primer lugar, siempre quiero priorizar un buen diseño de API y proporcionar un proceso de diseño de esquema colaborativo y ágil. Idealmente, mi API encuentra un equilibrio entre resolver casos de uso específicos y ser lo suficientemente generalizado como para admitir casos de uso nuevos e imprevistos. Esto es un desafío, especialmente a gran escala con docenas de equipos y clientes. Así que quiero evitar cualquier cosa que obstaculice un buen diseño de esquema. En segundo lugar, necesito la capacidad de evolucionar gradualmente mi API a medida que cambien las necesidades de los clientes y del negocio.

Esto incluye la capacidad de agregar tipos y campos, y también la capacidad de eliminar partes no utilizadas de mi esquema para mantener las cosas manejables. En tercer lugar, no quiero estar limitado a ninguna implementación o fuente de datos en particular. Cualquier sistema exitoso eventualmente necesitará una reescritura o algún tipo de migración. Puedes comenzar con Postgres, pero después de agregar unos millones de usuarios, es posible que te des cuenta de que sería mejor utilizar una combinación de DynamoDB y Elasticsearch. GraphQL es una gran capa de abstracción sobre estos detalles de implementación. No quiero que mis elecciones de hoy restrinjan lo que sea posible mañana. Este es un gran valor de Apollo y también lo considero importante. Creemos que los sistemas declarativos son preferibles a los sistemas imperativos. Si estás viendo nuestra charla sobre GraphQL, probablemente estés de acuerdo. El lenguaje de consulta declarativo de GraphQL es una gran mejora en comparación con escribir código imperativo para coordinar un conjunto de llamadas a API REST. Los sistemas declarativos suelen ser más fáciles de entender, admiten excelentes herramientas para el análisis estático y son mejores para la colaboración.

El modelo de composición declarativa de Apollo Federation es un ejemplo de nuestra inversión en esta idea. Y por último, cuanto más rápido y económico sea construir un sistema, más rápido podremos llegar al mercado y menos deuda técnica se acumulará en el camino. No sorprende que crea que un enfoque dirigido por directivas para GraphQL se ajuste mejor a estos valores. Así que sumerjámonos en esa idea y espero que estés de acuerdo. Un sistema dirigido por directivas implica dos siglas de tres letras diferentes que trabajan juntas. Primero, defines tu API utilizando el lenguaje de definición de esquema o SDL, y defines el comportamiento de tu API utilizando algún lenguaje específico de dominio o DSL. Con las directivas de GraphQL, estos pueden ir juntos en el mismo archivo. Para ejecutar una API dirigida por directivas, pasas tanto el SDL como el DSL a alguna implementación en una caja negra. Utiliza el SDL para proporcionar la API de GraphQL y utiliza el DSL para determinar el comportamiento de cómo obtiene datos de tus fuentes de datos.

He estado trabajando en un prototipo de un enfoque dirigido por directivas para construir una API de GraphQL sobre APIs de gRPC. Definitivamente, tengo mucho camino por recorrer, pero estoy emocionado de mostrar lo que tengo aquí hoy. Antes de sumergirme en el prototipo, quiero tocar brevemente gRPC para aquellos que no estén familiarizados con él. gRPC es un marco de RPC de código abierto que originalmente proviene de Google. Tuve la oportunidad de usarlo durante muchos años cuando trabajaba en Square. Creo que es realmente excelente para la comunicación este-oeste entre servicios. Es súper rápido y eficiente. Sin embargo, siempre encontré que era insatisfactorio cuando lo usaba en clientes web y móviles. Tiene muchas de las mismas desventajas que tienen las API REST. Mi insatisfacción con gRPC para clientes finales fue lo que me impulsó a aprender GraphQL en primer lugar. El formato de cable para gRPC se llama protocolo

Mi prototipo tiene tres componentes. Un generador de plantillas, un validador, y un tiempo de ejecución, que es la caja negra que mencioné anteriormente. El generador de plantillas está ahí solo para ayudarte a comenzar. Dada una definición de servicio de proto buffs, genera un esquema de GraphQL con un montón de directivas que declaran el comportamiento de todos los resolvedores. El resultado, sin embargo, no es una gran API de GraphQL. En realidad, es muy similar a la salida de un enfoque basado en datos, como GraphQL Mesh. Se mapea uno a uno con la API de gRPC, por lo que es realmente solo una API de RPC que resulta ser escrita en GraphQL. No modela un gráfico de datos, no se ajusta a los idiomas y mejores prácticas de GraphQL, algunos tipos y campos tienen nombres extraños y tiene un montón de tipos adicionales que ni siquiera son necesarios, y en lugar de modelar las relaciones entre tu gráfico de datos, generalmente solo tiene un montón de campos de clave externa. Pero la idea aquí es que esto es solo un punto de partida, y lo reescribirás para hacer la API que tus clientes realmente necesitan, y ni siquiera tienes que usarlo si prefieres comenzar desde cero. De cualquier manera, todo el trabajo se realizará en este único archivo de GraphQL.

Mientras editaba este esquema y usando mi DSL, me di cuenta rápidamente de que era difícil mantener un mapa mental de los tipos y campos de GraphQL a los mensajes y métodos de gRPC. Escribí un validador que me advierte si escribo mal un nombre de campo o si uso el tipo de salida incorrecto para un campo.

Lo que estás viendo aquí es cómo edito y modifico mi esquema generado en uno que sea más idiomático y se ajuste mejor a las necesidades de mis aplicaciones cliente. Puedo cambiar nombres de tipos y campos, eliminar capas innecesarias de indirección, construir relaciones entre tipos proporcionados por diferentes RPC, agregar documentación y mucho más. Para mí, esta es la parte más interesante del prototipo y algo que no he visto que nadie más haga. Muestra el poder del modelo de programación declarativa.

Puedo demostrar que el esquema es correcto solo mediante análisis estático. Me gustaría tener un poco más de tiempo para profundizar en esto, pero básicamente es un algoritmo de recorrido de gráfico en profundidad que recorre el esquema de GraphQL y compara los argumentos y tipos de retorno del campo con los métodos, mensajes y campos relevantes de gRPC. Una vez que hayas modificado el esquema para adaptarlo a los casos de uso de tu cliente, puedes ejecutar esta API con un solo comando. Aquí estoy ejecutando mi API de películas de GraphQL sobre una API de gRPC, y después de ejecutar una operación, puedes ver en los registros del servidor de gRPC qué métodos de RPC se llamaron para cumplir con los campos de esta operación. Funciona bastante bien y te sorprenderá lo simple que es la implementación. Básicamente, es solo un resolvedor único que se ejecuta en cada campo, pero sabe qué hacer en función de la presencia de directivas de aplicación. En este momento, tiene alrededor de 300 líneas de TypeScript.

El DSL de gRPC determina el comportamiento tanto de los componentes de runtime como de validación. Fue un desafío realmente divertido descubrir cómo expresar el comportamiento del resolvedor en un conjunto de directivas declarativas. Terminé con solo cuatro directivas.

La primera es simplemente para configurar el cliente de gRPC e incluye la capacidad de hacer cosas como reenviar encabezados para la autenticación y cosas así. Pasaré los próximos minutos mostrándote lo que puedes hacer con las otras tres directivas para construir fácilmente una gran API de GraphQL.

Una diferencia obvia entre gRPC y GraphQL es que gRPC no diferencia entre consultas y mutaciones. Un servicio de gRPC es simplemente una lista plana de métodos. La primera elección de diseño que hice fue que depende de ti decidir qué métodos son consultas y qué métodos tienen efectos secundarios y deben ser mutaciones. Todo lo que tienes que hacer es agregar campos raíz en los tipos de consulta y mutación y agregar la directiva fetch para declarar qué método RPC se utilizará como su resolvedor.

Es práctica estándar tener mensajes de envoltura de solicitud y respuesta únicos para cada método en una API de gRPC, como esta solicitud de obtener película y respuesta de obtener película. A veces quieres incluir estos tipos de envoltura en tu API de GraphQL, pero a veces no. Tomé la decisión de que los mensajes de entrada se mapeen directamente a los argumentos de campo de GraphQL, lo que elimina la necesidad del tipo de envoltura de solicitud. Para los tipos de respuesta, tienes la opción de incluirlo o no. Si quieres devolver solo la película que está incrustada en el mensaje de respuesta, puedes usar este argumento para extraerla de la respuesta y evitar esta capa adicional. Esto facilita mucho la construcción de una API de GraphQL idiomática.

Al realizar cambios en las API de estilo RPC, es común versionar los métodos y mensajes con espacios de nombres o convenciones de nomenclatura. GraphQL no tiene espacios de nombres ni un mecanismo de versionado y no quería agregar uno a mi DSL. Por lo tanto, en su lugar, tomé la decisión de no imponer ningún acuerdo entre los nombres de mensajes de GRPC y los nombres de tipos de GraphQL. El validador solo impone que los nombres de campo, nombres de argumento, tipos de retorno y tipos de argumento coincidan. Esto nos permite mantener la API de GraphQL consistente a medida que cambia la API subyacente, lo cual es una característica importante para evitar el bloqueo y reducir la rotación en las aplicaciones del cliente.

También quería la capacidad de solucionar la API orientada al cliente sin tener que cambiar la API subyacente. GraphQL es una gran capa de abstracción para realizar este tipo de correcciones. El flujo de trabajo de deprecación es un buen ejemplo de esto. Imagina que tenemos un campo de fecha en nuestra API de GRPC, pero nos damos cuenta de que el nombre es demasiado vago para nuestras aplicaciones de cliente. En su lugar, queremos llamarlo `premiered on`, que expresa mejor la intención de este campo. Podemos solucionar esto solo en el esquema de GraphQL deprecando el campo de fecha usando las directivas deprecadas incorporadas y usando esta directiva de renombrar para agregar un resolvedor para el nuevo campo que en realidad solo utiliza el mismo campo de GRPC internamente. Y ahora hemos mejorado declarativamente nuestra API sin tener que modificar la API subyacente.

Una de las mayores diferencias entre GRPC y GraphQL es que GraphQL modela un grafo de datos mientras que GRPC es básicamente solo funciones en un servidor remoto. No se puede modelar completamente un grafo utilizando protocol buffers, principalmente porque GRPC carece de la capacidad de seleccionar subcampos. Si tienes un grafo recursivo o relaciones bidireccionales, no podrás modelarlo de manera efectiva. En su lugar, es común que las API de GRPC incluyan claves foráneas y respuestas, lo que requiere que los clientes resuelvan la relación por sí mismos con otra solicitud de red. Si tengo un método RPC para obtener el tipo relacionado, puedo modelar declarativamente esta relación en mi API de GraphQL. En lugar de un campo ID para el director de las películas, puedo agregar un campo que devuelva un tipo complejo para representar mejor la relación. Y puedo agregar una directiva de búsqueda para declarar que el resolvedor de este campo llama a este método RPC. No estamos limitados a agregar una directiva de búsqueda solo a los campos de consulta y mutación raíz. Podemos agregarlas a cualquier campo en cualquier capa de nuestro esquema de GraphQL. Estos argumentos de directiva declaran cómo el campo ID del director en el objeto padre se mapeará al campo ID en el mensaje de solicitud del RPC.

Por supuesto, solo tienes que sumergirte en GraphQL para encontrarte con el problema de la consulta n más uno. En esta operación, si mi API de GraphQL devuelve diez películas, terminaré haciendo diez llamadas separadas para obtener la relación del director de cada película, lo cual no es ideal. La estrategia más común para lidiar con este patrón de cargador de datos, para lidiar con esto, es el patrón de cargador de datos, que almacena en caché y agrupa las solicitudes para realizar menos llamadas de red. Por lo tanto, agregué un argumento opcional de cargador de datos que te permite configurar el cargador de datos en este resolvedor. Puedes especificar claves de caché, cómo se utilizan para crear la solicitud en lote, y luego cómo hacer coincidir los resultados con esa clave de caché. Esto requiere que tu API de gRPC admita un método de obtención en lote, pero probablemente ya debería hacerlo, porque si no estás haciendo esto en tu API de GraphQL, probablemente estés obligando a tus aplicaciones cliente a manejar esto.

Además de admitir la federación, creo que esto señala otro beneficio del enfoque dirigido por directivas, la capacidad de combinar diferentes comportamientos simplemente agregando diferentes directivas en el mismo archivo. Apollo tiene una directiva de control de caché incorporada que podríamos agregar fácilmente aquí. También estamos trabajando en directivas para el costo de operación, autorización y muchos otros comportamientos que funcionarían bien en el sistema. Definitivamente hay mucho más por hacer en mi prototipo antes de que esté listo para producción. Algunas de las cosas en mi lista de tareas pendientes incluyen el soporte para uniones de GraphQL, donde Protobuf tiene esta palabra clave `oneof` y no es exactamente lo mismo, pero estoy bastante seguro de que hay una forma de traducir entre ellos con el DSL. Los errores de gRPC y los errores de GraphQL en realidad tienen más en común de lo que podrías pensar, pero no he dedicado mucho tiempo a tratar de averiguar cómo traducir entre ellos tampoco. Creo que hay algunas ideas realmente poderosas en este enfoque, incluida la capacidad de utilizar RPCs de transmisión de gRPC para alimentar suscripciones de data en tiempo real, pero hay mucho trabajo que tengo que hacer para descubrir cómo hacerlo. Y estoy seguro de que me he perdido muchas cosas. Me encantaría saber qué casos de uso y características te gustaría que aborde en este DSL hasta ahora.

Para concluir, quiero volver a visitar los valores de los que hablé anteriormente y evaluar cada uno de los enfoques. Los dos enfoques tradicionales, basados en esquemas y basados en código, son excelentes. No desaparecerán pronto. Permiten mucha flexibilidad en el diseño del esquema y la capacidad de evolucionar tu API y vincularla a cualquier fuente de data en el fondo. Pero según mi criterio, fallan porque son realmente costosos. Escribir todos esos resolvedores es una gran inversión inicial y resulta en mucho código que debes mantener durante mucho tiempo.

No pretendo menospreciar el trabajo de ingeniería involucrado en las soluciones basadas en datos. Algunas de las implementaciones son muy interesantes. Pero como estrategia a largo plazo, tengo mis dudas. Algunos de los clientes de Apollo han probado enfoques basados en datos, pero terminaron eliminándolos cuando vieron cuánto control tenían sobre el diseño del esquema y la evolución de la API. Por lo tanto, no es sorprendente que en mi tabla muy sesgada, el enfoque dirigido por directivas cumpla con todos mis requisitos. Pero espero que haya logrado argumentar que es un enfoque bastante convincente. La desventaja obvia es que todavía no existen muchas implementaciones dirigidas por directivas. Podríamos construir DSL que admita REST, SQL, SOAP, Thrift, funciones serverless arbitrarias, y tal vez muchas otras fuentes de datos. Incluso podríamos ponerlos todos en la misma implementación en una caja negra , lo que facilitaría mucho la construcción de APIs de GraphQL sobre la variedad de sistemas que nuestro equipo o empresa ya utiliza. Si el desarrollo de GraphQL dirigido por directivas te interesa, por favor revisa mi prototipo aquí en GitHub. Y si te gustaría trabajar en el desarrollo del futuro de los sistemas declarativos de GraphQL, Apollo está contratando. Gracias por tu tiempo y que tengas un excelente resto de la conferencia.