En este artículo explicaré de forma práctica que y cómo documentar tanto un ecosistema de microservicios, como los microservicios de un ecosistema.
La documentación global del ecosistema se refiere a esa documentación que afecta a todo el ecosistema de microservicios. Esta documentación define las reglas de comportamiento dentro del ecosistema y los elementos comunes. Es decir, contiene toda la información que necesitará alguien que vaya a crear un microservicio dentro del ecosistema.
En líneas generales, la documentación global será más o menos extensa y restrictiva en función del nivel de madurez del ecosistema de microservicios, pero esta documentación nos marcará las reglas de comportamiento en las 3 grandes líneas de tecnología: definición del stack tecnológico, reglas de desarrollo (o best practices) y artefactos de arquitectura (o microservicios de arquitectura).
El stack tecnológico puede estar más o menos definido y ser más o menos impositivo en función de la madurez del ecosistema de microservicios
La documentación sobre el stack tecnológico describiremos las posibles decisiones que se hayan podido tomar a nivel global. Eso incluye tanto los lenguajes de programación como los productos y librerías seleccionadas. Mi recomendación es incluir también las descartadas así como los motivos, esto nos evitará repetir hunting tecnológico innecesarios.
Este apartado será más completo cuanto más restrictivo sea el ecosistema. En ecosistemas de microservicios poco restrictivo se deja libertad a los equipos para seleccionar el stack tecnológico de sus microservicios. Son los ecosistemas con un nivel de madurez mayor los que guían y controlan las decisiones tecnológicas a nivel global.
Las reglas de desarrollo o buenas prácticas hacen referencia tanto a las convenciones de desarrollo (o guías de estilo de desarrollo) como a los patrones de diseño como a temas más de gestión del ciclo de vida aplicativo.
La necesidad de establecer reglas en este sentido dependerá del nivel de madurez que queramos alcanzar con nuestros microservicios.
Convenciones de codificación o (Code Conventions) nos permiten establecer un sistema de codificación estandarizado que simplificará la lectura del código.
En este punto, lo más práctico es seleccionar y usar unas code conventions existentes en el mercado por 2 motivos:
- Al tratarse de estándares de facto, la curva de aprendizaje de nuevos perfiles será mayormente mucho más sencillas.
- Facilita el uso de herramientas de exploración y control del código.
- Es documentación completa creada por equipos de especialistas dedicados a crearla.
Os dejo unos cuantos ejemplos de Code Conventions de diferentes lenguajes de programación y/o frameworks:
- Java Code Conventions de Oracle
- PHP FIG-PSR
- PHP The Right Way
- Symfony coding standards
- C# Coding Convetions
- Android coding conventions
- React Coding Styles
- NodeJS Coding Style
Finalmente comentar, que la necesidad de seleccionar unos estándares de codificación o una guía de estilos de codificación dependerá de la madurez del ecosistema de microservicios. Es posible que en ecosistemas menos restrictivos donde no se limitan los lenguajes de programación, no tenga demasiado sentido hacer recomendaciones de este estilo a nivel global.
Los patrones de diseño son una herramienta de ingeniería del software que nos permite ponerle nombre a formas de estructurar el software. Ejemplos de patrones de diseño muy conocidos son el MVC, Façade, ... En el ámbito de los microservicios y sus ecosistemas existen tendencias dominantes en cuanto a partones a implementar. Para el control de la comunicación de los microserivios, el Event Driven es uno de los mas establecidos.
La documentación de los patrones de diseño no hace falta profundizar demasiado en que significan los patrones seleccionados, pero si que es necesario indicar cómo está hecha la implementación y cómo puede ser accedida desde un determinado microservicio.
Este apartado está anidado hasta este punto, pero en realidad puede tener más protagonismo puesto es el apartado de la documentación donde se describen los temas relacionados a ciclo de vida aplicactivo. Que herramientas se utilizan y como se utilizan.
En este punto, como siempre, recomiendo usar estándares de mercado, por ejemplo, si en tu proyecto vas a utilizar Git, generalmente la mejor opción es utilizar GitFlow para gestionar las versiones en lugar de inventar un nuevo sistema.
Los artefactos de arquitectura son elementos de software que proporcionan la capa de integración de microservicios. Por ejemplo, típicamente tendremos en este capa los servicios de autenticación y autorización, las colas de mensajería, los gateways específicos de un determinado front, …
La documentación de estos artefactos ha de estar muy orientada al usuario de los mismos. Suele ser una buena práctica intercalar explicaciones con snippets de código de ejemplo.
Mediante el uso de arquetipos podemos proporcionar a los equipos una estructura base que cumple con las especificaciones e integra las librerías/artefactos de arquitectura. Este tipo de complementos simplificará la integración de los microservicios, facilita la codificación de nuevos servicios y simplifica la necesidad de tener una foto global del sistema antes de iniciar el desarrollo.
La documentación de microservicio contendrá la información que el resto de microservicios necesitan para desarrollar las integraciones con el mismo.
Las funcionalidades se definen mediante historias de usuario que se aglutinan formando el backlog. Estas historias de usuario se refinan y se enriquecen con los casos de prueba del TDD (unitarias), BDD (funcionales) y ATDD (de negocio).
En mi experiencia, tener publicadas para otros equipos las historias de usuario permite tener una foto más clara de la lógica que implementa cada microservicio. Pudiendo ser referidas desde la documentación del propio servicio cuando esta requiera una documentación funcional más extensa.
Cada microservicio publicará eventos en la cola de eventos (lo mismo aplica en las interfaces de usuario cuando trabajamos con compoanentes).
Es necesario definir y documentar los eventos que un determinado microservicio lanzará a la cola y la información que incluirá. Si tenemos un equipo concienciado en mantener actualizada la documentación, también es recomendable documentar los eventos consumidos por cada microservicio y las acciones que se realizan (esto nos permitirá hacer análisis de impacto).
La API deberá documentar que hace cada uno de los servicios que tenemos publicados, cuales son sus parámetros, sus respuestas y los posibles casos de error.
Existen soluciones como Swagger que nos simplificarán mucho la documentación de la api. Esta herramienta nos permite documentar directamente inline en el código o bien tener la documentación en ficheros independientes. Lo cierto es que los detractores de la primera opción, prefieren documentar fuera porque los comentarios de swagger son muy extensos. A mi entender, y puesto que los editores de código moderno te permiten comprimir los comentarios, prefiero el uso de la documentación inline.
La documentación en código aporta valor a los desarrolladores, pero sobre este punto, yo tengo una idea bastante clara. La documentación en código se desactualiza y pocas veces es útil. Lo mejor para documentar el código es codificar de forma clara, usando nombres de variables, clases y funciones que sean human-friendly e intentar encapsular al máximo la lógica en funciones con nombres claros.