Herramientas y Procesos para Gestionar GraphQL a Escala

Hola a todos. Esta charla te llevará a través de cómo es la vida como desarrollador de GraphQL en Yelp. Específicamente, quiero mostrarte algunas de las herramientas y procesos que hemos construido para hacer nuestras vidas más fáciles y para enviar cosas de manera más segura y rápida. Mi nombre es Mark, y soy líder del equipo de API de datos del cliente. Mantenemos la infraestructura de GraphQL utilizada por los desarrolladores de Yelp para construir nuestras aplicaciones web y móviles. Y si quieres ponerte en contacto conmigo sobre cualquier cosa que voy a decir, estoy en Twitter, es Mark underscore Lara. Si no estás familiarizado con Yelp, es un lugar para conectarse con excelentes negocios locales y encontrar dónde es bueno comer o encontrar fontaneros o mudanzas de los que puedes leer sus reseñas, ese tipo de cosas. Y aquí hay una página típica de un negocio de Yelp. Mira todos estos hermosos datos que hemos extraído de la base de datos. Se ve útil, ¿verdad? Así es como se ve esta página sin ningún dato. Lo cual no es muy útil. Así que creo que todos podemos estar de acuerdo en que los datos son buenos. Y nuestro trabajo es enviarlos a esta página de alguna manera. Lo que quiero hacer es llevarte en un viaje, y juntos pasaremos por la experiencia de hacer una solicitud de extracción y agregar un esquema para una nueva función en nuestro servicio de GraphQL. En el camino, compartiré los procesos y herramientas que hemos agregado para las personas, para que puedas tener una idea de cómo es nuestra experiencia como desarrolladores. Ahora, quiero establecer el escenario y compartir la escala de las cosas y por qué estamos invirtiendo mucho tiempo en esto. Entonces, GraphQL es el estándar moderno para hacer extracción de datos en Yelp. Es utilizado por cientos de desarrolladores en toda la organización. Hay más de 500 tipos en el esquema. 500 consultas persistentes activas. Es decir, consultas que se están utilizando en producción en las últimas dos semanas. Y en total, el servicio de GraphQL recibe alrededor de 10,000 QPS. Por lo tanto, mucho de Yelp depende de que esta cosa funcione de manera fluida y eficiente. Veamos cómo se ve eso. De acuerdo. Digamos que estamos creando un producto completamente nuevo en Yelp. Y puede haber algún esquema existente que podrías usar. Pero en su mayoría, tendremos que implementar alguna lógica nueva en el backend para esto. Entonces, lo primero que tendremos que averiguar es, bueno, ¿qué tipo de consulta quieres enviar? ¿Qué tipo de esquema queremos? Y obviamente, no queremos agregar simplemente lo primero que se nos ocurra y comprometernos con eso. Las malas elecciones de esquema pueden ser costosas y difíciles.

para eliminar una vez que se utilicen en producción. Por lo tanto, queremos mantener las cosas bastante flexibles hasta el punto en que realmente comprometamos el código. Ahora, tal vez seas nuevo en la empresa o nuevo en GraphQL, y aún no tengas una idea de lo que hay en el resto del esquema o cómo se ve un esquema idiomático en general. Y así, al escribir la consulta para tu nueva página, alentamos a los desarrolladores a simplemente escribir algo que se parezca a una consulta de GraphQL y haga lo que deseas. Y llamamos a esto la consulta de ensueño. Y esa es la consulta que desearías poder escribir si el esquema estuviera mágicamente disponible para alimentarla. Y a partir de ahí, tenemos un grupo de revisores de esquemas que pueden ayudar a revisar y señalar los tipos existentes y demás. Y hemos encontrado que esta es una buena forma de comunicar las cosas y de incorporar a las personas de una manera menos intimidante. He vinculado nuestra publicación de blog, que describe este proceso con más detalle y por qué nos gusta. Échale un vistazo al enlace en la diapositiva. Entonces, sí, sigamos adelante con nuestra nueva función y hemos escrito una consulta de ensueño que queremos usar en nuestra nueva página web. Y una vez que tengamos algo con lo que estemos razonablemente satisfechos y que se vea bien en papel, a continuación, podemos comenzar a elaborar el esquema que escribiríamos para alimentar esa consulta. Y supongo que realmente esto se puede hacer en paralelo con una consulta de ensueño. Somos grandes fanáticos de una herramienta, una herramienta de código abierto llamada GraphQL Faker. Es un poco como GraphQL o GraphQL Playground y crea un entorno de desarrollo para que puedas hacer consultas en él.

