Agile Architectur Documentation - statische vs dynamische Dokumentation einer Software Architektur

04.11.2017


Während die Software-Industrie ihren Kunden die Digitale Transformation als eine zum Überleben notwendige Dienstleistung anbietet, scheint sie in den eigenen Reihen nur schwer Fuss zu fassen. Immer wieder begegnet man Prozessen innerhalb der Software Entwicklung die scheinbar von den notwendigen Schritten ausgeklammert werden. Während man in den Bereichen Development, Testing und Operations auf einer grossen Automatisierungs-Welle schwimmt, wird die Visualisierung dieser Prozesse und der Architektur einer Software oftmals noch aufwendig per Hand durchgeführt.

Einer der agilen Grundsätze besteht darin das sich der Plan der aktuellen Realität anpassen soll. Dies sollte auch für die Visualisierung und Dokumentation einer Software-Architektur gelten.

Da sich die Visualisierung und die Dokumentation in Zeiten agiler Architekturen im Gegensatz zur klassischen Vorgehensweise den ständigen Änderungen der Architektur anpassen muss, sind die oft statischen Lösungen die in der Entwurfsphase benutzt werden nicht mehr ausreichend. Während es auf der Enterprise Architektur Ebene in der Entwicklungsphase kaum noch zu Änderungen kommen sollte, ist dies bei den tiefer liegenden Schichten durchaus zu erwarten. Am stärksten davon ist sicherlich die Modul- und Code Ebene betroffen. Aber durch granulare Ansätze wie zb.: Microservice ist auch in abstrakteren Ebenen durchaus mit Änderungen während der Entwicklung zu rechnen.

Hier ist es der schlicht unmöglich manuell Schritt zu halten und so stehen wir schon nach kurzer Zeit einer veralteten Dokumentation der eigenen Software Architektur gegenüber.

Folgend möchte ich eine Variante aufzeigen, die folgende Vorteile zu klassischen Visualisierungs-Tools bietet.

  • Die Visualisierung bildet die aktuelle Realität ab.
  • Die zugrundeliegenden Modelle werden automatisiert generiert und der Visualisierung bereitgestellt.
  • Die Visualisierung kann in bestehende Software zur Dokumentierung automatisiert eingebunden werden.

Structurizr:

Structurizr scheint hier eine praktikable Lösung für diese Problemstellung zu sein. Es basiert auf dem C4 Model und unterstützt PlantUML zur Visualisierung.

Die kostenpflichtige Variante (SaaS) nimmt einem sehr viel Arbeit bei der Auswertung und Visualisierung ab. Das Architekturmodell wird mit Hilfe von Code erstellt beziehungsweise aus vorhandenem Code automatisch als JSON-File generiert und kann dann via Web API auf einen eigenen Workspace geladen werden. Hier gibt es gegenüber einer statischen Lösung einen initialen Aufwand, da der erforderliche Code für die Generierung eines Models in das Projekt implementiert werden muss.


Extract a Model:

Das Extrahieren des Models kann aus verschiedenen Ebenen erfolgen. Hierzu ein Auszug aus der Dokumentation:

  • Naming conventions: Perhaps you've unconsciously used a naming convention whereby all of your controllers, services and repositories (for example) are named *Controller, *Service and *Repository respectively.
  • Packaging and namespacing conventions: Or perhaps you've grouped everything related to a single component into a single package or namespace.
  • Machine-readable metadata: Alternatively, perhaps you've included metadata in the code to signify parts of the codebase as being significant in some way. This could be done using Java Annotations, C# Attributes, etc; whether they are proprietary or provided to you by a framework.
  • Module systems: Adopting a module system (e.g. OSGi, Java 9 modules, etc) might mean there's a very easy way to extract components from your codebase.

Um aus einer bestehenden Code-Base ein Model zu generieren können unterschiedliche Component-Finder Strategien verwendet werden. Drei der Strategien extrahieren das Model aus dem komplilierten Bytecode:

  • TypeMatcherComponentFinderStrategy - benutzt verschiedene TypeMatcher (NameSuffixTypeMatcher, ImplementsInterfaceTypeMatcher, RegexTypeMatcher and AnnotationTypeMatcher) um das Model anhand der verwendetet Typen zu erstellen. Diese Strategie bietet eine hohe Flexibilität bezüglich der Identifizierung. Sie kann unabhängig von eingesetzten Frameworks und Annotations eingesetzt werden da die TypeMatcher auf die gegebenen Umstände einer Code-Basis angepasst werden können.
  • SpringComponentFinderStrategy - Identifiziert Typen anhand ihrer Spring Annotationen und JPA Repositories. Diese Strategie eignet sich sehr gut bei Legacy Sytemen die Spring und JPA einsetzen, da hier keine zusätzlichen Anotationen eingeführt werden müssen.  - (@Controller, @RestController, @Component, @Service and @Repository, plus classes that extend JpaRepository )
  • StructurizrAnnotationsComponentFinderStrategy - Hier werden die Structurizr Annotationen ausgewertet, was eine entsprechende Vorarbeit bei Legacy-Code vorraussetzt. Dies ist besonders bei neuen Projekten die kein Spring und JPA einsetzen geeignet. - (@Component, @UsedByPerson, @UsedBySoftwareSystem, @UsedByContainer, @UsesSoftwareSystem, @UsesContainer and @UsesComponent )

