Mantener y documentar puntos finales API de muchas aplicaciones en una arquitectura de microservicio

Creo que uno de los mayores puntos débiles al trabajar con microservicios es asegurarse de que las API estén bien documentadas y que las API no cambien su comportamiento sin afectar las aplicaciones posteriores. Este problema se amplifica cuando tiene muchos servicios que son interdependientes entre sí. Quizás en ese momento estás haciendo mal los microservicios, pero estoy divagando.

Digamos que hemos heredado 20 microservicios que son propiedad de diferentes equipos y no existe una documentación clara sobre qué aplicación utiliza qué punto final de la API de otra aplicación. ¿Existe una forma prescrita de documentar esto? Al principio pensé en analizar los puntos finales de cada aplicación y agregarlos a una tabla de base de datos, luego crear una relación FK entre cada aplicación y la ruta de una aplicación en una tabla de muchos a muchos (casi todas estas son aplicaciones de rieles). Pero no estoy seguro si esta es una buena manera de manejar esto, o si estoy reinventando la rueda aquí.

En retrospectiva, esta podría ser una forma no tan mala de documentar la interacción de la aplicación si está comenzando con microservicios desde cero. Esto solo exigiría que se mantenga una única fuente de verdad mediante el uso de una base de datos y que cualquier cambio en los puntos finales se realizaría en la aplicación junto con el cambio en la base de datos. Pensamientos?

Una gran parte del beneficio de una "arquitectura de microservicios" es que no está documentando todas esas relaciones. Cada servicio es su propio producto. Y cada propietario del servicio es responsable de la operación de su servicio como un producto independiente. Eso puede incluir cosas como:

• Publicación de documentos de "marketing", documentos de usuario y registros de cambios (incluidas las depreciaciones )
• Proporcionar una forma para que los clientes / consumidores soliciten funciones / denuncien errores
• Mantener un SLA
• Realizar actualizaciones tan compatibles con versiones anteriores como sea posible y romper los cambios
• Conocer y ver las noticias de los servicios que consumen directamente
• Poda de dependencias cuando sea posible
• Depreciar todo el servicio cuando se vuelve irrelevante o demasiado costoso de mantener

Y así.

Sobre todo, enfatizaría, como uno de los principales beneficios de un microservicio, la oportunidad para que los propietarios de servicios realmente se concentren y se especialicen en la "única cosa" que hace su servicio.

En cuanto a dónde cada propietario del producto o servicio debe documentar sus propias dependencias, eso debería suceder "naturalmente" a medida que se agregan a la configuración de su compilador (o script de compilación). Si necesita saber de qué depende ServiceA , ServiceA/Configuration.xml(o lo que sea ) se lo informará. También normalmente esperaría que cada propietario del servicio diagramara inicialmente sus propias dependencias inmediatas , pero no dependencias de dependencias, etc. Y, dado que la información ya está en el código, no necesariamente esperaría que esos diagramas se mantengan en el futuro.

^{Si realmente desea una imagen global, escanee las secuencias de comandos de configuración / compilación. Lo que haga con ese resultado, cómo lo almacena, etc., depende completamente de las decisiones que los datos le ayudarán a tomar.}

Creo que una buena idea es crear un diagrama de integraciones e incluirlo en su repositorio. Elija alguna herramienta gratuita (como draw.io) que pueda exportar el diagrama en un archivo XML o JSON y confirme este archivo en su repositorio. Si usa Github o Gitlab, genere la imagen de este diagrama e inclúyala en el Wiki o incluso en el archivo README.md, de modo que la imagen sea visible cada vez que el desarrollador visualice el repositorio desde el navegador.

Se puede usar la misma estrategia para la base de datos.

Acerca de la documentación de recursos de API, Swagger es una buena opción.

Este problema se amplifica cuando tiene muchos servicios que son interdependientes entre sí. Quizás en ese momento estás haciendo mal los microservicios, pero estoy divagando.

Esto es un problema, seguro.