Pero también obtienes un editor para agregar nuevos esquemas y nuevos tipos sobre la marcha. Entonces, puedes consultarlos y obtener datos de lorem ipsum generados automáticamente. Y esto también se puede integrar y ampliar un esquema existente. Así que usamos esto para ampliar nuestro esquema GraphQL real y puedes hacer consultas que combinen el esquema real y tu nuevo esquema en progreso. Esta es una excelente manera de tener configurado un ciclo de iteración rápida y tener una idea del nuevo esquema que deseas agregar antes de dedicar tiempo a implementar los resolvers. Hemos hecho esto disponible globalmente en nuestras máquinas de desarrollo. Simplemente escribe un comando y inicia una instancia falsa de GraphQL, preconfigurada para comunicarse con una de nuestras instancias de desarrollo reales de GraphQL, y todo está mágicamente disponible. Puedes ir más allá y integrar esto en la aplicación React que estás desarrollando y probarlo con algunos componentes reales que estás desarrollando en la interfaz de usuario, al mismo tiempo, para que no tengas que esperar al backend. Y sí, esto es genial para paralelizar el trabajo entre los desarrolladores de backend y frontend. GraphQL Faker es genial. Recomiendo encarecidamente usarlo en tus flujos de desarrollo y proporcionar algunas herramientas ligeras a su alrededor para que sea fácil ampliar tu esquema real.

y úsalo en tus aplicaciones React. De acuerdo. Estamos muy contentos con nuestro nuevo esquema, y queremos invertir algo de tiempo en hacer que funcione de verdad e implementar los resolvers.

Instantánea rápida de la arquitectura. Esta es una descripción general aproximada de cómo se ve nuestra arquitectura. Esperemos que se vea algo familiar. Simplemente tenemos un montón de servicios diferentes propiedad de diferentes equipos que exponen APIs REST internas para diversos productos y casos de uso. Nos comunicamos con todos estos servicios a través del servicio de puerta de enlace GraphQL, que es nuestro servicio GraphQL ligeramente monolítico escrito en Node con Apollo Server. Y los resolvers necesitan obtener datos y comunicarse con estos puntos finales.

Aquí hay algunos problemas comunes. ¿Cómo evitamos sobrecargar el backend y hacer un montón de solicitudes de red innecesarias y desperdiciadas? ¿Cómo utilizamos correctamente los puntos finales en bloque? La respuesta principal son los data loaders. Apollo también tiene un patrón llamado data sources. Estoy seguro de que la mayoría de ustedes probablemente ya conocen los data loaders. Existen en varios lenguajes, pero si no, la idea principal aquí es que son una función mágica de agrupación y almacenamiento en caché sobre algún recurso subyacente. Si no tienes acceso directo a donde se encuentran los datos en tu servidor GraphQL, y necesitas conectarte a algún recurso externo, probablemente deberías estar usando