Eine weitere Strategie wird auf den SourceCode angewendet.

  • SourceCodeComponentFinderStrategy - Diese Strategie findet keine Komponenten im eigentlichen Sinne. Sie extrahiert vielmehr den Top Level JavaDoc und fügt ihn bestehenden Komponent hinzu und berechnet die Grösse einer Komponente anhand der Zeilenanzahl des Source Codes.

Hier ist anzumerken das es um Komponenten geht, und nicht wie man nun vermuten würde um Klassen. Details der Implementierung wie Logik oder Attribute werden im Model nicht berücksichtigt. Dies ist aber bei einer Dokumentation einer Architektur auch nicht unbedingt erwünscht. Die vorhandenen Komponenten können aber mit den Klassen in einem Reporitory verlinkt werden, sodas direkt aus der Dokumentation in den Code gesprungen werden kann.

Supplement:

Natürlich können nicht alle Informationen zu einem System aus der Code-Basis extrahiert werden. Dazu kann das extrahierte Model manuel um die benötigten Informationen ergänzt werden:

The higher levels of the software architecture model (people, software systems and containers) are a little harder to extract from a codebase, so often it's easier to simply specify them manually. The Spring PetClinic example shows this technique in action.

Visualisierung und Dokumentation:

Die Structurizr Software stellt für den Workspace verschiedene Tools zur Visualisierung aber auch zur Dokumentation bereit. Ab diesem Zeitpunkt wird die Dokumentation aufgrund der Modelbeschreibung im JSON-Format automatisiert erstellt. Mithilfe von Workspaces können so auch mehrere Projekte abgebildet werden.

Es gibt mehrere Diagramm-Typen die es ermöglichen die verschiedenen Layer einer Software abzubilden. Dies wären zum Beispiel: Enterprise Context, System Context, Container-, Modul-, und Component Diagramme. Daneben gibt es noch die sehr nützlichen Dynamic Web oder Deployment Diagramme. Somit sollten alle benötigten Modelle erstellt und visualisiert werden können.

Die Visualisierung der generierten Modelle kann auf unterschiedliche Art erfolgen. Strukturizr stellt dazu mehrere sogenannte Explorations bereit die einem helfen sich durch die Architektur zu navigieren. Die Möglichkeiten sind hier sehr umfangreich und kann so leicht den jeweiligen Anforderungen angepasst werden.


Für die Dokumentierung werden Markdown oder AsciiDoc unterstützt. Hierzu gibt es bekannte Templates wie die von arc42, es könnten aber auch eigene Templates bereitgestellt werden. Die Dokumentation wird zusammen mit den Modellen im eigenen Workspace verwaltet.

Auch an die einfache Integration in bestehende Lösungen zur Dokumentation wurde gedacht. Es wird zum Beispiel das weit verbreitete Atlassian Confluence unterstützt. Hier ist dann sogar auf dem Confluence Marketplace ein Structurizr Macro vorhanden, was den Aufwand der Integration um einiges verringert.

OpenSource?

Eine weiter Variante wären die OpenSource .NET bzw Java API's von Structurizr. Natürlich mit mehr Aufwand verbunden ist es dadurch möglich auch ohne Kosten zu einer dynamischen Dokumentation zu gelangen.

Java API

.NET API

Mit Hilfe dieser Client API's können die Anforderungen gezielt für einen eigenen Client umgesetzt werden. Durch die API's bekommt man ebenfalls die Möglichkeit den Dokumentationsprozess automatisiert in den Build-Prozess einzubinden. Bei dieser Variante verzichtet man auf die vielfältige Verarbeitung die mit Structurizr möglich ist und übernimmt selbst die Verantwortung über die Art der Dokumentation und Visualisierung. Hierzu kann der Export des Models mit PlantUML und Graphviz and DOT vorgenommen werden. Über die PlantUML Confluence Erweiterung kann das Ergebnis auch in Confluence eingebunden werden, wenn auch nicht so komfortabel wie dies über das Structurizr Macro möglich ist.

Die Dokumentation von Sturcturizr ist sehr umfangreich und ist auch geeignet als Hilfestellung für die Umsetzung einer eigenen Lösung ohne der kostenpflichtigen Structurizr-Software.

Summary:

Abschliessen möchte ich zusammenfassen das der Aufwand zu Anfangs höher als bei statischen Lösungen für die Visualisierung ist. Dies wird aber meiner Meinung nach mit einer Liquid-Documentation belohnt die den agilen Ansätzen einer modernen Software-Architektur Rechnung trägt und so auch als Entscheidungshifle innerhalb eines Entwicklungsprozesses herangezogen werden kann. Hier lohnt es sich eine gewisse Einarbeitungszeit bereitzustellen um eine lebendige und langfristig brauchbare Dokumentation einer Software Architektur zu erstellen.

Structurizr biete noch viele weiter interessante Features und sollte daher von Software Architekten sorgfältig begutachtet werden.

Markus Wagner

https://structurizr.com

https://structurizr.com/help/atlassian-confluence

https://c4model.com/

https://plantuml.com/

FollowMe