Video Summary and Transcription
La charla de hoy se centra en la construcción de APIs GraphQL de grado empresarial con diseño guiado por el dominio y arquitectura limpia. El orador comparte su experiencia y enfatiza la importancia de entender el dominio empresarial y alinear el software con los requisitos empresariales. Discuten el enfoque por capas de la arquitectura limpia y los beneficios que proporciona para la separación de preocupaciones y pruebas. La charla también cubre el uso de la fusión de esquemas GraphQL y mapeadores para crear un esquema unificado. El orador concluye destacando la importancia de la observación constante, la evaluación y la mejora en el desarrollo de software.
1. Introducción a la construcción de APIs GraphQL
Hoy, voy a hablar sobre la construcción de APIs GraphQL de grado empresarial con diseño orientado al dominio y arquitectura limpia. Compartiré mi experiencia en la construcción de una API GraphQL escalable y mantenible al adoptar TypeScript, diseño orientado al dominio y arquitectura limpia. Puedes encontrarme en las redes sociales y echar un vistazo a mi blog y boletín informativo. Trabajo para Ant, S6, una empresa de consultoría de outsourcing con sede en Sofía, Bulgaria.
Hola a todos. Soy Peter, y hoy voy a hablar sobre la construcción de APIs GraphQL de grado enterprise con diseño orientado al dominio y arquitectura clean. Así que unas pocas palabras sobre mí. Como dije, soy Peter Ivanov. Aquí está mi identificador, así que puedes encontrarme en las redes sociales con este identificador. Y también me considero un desarrollador en forma de T. Si no estás seguro de qué es un desarrollador en forma de T, puedes consultar una de mis últimas entradas en el blog en mi sitio web personal, peterivanov.me. Y también tengo un boletín informativo, el Dev en forma de T. Así que si estás interesado, puedes echarle un vistazo. Y sí, aquí están mis enlaces a LinkedIn y mi cuenta de GitHub. Soy Ant, S6 es la empresa para la que trabajo. Somos una empresa de consultoría de outsourcing con sede aquí en Sofía, Bulgaria. Y el propósito de mi presentación es compartir mi experiencia en la construcción de una API GraphQL escalable y mantenible al adoptar TypeScript, diseño orientado al dominio y arquitectura clean.
2. Introducción a la Arquitectura y la API GraphQL
No tomes todo lo que comparto en esta presentación como absoluto. No entraremos en mucho detalle sobre qué es GraphQL, DDD y arquitectura limpia. Estamos hablando de backstadium.com, piénsalo como DigitalOcean o AWS para infraestructura Mac. Comenzaremos con la primera versión de nuestra arquitectura, dos aplicaciones web, una pública y una interna. La segunda versión es la versión actual, con toda la lógica de negocio dentro de la API GraphQL. La API GraphQL es el lugar central para toda la lógica relacionada con el negocio. Tenemos un único usuario, la API GraphQL, lo que facilita refactorizar y mejorar el diseño de toda la base de datos.
Y me gustaría comenzar con algunas aclaraciones. Y la primera es que no tomes todo lo que comparto en esta presentación como absoluto, porque el software puede construirse de múltiples maneras. Y también, dado que solo tenemos 20 minutos para esta presentación, no entraremos en mucho detalle sobre qué es GraphQL, DDD y la arquitectura limpia, porque nos centraremos en cómo diseñar y construir nuestra API.
Y ahora, algunas palabras sobre ello para darte algún contexto y qué tipo de software y qué tipo de negocio estamos hablando. Así que estamos hablando de backstadium.com, y puedes pensar en ello como DigitalOcean o AWS para la infraestructura Mac. Así que si no quieres comprar el Mac físico, el hardware real, pero quieres ejecutar algo en Mac, puedes ir allí y puedes comprar virtualmente el Mac y su infraestructura. Así que básicamente, tenemos las mismas cosas que tenemos en DigitalOcean o AWS. Así que tenemos facturación, tenemos cuentas, empresas, usuarios y cosas así. Solo para darte qué tipo de contexto y qué tipo de software vamos a construir y de lo que vamos a hablar a lo largo de la presentación.
Y ahora comencemos con la primera versión de nuestra arquitectura. Y aquí está. Así que tenemos dos aplicaciones web, una pública y una interna. La pública está construida con React, KXPHP, y la otra está construida solo con KXPHP. Y estos dos servicios llaman directamente a la base de datos o a servicios de terceros. Muy, muy simple. Y ahora pasemos a la segunda versión de la arquitectura, y esta es la versión actual de la arquitectura. Y aquí está. De nuevo, tenemos esas dos aplicaciones web, pero ahora toda la lógica de negocio está dentro de la llamada API GraphQL. Y aquí puedes ver la API GraphQL. Tenemos una gestión de cuentas, gestión de facturación, verás lo que es. Y aquí tenemos la API que llama a la base de datos o a servicios de terceros. No te preocupes. Ahora vamos a profundizar y explorar cómo logramos hacer esto y cómo lo hicimos.
La primera pregunta que tenemos que responder es por qué necesitamos la API GraphQL y cuál es su propósito. Y una de las razones principales es que es el lugar central para toda la lógica relacionada con el negocio. Esta es la API GraphQL. Y también en esto, al introducir la API GraphQL, tenemos en este caso la base de datos. Tenemos un único usuario, en nuestro caso la API GraphQL, lo que facilitará la refactorización y la mejora del diseño de toda la base de datos. Como viste en la primera versión de la arquitectura, teníamos dos clientes, pero la mayoría de las veces son más antiguos. Y ahora unas palabras sobre las tecnologías que decidimos usar.
3. Introducción a DDD y Lenguaje Ubicuo
Aquí, tenemos Node.js, Express, TypeScript, Apollo Server y GraphQL. El diseño guiado por el dominio (DDD) enfatiza la comprensión del dominio empresarial, se centra en la lógica empresarial central y alinea el software con los requisitos empresariales. El DDD estratégico implica implementar DDD como una práctica de desarrollo de software, comenzando con el lenguaje ubicuo y el contexto delimitado. El lenguaje ubicuo es un vocabulario común utilizado por todos los interesados, que define términos como cuentas, usuarios, perfiles de pago con tarjeta e facturas. El contexto delimitado establece límites lógicos dentro del dominio, permitiendo un trabajo en equipo eficiente y una comprensión compartida del lenguaje del dominio. Un ejemplo en nuestro caso es el contexto de gestión de cuentas, responsable de gestionar cuentas y usuarios.
Y aquí muy rápidamente, tenemos Node.js, Express, TypeScript, Apollo Server y GraphQL. Ahora, ¿qué es el diseño guiado por el dominio y por qué decidimos usarlo? Primero, ¿qué es el diseño guiado por el dominio y qué es eso? Una de las cosas clave aquí es que el diseño guiado por el dominio, o DDD, enfatiza la importancia de entender el dominio empresarial. También ayuda a los equipos a centrarse en la lógica empresarial central, y también al adoptar todo eso, hace que el software se alinee con los requisitos empresariales.
En nuestro caso, porque el diseño guiado por el dominio es un tema muy, muy amplio. Pero hay una cosa clave aquí, es el llamado DDD estratégico. El DDD estratégico significa que empiezas a implementar la práctica de diseño guiado por el dominio, como una práctica de desarrollo de software. Empiezas por averiguar dos cosas. El lenguaje ubicuo y el contexto delimitado. Ahora veamos qué son estas cosas.
Empecemos con el lenguaje ubicuo. El lenguaje ubicuo es un vocabulario y lenguaje común utilizado por todos los involucrados en el proyecto. Y como puedes ver, al tener este vocabulario común que es utilizado por todos, por todos nos referimos a todos los interesados, como los usuarios, expertos en el dominio y también los expertos técnicos. Todos los involucrados en el proyecto, parte de un tipo diferente de negocio digamos, el dominio empresarial, hablan y usan el mismo lenguaje. Así que todos pueden entender a todos básicamente. Esa es toda la cosa. Y en nuestro caso, definimos varias cosas que son parte del lenguaje ubicuo. Puedes pensar en ello como un diccionario, vocabulario, algo así. Así que tenemos cuentas, básicamente las empresas que son parte del sistema, los usuarios o empleados que son parte de la empresa o la cuenta. Tenemos perfiles de pago con tarjeta que son parte de la cuenta. Así que las empresas pueden pagar por lo que usan en el sistema. Y tenemos facturas y algunas otras cosas. Pero esas cuatro cosas de las que vamos a hablar a lo largo de toda la presentación. Por eso las añadí aquí.
Y ahora ¿qué pasa con el contexto delimitado? Primero, respondamos qué es esto. Así que el contexto delimitado es básicamente como un límite lógico entre las diferentes partes del dominio. Y al tener este límite lógico, podemos permitir que los equipos trabajen de manera más eficiente con una comprensión compartida del lenguaje del dominio utilizado en un área específica del sistema. Y ahora voy a darte un ejemplo muy breve, en nuestro caso básicamente. Así que aquí la primera cosa que tenemos, como un límite lógico es la gestión de cuentas. El contexto de gestión de cuentas, o dominio, es responsable de, como puedes imaginar, gestionar la cuenta. Así que aquí dentro tenemos cuenta y usuario.
4. Introducción a la Gestión de Cuentas y Facturación
La cuenta representa a la empresa y el usuario representa a un empleado. La gestión de facturación se encarga de todo lo relacionado con la facturación, incluyendo los perfiles de pago con tarjeta y las facturas. La arquitectura limpia, con su enfoque por capas, permite una mejor separación de responsabilidades y facilita las pruebas y el mantenimiento. Sin embargo, requiere un esfuerzo de ingeniería adicional. Nuestra base de código sigue los principios de la arquitectura limpia, con capas que apuntan hacia el interior. Tenemos tres capas, excluyendo la base de datos abstracta. Cada contexto delimitado, como la gestión de cuentas y la gestión de facturación, tiene su propia estructura, comenzando con las entidades como objetos JavaScript simples.
La cuenta, como dije, puedes imaginarla como la empresa, y el usuario, puedes imaginarlo como el empleado que forma parte de la empresa. Así que cada empresa puede tener varios empleados. Por otro lado, tenemos la gestión de facturación, y esta parte de la base de código, o el software, es responsable de gestionar todo lo que está relacionado con la parte de facturación. Y aquí tenemos el perfil de pago con tarjeta, y tenemos facturas, que forman parte de la facturación.
El principal. Y ahora pasemos a la segunda cosa, y es la arquitectura limpia. Al pensar en la arquitectura limpia, puedes pensar en ella como una arquitectura por capas. Y ahora ves por qué por capas. Quizás esta es la captura de pantalla más famosa y popular sobre la arquitectura limpia. Y me gustaría señalar dos cosas muy importantes aquí. La primera es, como puedes ver, tenemos las diferentes capas, los diferentes círculos, y cada círculo o capa es de un color diferente. Y cada capa es responsable de algo, básicamente de una cosa la mayoría de las veces. Y la segunda cosa muy importante aquí para mencionar y señalar es que cada capa apunta hacia el interior. Así que puedes ver que la azul apunta hacia la verde y luego la verde apunta a la roja, etc. Así que tenemos un flujo, como una dirección de cómo esas capas apuntan hacia el círculo más interno.
Y ahora veamos por qué decidimos adoptar esta arquitectura y este principio para hacer nuestra base de código de esta manera. Una de las mayores ventajas de este patrón es que permite una mejor separación de responsabilidades. Es muy fácil de probar de esta manera, y también es muy fácil de mantener toda la base de código y todo el software en el futuro. Pero por otro lado, una gran desventaja es que se necesita un esfuerzo de ingeniería adicional para implementarlo. Así que, sí, depende. Y ahora veamos cómo miramos a través del prisma de la arquitectura limpia y cómo la añadimos a nuestra base de código, a nuestro software. Y aquí vamos a... te mostraré las diferentes capas que tenemos. Como puedes ver, sólo tenemos tres porque la base de datos está abstraída como una infraestructura. Así que no hablaremos de la base de datos. Y sí, veamos. Y también es importante que, como dije, tenemos, digamos, dos contextos delimitados, la gestión de cuentas y la gestión de facturación. Y esta estructura que voy a compartir ahora es la estructura que tenemos para cada contexto delimitado. Y comencemos con el círculo más interno, el amarillo. Y aquí tenemos entidades, y las entidades son simplemente un objeto JavaScript plano.
5. Introducción a Capas y Servicios
No tienen estado y tienen un identificador único. Los servicios de dominio encapsulan la lógica de negocio con entidades. La capa verde consta de servicios de aplicación que manejan mutaciones y consultas. Los repositorios se utilizan para cargar o actualizar datos de dominio.
No tienen estado. Y tienen un identificador único, como un ID. Y los servicios de dominio son simplemente una encapsulación de alguna lógica de negocio que se maneja con entidades o algo similar. Luego, en la capa verde, tenemos servicios de aplicación. Y esto es como, de nuevo, encapsulación de alguna lógica de negocio que se utiliza en nuestro sistema. Tenemos mutaciones que son y también consultas que son mapeadas. Quizás si estás familiarizado con GraphQL, esto es lo mismo. Es una relación uno a uno. Así que nada, diría yo, extraño aquí. También tenemos repositorios y los repositorios se utilizan para, digamos, cargar o actualizar algunas entidades, algunos datos de dominio data.
6. Introducción al Esquema y Arquitectura de GraphQL
Y ahora nos estamos moviendo a la capa azul. Aquí tenemos el esquema de GraphQL. GraphQL permite la obtención de datos de moneda y mejora el rendimiento general de nuestra aplicación. Tenemos la API de GraphQL implementada con el servidor Polo. Cada contexto delimitado define su esquema de GraphQL, y utilizamos la Fusión de Esquemas para tener un solo esquema al que se refieren nuestros clientes. Ahora vamos a saltar al código.
Y ahora nos estamos moviendo a la capa azul. Aquí tenemos el esquema de GraphQL. Así que cada contexto define su esquema. También tenemos resolutores de GraphQL y estos resolutores de GraphQL son responsables de mapear los tipos de GraphQL con nuestros tipos de dominio. Y la mayoría de las veces, el tipo de GraphQL debería mapear 1 a 1 con las entidades. Pero no te preocupes, veremos esto en un ejemplo, porque esto es solo como una teoría, pero veremos el código.
Y sí, aquí también tenemos la API REST si es necesario y tenemos la API del módulo. Esta es la interfaz pública, la API pública que es definida por cada contexto delimitado. El otro contexto, los otros dominios pueden usarlo, pueden referirse a él. Y de esta manera, los diferentes contextos, los diferentes dominios, pueden comunicarse y hablar entre sí. Y ahora GraphQL. Y el GraphQL sirve como un paraguas en la parte superior de todo el contexto delimitado que comparto y muestro.
Y unas pocas palabras sobre GraphQL, qué y por qué. Así que GraphQL permite la obtención de data de moneda. También expone un único punto final HTTP que responde a las consultas. Y de esta manera, los clientes pueden recuperar data de múltiples contextos como un paraguas en la parte superior de ellos. Y básicamente, con GraphQL, podemos mejorar el rendimiento general de nuestra aplicación porque reducimos el número de solicitudes. Y también reducimos la transferencia de data que necesitan nuestros clientes. Y así es como logramos realizar toda esta architecture.
Como puedes ver, tenemos la API de GraphQL. Está implementada con el servidor Polo y nuestras aplicaciones web llaman a esta API de GraphQL a través de solicitudes HTTP. Y dentro de esta API de GraphQL tenemos dos contextos delimitados que pueden comunicarse entre sí a través de las APIs de módulo que han definido. Y también, cada contexto delimitado define su esquema de GraphQL. Y aquí utilizamos una técnica llamada Fusión de Esquemas que a través de la fusión de esos dos esquemas tenemos solo un esquema que es realmente referido por nuestros clientes. Y luego la API de GraphQL llama a la database y a los servicios de terceros. Y ahora voy a compartir un ejemplo contigo. Uno muy simple. Es un repositorio público en mi cuenta de GitHub. Así que tal vez hubo mucha teoría aquí, pero la necesitábamos.
7. Introducción al Código Fuente y al Dominio de la Cuenta
Y como no tenemos mucho tiempo para ver todo en el repositorio, puedes echar un vistazo. Es público. Y ahora vamos a centrarnos en el código fuente. Aquí tenemos módulos, cuenta y facturación. Tienen la API y son referidos desde otros módulos. También tenemos perfiles de pago con tarjeta definidos bajo el dominio de la cuenta. Aquí definimos todo lo relacionado con la cuenta, incluyendo el campo del perfil de pago con tarjeta.
Y ahora voy a saltar al código. Y como no tenemos mucho tiempo para ver todo en el repositorio, puedes echar un vistazo. Es público. Así que puedes dedicar más tiempo a mirar el código.
Y ahora vamos a centrarnos en el código fuente. Así que aquí el código fuente es en realidad el código fuente de nuestra aplicación. Y aquí tenemos modules. Modules o contexto delimitado o dominios es lo mismo. Son palabras diferentes, pero con el mismo significado. Y aquí tenemos cuenta. Y aquí tenemos facturación. Y ahora vamos a ver qué tenemos bajo la cuenta y bajo la facturación.
Como puedes ver, tienen la API. Aquí esta carpeta contiene la API del módulo. Así que esto es lo que se expone por este dominio, por este módulo. Y esto es referido desde los otros modules. Así que pueden comunicarse entre sí. Aquí tenemos la carpeta del dominio. Aquí tenemos modelos, mutaciones, consultas o servicios. Estos son los servicios de la aplicación. Aquí tenemos el GraphQL. Y ahora me gustaría mostrarte el esquema de GraphQL. Y como puedes ver, aquí tenemos el tipo de cuenta. Pero como dije en la presentación, también tenemos perfiles de pago con tarjeta. Y ahora voy a mostrarte dónde los definimos en realidad. Así que los definimos bajo — tal vez puedo dividirlo así, para que sea más fácil de ver. Como puedes ver, aquí tenemos el tipo de cuenta. Y bajo el tipo de cuenta, esto está bajo el dominio de la cuenta, bajo el módulo de la cuenta. Aquí definimos todo lo que está relacionado con la cuenta. A la derecha, tenemos el tipo de cuenta. Pero aquí definimos el campo del perfil de pago con tarjeta.
8. Introducción a la Fusión de Esquemas y Mapeadores
El dominio de facturación maneja el campo responsable de la cuenta. La cuenta y la facturación están organizadas en carpetas separadas. La técnica de fusión de esquemas combina las definiciones de tipo de los esquemas en uno solo. Los modelos representan las entidades en una simple aplicación de JavaScript. Los mapeadores se utilizan para mapear las formas de objetos de terceros a nuestras formas de objetos de dominio. Code.gen se utiliza para mapear entidades a tipos de GraphQL.
Porque este campo es responsable, debería ser manejado por el dominio de facturación. Y por este principio, hacemos para todas las cosas que son parte de nuestro software. Así que todo lo que está relacionado con la cuenta está bajo la carpeta de la cuenta. Y todo lo que está relacionado con la facturación está bajo la carpeta de facturación.
Y luego tenemos un script simple. Aquí puedes ver, construir esquema. Y aquí tenemos la técnica de fusión de esquemas donde fusionamos las definiciones de tipo de esos dos esquemas. Así que al final tenemos sólo un esquema. Aquí este esquema generado GraphQL. Bueno, esto es acerca de un esquema GraphQL.
Y otra cosa que quiero mostrarte, los modelos, como dije, aquí, estas son las entidades. Y aquí, esta es una aplicación muy simple de JavaScript. El id es el identificador. Y aquí las otras cosas. Los otros campos que son parte de los perfiles de Carpean. Y, sí, la consulta que compartí es como el mapa con la consulta GraphQL que conocemos. Y aquí también usamos el repositorio. Así que lo que tenemos bajo el repositorio. Sí, así que el repositorio, como dije, es para cargar algunos datos. Y aquí otra cosa interesante es que podemos usar mapeadores porque la mayoría de las veces, especialmente para la facturación, utilizaremos un servicio de terceros. Y para este servicio de terceros, tendrán perfiles de pago en una forma. Su objeto que es para el perfil de pago estará en una forma. Sin embargo, en nuestro sistema, probablemente queremos tener otra forma para el perfil de pago. Y aquí podemos usar los llamados mapeadores para que podamos mapear su objeto a nuestro objeto de dominio. Y de esta manera podemos tener esta consistencia para que podamos usar nuestro objeto dentro de nuestra base de código. Y sí, tal vez una cosa a señalar es que también usamos code.gen aquí para que podamos mapear nuestras entidades, nuestros objetos de dominio a los tipos de GraphQL. Y esto se utiliza a través de estos dos mapeadores. Pero puedes echar un vistazo en el repositorio de GitHub. Es público, como dije. Tengo dos diapositivas más, como un resumen.
9. Lecciones y Conclusión
Lecciones del viaje: Es difícil acertar desde el principio. Observa constantemente, evalúa y haz mejoras. No es necesario implementar DDD y arquitectura limpia al 100%. Adáptalo a tus necesidades. Construir software para una pequeña empresa es un desafío. Entiende el negocio y su dominio. Adopta el diseño impulsado por el dominio y la arquitectura limpia. La arquitectura ágil permite iteraciones rápidas y la resolución de problemas empresariales de la vida real. ¡Gracias por unirte a mi presentación!
Y algunas lecciones de todo el viaje es que es muy difícil acertar desde el principio. Así que no te preocupes, observa, evalúa y busca mejoras. Y siempre programa tiempo para pagar eso, porque lo que compartí ahora, esto no fue de ir de la versión uno a la versión dos directamente. Hubo mucho refactorización, muchos otros errores y fallos. Pero constantemente estábamos mirando lo que habíamos detectado e intentábamos pagar para resolverlo.
Y también, no es necesario implementar DDD y arquitectura limpia al 100 por ciento. Como te mostré, nosotros no lo hicimos. Así que adáptalo a tus necesidades y experiencia. Esta es quizás la lección más importante de nuestra presentación de hoy.
Como resumen, construir software para una pequeña empresa no es fácil. Deberíamos entender el negocio y su dominio. Utilizamos diseño impulsado por el dominio y arquitectura limpia para crear un sistema robusto y escalable. Y al final, la resultante arquitectura ágil permite iteraciones rápidas y cambios rápidos a los requisitos, mientras se está explorando el dominio. En total, hemos adoptado esas prácticas de desarrollo de software que compartí. Y al final, estamos modelando software para resolver problemas empresariales complejos de la vida real.
Y aquí también añadí un par de recursos. Y sí, espero que no estés cansado, que no estés muy aburrido y agotado. Y sí, este fue el final de mi presentación. Espero que te haya gustado. Y puedes encontrar las diapositivas y los otros materiales como el repositorio de GitHub en mi sitio web público. Si escaneas este código QR, irás directamente a mi sitio web y allí puedes encontrar las diapositivas. Así que muchas gracias por unirte a mi presentación. Espero que te haya gustado. También puedes dejarme algunos comentarios en las redes sociales para que pueda mejorar en el futuro. Y sí, muchas gracias. Y nos vemos la próxima vez.
Comments