algo como esto. De acuerdo. Utilizamos data loaders. Pero como con muchas cosas en el desarrollo de software y en herramientas de código abierto, tienes algunos ejemplos básicos en la documentación y algunos tutoriales en línea, pero se vuelve complicado cuando queremos escalar esto y conectarlo con el resto de Yelp. El problema es que tenemos cientos de estos puntos finales HTTP internos que están distribuidos en cientos de servicios y el enfoque básico sería escribir a mano los cientos de data loaders para comunicarse con todos estos cientos de puntos finales, lo cual sería bastante engorroso por varias razones. Tenemos múltiples puntos finales que devuelven información de usuario. Por ejemplo, hay muchas representaciones diferentes de usuario, por lo que si alguien crea un data loader de usuario, ¿a qué punto final va? ¿Quién decide? ¿Cómo evitamos que las personas creen múltiples data loaders de usuario? ¿Cómo obtenemos tipado en estos data loaders? ¿Cómo nos aseguramos de que la gestión de errores y el registro sean correctos cada vez? Simplemente lleva tiempo escribirlo. Es otra cosa para mantener, etc. Así que puedes imaginar que todo este boilerplate inconsistente puede volverse bastante desagradable.

para manejar. La solución que encontramos fue una capa de generación de código llamada generación de código de data loader. Ya tenemos Swagger UI configurado para documentar todos los puntos finales internos en Yelp. La gente ya está acostumbrada a pensar en términos de estos puntos finales de Swagger y sus interfaces. Son muy utilizados y están muy bien documentados, una buena fuente de verdad. Queremos que la gente piense en términos de esos puntos finales. Y eso es lo que hace la generación de código de data loader. Tenemos un archivo de configuración y genera data loaders para cada punto final que especificamos. Entonces, piensas en términos de los puntos finales, no en los data loaders, que pueden tener diferencias sutiles. Y tenemos esta estricta correspondencia uno a uno. No es necesario pensar en qué data loader necesito para este punto final. Siempre será el verdadero. Y tendrá una interfaz coincidente. Y esto es genial. Entonces, la capa de data loader ahora es básicamente transparente. Es una cosa menos de la que preocuparse. Ahorra mucho tiempo escribirlos y mantenerlos y nos ha permitido escalar hasta tener cientos de data loaders, todos con el mismo manejo de errores y registro, etc. Incluso si no estás hablando con puntos finales REST detrás de escena, algunos de estos conceptos aún pueden aplicarse a tu situación. Creo que la conclusión aquí es que la generación de código y la eliminación de cosas mantenidas por humanos cuando sea posible es bueno. De todos modos, hemos abierto esto al público, y si estás interesado en obtener más información, puedes consultarlo en GitHub con el enlace de la diapositiva. Lo otro que recomiendo encarecidamente son los tipos generados para los resolvers. Utilizamos una buena biblioteca de Guild, GraphQL cogenerator, que también hace muchas otras cosas, pero la usamos para generar tipos a partir de nuestro archivo de esquema y los usamos para verificar el tipo de implementación en JavaScript. Es una victoria rápida y fácil.

Bien, ahora estamos realmente listos para confirmar nuestro nuevo esquema al confirmar el código, y utilizamos Precommits como un sistema de advertencia temprana para detectar problemas que romperían la compilación. Precommit es una herramienta que realiza verificaciones justo después de escribir git commit en tu terminal, pero antes de confirmarlo realmente, y esto es principalmente para cosas como linters y comprobadores de tipos y cosas que se ejecutan en CI, pero esto se ejecuta en tu terminal de inmediato. Entonces, no tienes que esperar 20 minutos para que CI falle y luego darte cuenta de que tenías un error de espacio en blanco. Además de verificar el formato del JavaScript, también verificamos el esquema, y para hacer esto, utilizamos una herramienta llamada GraphQL Schema Linter, y esto nos permite verificar un conjunto básico de convenciones de nombres y reglas de estilo, sí, es una herramienta realmente buena, y la ejecutamos en precommit, por lo que esto es lo que sucede si intentas pasar un esquema que sabemos que rompe las reglas. Muy bien. Suponiendo que todo salió bien, ahora es el momento de enviar tu solicitud de extracción, y lo primero que hacemos es tener un par de bots de GitHub para verificar más de tu esquema. El primero es el bot de verificación de esquemas, y este utiliza un paquete llamado GraphQL inspector para detectar cualquier cambio que rompa el esquema. Si encontramos cambios que rompen, como eliminar un campo o cambiar el nombre de un campo, mostramos una gran señal de advertencia como esta, y vamos un paso más allá, por lo que tenemos esta lista blanca de consultas, consultas persistentes, y sabemos cuándo se están utilizando las consultas, y podemos revisar todas las consultas que se están utilizando en las últimas dos semanas y decir, oye, parece que estás tratando de eliminar este campo, pero tenemos, como, estas 20 consultas que están utilizando este campo en producción en este momento, por lo que va a romper estas consultas, así que tal vez no lo empujes, por lo que es un buen sistema de advertencia y nos evita romper Yelp, como la solicitud de extracción realmente se volverá roja.

