Construcción de APIs GraphQL de grado empresarial con Diseño Guiado por el Dominio y Arquitectura Limpia

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.

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.

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.

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.

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.

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.

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.

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.

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.