Resumen
Este paper se centra en la implementación de una arquitectura limpia basada en GraphQL como Single Source of Truth (SSOT), donde tanto el frontend como el backend se alinean utilizando tipos, contratos y resolvers generados automáticamente. Además, explora cómo los servicios se implementan internamente en el sistema, orquestando operaciones complejas a través de los casos de uso (UC). Se analiza la flexibilidad de la arquitectura para soportar otras interfaces como REST o WebSockets, manteniendo siempre la separación de responsabilidades y asegurando que los desarrolladores sigan las convenciones internas establecidas para garantizar la integridad del sistema.
Nota: Para detalles más específicos sobre la estructura de archivos y el uso de herramientas como
gqlgenycodegenpara la generación automática de tipos e interfaces, consulte el paper anterior sobre la Implementación de un “Single Source of Truth” Basado en GraphQL: Integración de Go y TypeScript en tidy-core“.
Introducción: GraphQL como el SSOT y la Sincronización entre Frontend y Backend
La adopción de GraphQL como Single Source of Truth permite definir una única fuente de verdad para todas las estructuras de datos, queries y mutaciones del sistema. Este enfoque asegura la sincronización total entre el frontend (TypeScript) y el backend (Go), generando de manera automática tipos, contratos y resolvers que mantienen la integridad de la lógica de negocio.
Al centralizar las definiciones en GraphQL, se evita la desincronización entre las capas del sistema y se habilita un entorno donde los equipos de desarrollo pueden trabajar con un alto grado de confianza. Cada cambio en el esquema de GraphQL se refleja automáticamente en ambas partes del sistema, garantizando que tanto el frontend como el backend estén siempre alineados.
Este proceso no solo reduce los riesgos de error, sino que permite una evolución rápida del sistema, ya que cada modificación en el esquema es fácilmente adoptada por todas las capas de la aplicación.
Resolvers: Puentes, No Lógica de Negocio
Uno de los principios clave de esta arquitectura es que los resolvers de GraphQL deben actuar únicamente como puentes entre las peticiones del cliente y los casos de uso que contienen la lógica de negocio. Los resolvers no deben incluir ningún tipo de lógica de negocio directa, sino delegar las acciones a los casos de uso (UC) o servicios, manteniendo una estructura limpia y modular.
Este enfoque garantiza que:
- Los resolvers no se conviertan en puntos de acoplamiento con la lógica de negocio.
- En un futuro, si se decide implementar una API REST o manejar WebSockets, estas capas actuarán también como puentes que simplemente conectan con los mismos casos de uso o servicios que utilizan los resolvers de GraphQL.
Servicios: Orquestación Compleja y Convenciones Internas
En términos de convenciones internas del equipo de desarrollo, se ha definido una separación clara entre los servicios y los casos de uso. Los servicios se encargan de orquestar tareas complejas que involucran múltiples casos de uso, pero con la regla estricta de que los servicios nunca interactúan directamente con los repositorios.
Rol de los Casos de Uso (UC)
Los casos de uso son responsables de implementar la lógica de negocio directa y son la única capa que interactúa con los repositorios. Esto asegura que cualquier acceso a la base de datos o a fuentes externas esté correctamente aislado en la capa de casos de uso.
Rol de los Servicios
Por otro lado, los servicios son responsables de coordinar y orquestar operaciones complejas, como manejar varias transacciones, notificaciones, u operaciones multicomponente. Sin embargo, un servicio siempre debe utilizar los casos de uso como interfaz para acceder a los datos, asegurando que la lógica de negocio permanezca centralizada.
Interfaz Unificada para el Usuario de la API
Desde el punto de vista del usuario de la API (ya sea a través de GraphQL, REST o WebSockets), el sistema se comporta de manera uniforme. El usuario no debe preocuparse por si la operación que está ejecutando está manejada por un caso de uso simple o un servicio complejo. La API proporciona una interfaz unificada, donde cada operación es consistente y sigue las mismas reglas de entrada y salida, independientemente de su complejidad interna.
Esto permite que el sistema sea flexible y escalable, ya que los desarrolladores pueden migrar una operación de un caso de uso a un servicio más complejo sin afectar al cliente que utiliza la API.
Extensión a REST y WebSockets
Un punto fuerte de esta arquitectura es que permite una transición fluida a otras interfaces, como REST o WebSockets. La convención de mantener los resolvers como puentes facilita la creación de controladores REST o manejadores de WebSocket que cumplan exactamente el mismo rol:
- Los controladores REST y los manejadores WebSocket, al igual que los resolvers de GraphQL, actúan como puentes hacia los casos de uso o servicios.
- Al seguir este patrón, el equipo de desarrollo puede añadir nuevas interfaces sin duplicar la lógica de negocio ni modificar el comportamiento interno del sistema.
Esto asegura una flexibilidad total a nivel de arquitectura, permitiendo que nuevas tecnologías o canales de comunicación sean integrados sin afectar la estabilidad o modularidad del sistema.
Conclusión
El enfoque de GraphQL como SSOT, combinado con la separación clara entre servicios y casos de uso, ofrece una solución robusta para garantizar la coherencia y modularidad en un sistema complejo. La regla interna de que los servicios siempre deben utilizar casos de uso para acceder a los datos asegura una arquitectura bien estructurada, manteniendo la lógica de negocio centralizada y fácil de mantener.
Este enfoque no solo facilita el desarrollo y mantenimiento del sistema, sino que también permite la evolución natural hacia otras interfaces como REST o WebSockets sin sacrificar la consistencia o la integridad del código.
Para más detalles sobre la generación automática de tipos e interfaces a partir de GraphQL en los lenguajes Go y TypeScript, consulte el paper “Implementación de un Single Source of Truth Basado en GraphQL: Integración de Go y TypeScript en tidy-core”