Si deseas eliminar un campo, pero no se está utilizando en producción, la verificación de GitHub pasará. Y, por otro lado, si realmente deseas eliminar un campo después de un proceso adecuado de desaprobación o limpiar algunos experimentos, entonces podemos decir que la lógica dice: bueno, estás eliminando un campo, pero en realidad no encontramos ningún documento que esté siendo utilizado en producción que utilice este campo, por lo que no romperá nada, puedes seguir adelante y la verificación de GitHub simplemente pasará para ti. Otro bot en el que nuestro equipo está trabajando actualmente es el bot de sugerencias de esquema, y esto es para cosas que creemos que podrían aplicarse a ti, pero que son inherentemente difíciles de verificar estrictamente, por lo que no queremos que la compilación falle por esto. Y esto podría ser cosas como, hey, estás agregando un nuevo tipo llamado horario de negocios, pero parece que ya hay un tipo llamado horario de apertura de negocios, así que tal vez quieras usar eso en su lugar, y tenemos un montón de reglas de expresiones regulares sofisticadas para detectar cosas que podrían estar rompiendo nuestras pautas de diseño de esquemas. Entonces, si creemos que encontramos algo, verás un comentario en línea en GitHub y puedes optar por hacer algo al respecto o ignorarlo como un falso positivo. Una vez que todo se ve bien, el paso final, final, es obtener la aprobación de alguien en nuestro grupo de revisión de esquemas, y estas son personas que están familiarizadas con nuestras pautas de diseño de esquemas, y este paso existe como una verificación adicional de seguridad final para asegurarse de que el esquema se vea bien. Inicialmente, esto era solo un pequeño grupo de desarrolladores para asegurarnos de tener consistencia en los primeros tipos y difundir ese conocimiento en toda la empresa, pero ahora está abierto a todos y es un módulo de aprendizaje que pedimos a las personas que completen y una vez que lo hayan completado, pueden unirse al grupo y aprobar nuevos esquemas. Intentamos tener dos revisores por equipo, pero hay desigualdades en algunos lugares, por lo que las personas manejan las revisiones de diferentes equipos cuando es necesario, y eso también es algo bueno, porque significa que no hay opiniones específicas del equipo sobre el esquema y todo se ve un poco más consistente en toda la empresa. Bien, una cosa final que quería mencionar es el valor de una documentación sólida. En el primer año en que implementamos GraphQL, diría que hubo una división absolutamente equitativa del tiempo dedicado a la codificación versus la documentación interna para iniciar el conocimiento de esta nueva cosa y servir como material de incorporación. Para una plataforma que muchos desarrolladores usarán con el tiempo, la documentación es tanto un producto como un enfoque y, sinceramente, solo la documentación y el pensamiento y el proceso que se le dedica podrían ser un tema de conversación en sí mismo, pero ese no es el tema más emocionante, así que eso es un tema para otra charla. Las únicas conclusiones importantes que daré aquí son que la mayoría de las veces, las personas de productos solo quieren centrarse en construir productos, y para la infraestructura, solo quieren ver cosas para copiar y pegar y no tener diferentes principios fundamentales. Todo lo que ves en el código abierto a veces de que no tenemos opiniones, usa x como quieras, es genial para el código abierto donde los autores no conocen tu configuración específica, pero internamente en la empresa, conocemos tu configuración y es nuestro trabajo como equipo de Infraestructura tener esas opiniones y crear abstracciones y establecer pautas tanto como sea posible para ahorrar tiempo a todos los demás en la empresa para que no tengan que hacerlo de un millón de formas diferentes. Entonces, tener todo eso listado en la documentación de solo hacer esto, descubrimos que funciona para nosotros. Estoy emocionado de decir que esta semana hemos compartido algunas de las páginas relacionadas con el diseño de esquemas. Por lo tanto, puedes consultarlas en GitHub con el enlace en la diapositiva para ver cómo diseñamos los esquemas en Yelp. Finalmente, si crees que nos hemos perdido algo que deberíamos estar haciendo, genial. Nos encantaría saber de ti. Estamos contratando. Así que visita la página de carreras.

