Porque la vida es demasiado corta para volver a dibujar diagramas. Recientemente me uní a una nueva empresa como . Como siempre pasa, tuve que empezar de cero. Cosas como: ¿Dónde está activo el código de una aplicación? ¿Cómo se implementa? ¿De dónde vienen las configuraciones? Afortunadamente, mis colegas hicieron un trabajo fantástico al convertir todo en "infraestructura como código". Entonces me sorprendí pensando: ingeniero de software si todo está en el código, ¿por qué no hay una herramienta para conectar todos los puntos? Esta herramienta revisaría el código base y crearía un diagrama de arquitectura de la aplicación, destacando aspectos clave. Un nuevo ingeniero podría mirar el diagrama y decir: "Ah, está bien, así es como funciona". Lo primero es lo primero Por mucho que busqué, no pude encontrar nada parecido. Las coincidencias más cercanas que encontré fueron los servicios que dibujan un diagrama de infraestructura. Puse algunos de ellos en para que puedas verlos más de cerca. Finalmente, dejé de buscar en Google y decidí intentar desarrollar algunas cosas nuevas e interesantes. esta revisión Primero, creé una aplicación de muestra con Gradle, y Terraform. La canalización de acciones de GitHub implementa la aplicación en Amazon Elastic Container Service. Este repositorio será una fuente para la herramienta que crearé (el código está ). Java Docker aquí En segundo lugar, dibujé un diagrama de muy alto nivel de lo que quería ver como resultado: Decidí que habría dos tipos de recursos: Reliquia El término me pareció demasiado sobrecargado, así que elegí . Entonces, ¿qué es una reliquia? Es el 90% de todo lo que quieres ver. Incluyendo pero no limitado a: artefacto Reliquia Artefactos (cuadros azules en el esquema, es decir, tarros, imágenes de Docker), Configura los recursos de Terraform (cuadros rosas en el esquema, es decir, instancias EC2, ECS, colas SQS), recursos de Kubernetes, y muchos muchos mas Cada Reliquia tiene un nombre (p. ej., my-shiny-app), un tipo opcional (p. ej., Jar) y un conjunto de pares clave → valor (p. ej., ruta → /build/libs/my-shiny-app.jar) que describe completamente la reliquia. Se llaman . Cuantas más definiciones tenga Relic, mejor. Definiciones Fuente El segundo tipo es una . Las fuentes definen, construyen o aprovisionan Reliquias (p. ej., cuadros amarillos arriba). Una Fuente describe una Reliquia en algún lugar y da una idea de su origen. Si bien las Fuentes son los componentes de los que obtenemos la mayor cantidad de información, normalmente tienen significados secundarios en el diagrama. Probablemente no necesites muchas flechas desde Terraform o Gradle a cualquier otra Reliquia. Fuente Reliquia y Fuente tienen una relación de muchos a muchos. Divide y conquistaras Cubrir cada fragmento de código es imposible. Las aplicaciones modernas pueden tener muchos marcos, herramientas o componentes de nube. ¡Solo AWS tiene alrededor de 950 recursos y fuentes de datos para Terraform! La herramienta tiene que ser fácilmente ampliable y desacoplada por diseño para que otras personas o empresas puedan contribuir. Si bien soy un gran admirador de la arquitectura de los proveedores Terraform increíblemente conectables, decidí construir la misma, aunque simplificada: El tiene una responsabilidad clara: crear Reliquias basadas en los archivos fuente solicitados. Por ejemplo, lee archivos *.gradle y devuelve , o Relics. Cada proveedor construye reliquias de los tipos que conoce. A los proveedores no les importan las interacciones entre Reliquias. Construyen Reliquias de forma declarativa, totalmente aisladas unas de otras. Proveedor GradleProvider Jar War Gz Con ese enfoque, es fácil llegar tan profundo como quieras. Un buen ejemplo son las acciones de GitHub. Un archivo YAML de flujo de trabajo típico consta de docenas de pasos que utilizan componentes y servicios poco acoplados. Un flujo de trabajo podría crear un JAR, luego una imagen de Docker e implementarlo en el entorno. Cada paso del flujo de trabajo podría estar cubierto por su proveedor. Entonces, los desarrolladores de, digamos, crean un proveedor relacionado solo con los pasos que les interesan. Docker Actions Este enfoque permite que cualquier número de personas trabajen en paralelo, añadiendo más lógica a la herramienta. Los usuarios finales también pueden implementar rápidamente sus proveedores (en el caso de alguna tecnología patentada). Vea más en Personalización a continuación. Fusionar o no fusionar Analicemos la siguiente trampa antes de pasar a la parte más jugosa. Dos proveedores, cada uno de los cuales crea una reliquia. Está bien. Pero ¿qué pasa si dos de estas Reliquias son sólo representaciones del mismo componente definido en dos lugares? Aquí hay un ejemplo. analiza la definición de tarea JSON y produce una Reliquia con el tipo . El flujo de trabajo de acciones de GitHub también tiene un paso relacionado con ECS, por lo que otro proveedor crea una reliquia de . Ahora tenemos duplicados porque ambos proveedores no saben nada el uno del otro. Además, es incorrecto que cualquiera de ellos asuma que otro ya ha creado una Reliquia. ¿Y que? AmazonECSProvider AmazonECSTask AmazonECSTaskDeployment No podemos descartar ninguno de los duplicados debido a las Definiciones (atributos) que tiene cada uno de ellos. La única manera es fusionarlos. De forma predeterminada, la siguiente lógica define la decisión de fusión: relic1.name() == relic2.name() && relic1.source() != relic2.source() Fusionamos dos Reliquias si sus nombres son iguales, pero están definidas en Fuentes diferentes (como en nuestro ejemplo, JSON en el repositorio y la referencia de definición de tarea está en Acciones de GithHub). Cuando nos fusionamos, nosotros: Elige un solo nombre Fusionar todas las definiciones (pares clave → valor) Crear una fuente compuesta que haga referencia a ambas fuentes originales. Dibuja una línea Omití intencionalmente un aspecto crucial de una reliquia. Puede que tenga un ... ¡y es mejor tenerlo! Matcher es una función booleana que toma un argumento y lo prueba. Los emparejadores son piezas cruciales de un proceso de vinculación. Si una Reliquia coincide con cualquier definición de la Reliquia de otra, estarán vinculadas entre sí. Matcher ¿Recuerdas cuando dije que los Proveedores no tienen idea de las Reliquias creadas por otros Proveedores? Eso sigue siendo cierto. Sin embargo, un Proveedor define un Comparador para una Reliquia. En otras palabras, representa un lado de una flecha entre dos cuadros en el diagrama resultante. Ejemplo. Dockerfile tiene una instrucción ENTRYPOINT. ENTRYPOINT java -jar /app/arch-diagram-sample.jar Con cierta certeza, podemos decir que Docker todo lo que se especifica en . Entonces, Relic tiene una función Matcher simple: . Lo más probable es que algunas Relics con en las Definiciones coincidan. En caso afirmativo, aparece una flecha entre y Relics. contiene ENTRYPOINT Dockerfile entrypointInstruction.contains(anotherRelicsDefinition) Jar arch-diagram-sample.jar Dockerfile Jar Con Matcher definido, el proceso de vinculación parece bastante sencillo. El servicio de enlace itera sobre todas las Reliquias y llama a las funciones de su Matcher. ¿La Reliquia A coincide con alguna de las definiciones de la Reliquia B? ¿Sí? Agrega un borde entre esas Reliquias en el gráfico resultante. También se podría nombrar el borde. Visualización El último paso es visualizar nuestro gráfico final de la etapa anterior. Además del PNG obvio, la herramienta admite formatos adicionales, como , y . Estos formatos de texto pueden parecer menos atractivos, pero la gran ventaja es que puedes incrustar esos textos en casi cualquier página wiki ( , y muchos más). Mermaid Plant UML DOT GitHub , confluencia Así es como se ve el diagrama final del repositorio de muestra: Personalización La capacidad de conectar componentes personalizados o modificar la lógica existente es esencial, especialmente cuando una herramienta se encuentra en su fase inicial. Las reliquias y las fuentes son lo suficientemente flexibles por defecto; puedes poner lo que quieras en ellos. Todos los demás componentes son personalizables. ¿Los proveedores existentes no cubren los recursos que necesita? Implemente el suyo propio con facilidad. ¿No está satisfecho con la lógica de fusión o vinculación descrita anteriormente? Ningún problema; agregue su propia o . Empaque todo en un archivo JAR y agréguelo al inicio. Leer más . LinkStrategy MergeStrategy aquí Outro La generación de un diagrama basado en el código fuente probablemente ganará terreno. Y la herramienta en particular (sí, este es el nombre de la herramienta de la que estaba hablando). ! NoReDraw ¡Los contribuyentes son bienvenidos El beneficio más notable (que proviene del nombre) es que no es necesario volver a dibujar un diagrama cuando cambian los componentes. La falta de atención de ingeniería es la razón por la cual la documentación en general (y los diagramas en particular) se vuelven obsoletos. Con herramientas como , ya no debería ser un problema, ya que se puede conectar fácilmente a cualquier canal de PR/CI. Recuerde, 😉 NoReDraw la vida es demasiado corta para volver a dibujar diagramas