Y sí, eso es todo lo que tengo. Gracias a todos. Tenemos una pregunta aquí. Preguntaste, ¿qué tan madura es la adopción de GraphQL en tu organización? ¿Qué opinas sobre estas respuestas? Sí, es muy interesante ver quién asiste a estas conferencias y el tipo de información que se aplica a ustedes en diferentes etapas de adopción. Obviamente, el nivel de inversión que deseen realizar en su infraestructura depende de cuántas personas esperen que la utilicen. Parece que se utiliza en muchos lugares, es una opción popular. Esperemos que haya muchas personas pensando en estas inversiones. Sí, seguro. Parece que muchas personas están investigando, pero ya se está utilizando. Eso es genial. Pasemos a algunas preguntas y respuestas de nuestra audiencia ahora. Tenemos una pregunta aquí que dice: El servicio de gateway de GraphQL parece un monolito. ¿Hay planes para dividirlo? Sí. Como escribí en el diagrama de arquitectura, todos los data loaders, toda la lógica del backend está en este servicio de gateway de GraphQL. Y aunque se pretende que sea una especie de proxy delgado sobre todos esos diferentes servicios y data loaders y puntos finales, ya sabes, se convierte en un poco de monolito, porque inevitablemente hay algo de lógica en ese servicio, y estamos hablando de cientos de estos resolutores, lo que crea problemas técnicos y problemas sociales, problemas técnicos que, ya sabes, los problemas habituales de los monolitos, como que se vuelve muy difícil trabajar en ese monolito porque tienes, como, cientos de pruebas que ahora podrían fallar cada vez que haces un pequeño cambio, y, ya sabes, hay conflictos de fusión y, ya sabes, lidiar con las convenciones de otros equipos y cosas así. Y luego hay problemas sociales, porque nuestro equipo es dueño de ese servicio y somos responsables de la infraestructura detrás de él, y tenemos, como, estas mejores prácticas que podrían, ya sabes, creemos que podrían aplicarse a todos, pero tal vez algún equipo tiene, ya sabes, queremos hacer las cosas de una manera específica. Entonces, y hay algunos asteriscos de rendimiento en los que no entraré en detalle, pero realmente parece que dividirlo de alguna manera probablemente será lo próximo, lo próximo grande en lo que nuestro equipo trabajará, y hay muchas respuestas a eso, como la federación, GraphQL mesh, así que definitivamente estamos trabajando duro en eso. Bien, entonces hay planes, próximamente. Sí. Genial. Entonces, sí, en la charla, mencionaste este GraphQL faker. Es algo que nunca he usado antes, y la integración de eso, y eso es algo en lo que tendré que investigar, porque parece muy interesante. Entonces, gestionar GraphQL, y obviamente, es posible que no tengas data para empezar. Entonces, tienes este faker, ¿verdad? Y eso es una gran ventaja. ¿Quieres ampliar algo de eso? Sí, mucho de lo que vemos son equipos que tienen páginas completas que se lanzan a producción y que podrían descartarse. Porque tenemos equipos de negocios que necesitan un ciclo de iteración muy rápido. Y tener algo que puedas crear una página como desarrollador web, no tienes que esperar necesariamente a un desarrollador del backend. Solo quieres algo que funcione. Necesitas jugar con esa consulta. Y también con el esquema. Entonces, ese ciclo de iteración rápida es algo en lo que nos enfocamos.

Mucho. Cuanta más información podamos obtener de eso. Mejor, más productivos seremos todos. Así que, siempre estoy atento a buenas herramientas como GraphQL o Faker. Y si alguien más conoce algo, alguna otra herramienta similar, por favor avísenme. Sí, me encanta cuando descubro nuevas herramientas. Tengo tantas herramientas. Las herramientas, nos ayudan sin importar en qué estemos trabajando. Probablemente haya una herramienta para eso.

Entonces, tenemos otra pregunta aquí. ¿Cuál es tu bebida preferida cuando trabajas en proyectos de gran escala? Oh, esa es una buena pregunta. Me gusta esa pregunta. Depende de cómo vaya el proyecto, ¿verdad? Sí, supongo. También depende de la hora en que esté trabajando. Yo personalmente soy amante del té, así que me gusta un buen té verde. ¿Caliente o frío? Entonces, ¿un buen oolong, tal vez? Sí. Bien, bien. Muy bien. Así que, los asistentes, continúen haciendo cualquier pregunta que puedan tener en el canal de preguntas y respuestas de Andromeda. Tenemos otra pregunta aquí. ¿Alguien tiene la lista de herramientas, o alguien tiene una lista de herramientas que Mark presentó? ¿Hay una lista en algún lugar? Puedo compartir las diapositivas en mi Twitter y compartir la lista de herramientas. Sí, puedo hacer eso. De acuerdo, de acuerdo, genial. Y finalmente, solo quiero decir que todo lo mencionado en las diapositivas requirió un gran esfuerzo de todo el equipo. Sé que algunos de ellos están viendo, así que les envío un saludo. Gracias a todos. Definitivamente, sí, no veo ninguna otra pregunta. ¿Hay algo más que sepas, en tu charla, que quisieras ampliar o algún plan futuro, algo más que quieras agregar para la audiencia? Bueno, si tuviera más tiempo, habría dedicado mucho más tiempo a la documentación. Lo mencioné brevemente en la charla. Y realmente fue un enfoque importante. No puedo enfatizar lo suficiente el valor de pensar mucho en eso, y no solo lanzar información en una página, sino tener un flujo de información considerado,

qué es relevante, cómo se ve. Tal vez sea un poco obsesivo, pero creo que eso es algo de lo que obtuvimos mucho valor. Y toda esta conferencia está dedicada a la documentación y sitios web y cosas así. Así que para cualquiera que lo implemente para muchas personas, sí, definitivamente. Sí, de acuerdo. Genial. Y tenemos otra pregunta aquí. ¿Utilizan alguna herramienta especial para organizar su documentación? La organización siempre es difícil para algunos de nosotros.

Utilizamos vPress como generador de markdown. Aparte de eso, es algo seleccionado a mano. Agregamos un pequeño tema, supongo, para que sea rojo para Yelp. Pero sí, aparte de eso, la página de pautas de diseño de esquema, que ahora es de código abierto, por lo que puedes ver que está seleccionada a mano y se hace de una manera que esperemos que fluya. Y también tenemos Iba a decir, algo que no incluí en las diapositivas es que además de la pestaña de documentación de esquema gráfico, también tenemos una especie de interfaz interna donde puedes ver todas las consultas y mutaciones que se han enviado a la lista permitida. Y eso es algo que te permite ver todas las consultas diferentes en Yelp. Y eso ayuda a servir como referencia para lo que es algún trabajo anterior y puedes filtrar por equipo y ver la evolución de una de esas consultas, etc. Sí. Bueno, nuevamente queremos agradecerte mucho por esta excelente charla. Si alguno de los asistentes tiene más preguntas para Mark, vayan a spatial chat a la sala de conferencias. Pueden hacer más preguntas allí. Mark, nuevamente, muchas gracias. Gracias. Cuídense.