Lange Zeit haben wir große monolithische Systeme gebaut. Auch wenn der Ruf dieses Architekturstils nicht mehr der Beste ist, funktionieren manche diese Systeme doch seit vielen Jahren und erfüllen ihre Aufgabe zur vollen Zufriedenheit der Nutzer. Mit der Idee eines Microservice hat sich ein neuer Ansatz durchgesetzt. Dieser Architekturstil wird oft als Nachfolger der service-orientierten Architektur (kurz SOA) bezeichnet. Beide Architekturstile führen zu verteilten Systemen. Ein System aus vielen verschiedenen Microservices zusammenzustellen eröffnet vor allem hinsichtlich Robustheit und Skalierbar völlig neue Optionen. Microservices haben den großen Vorteil, dass es mit Technologien wie Spring Boot, Ratpack oder Dropwizard möglich ist, leichtgewichtige Lösungen zu bauen. Im reaktiven Manifest wird ein nachrichten-orientierter Architekturstil definiert, der ideal zu den Technologien aus dem Apache-Universum passt. Verteilte Verarbeitung von Datenströmen quasi in Echtzeit ist mit Storm, Spark oder Flink in Verbindung mit Kafka realisierbar.

Unabhängig vom Architekturstil besteht jedes System aus Diensten. Ein Microservice ist ein ein Dienst. In einem nachrichten-orientierten System mit Storm ist eine Topologie ein Dienst. Aber auch in monolithischen Systemen lassen sich Dienste identifizieren und realisieren.

Motivation

Mit dem Baustein Service wollen wir einen Dienst eines Systems beschreiben, weitestgehend unabhängig vom Architekturstil und der gewählten technischen Lösung. Dabei steht der fachliche Nutzen des Dienstes im Vordergrund. In einem agilen Projekt können wir die Entscheidung für die technische Umsetzung getrost dem cross-funktionalen Team überlassen. Am Ende der Umsetzung eines Dienstes wird der Steckbrief des Dienstes um eine kurze Beschreibung der tatsächlichen gewählten Lösung ergänzt.

Der Baustein Service beinhaltet Entscheidungen für bestimmte Technologien, die für die Umsetzung notwendig sind. Die Verwendung einer Technologie, die große Auswirkungen auf den Betrieb hat oder nur sehr schwer ausgetauscht werden kann, muss immer durch eine Entscheidung mit dem Baustein Decision begründet werden.

Wichtig ist, dass der Baustein Service dafür gedacht ist, einem Dienst eines Systems einen eindeutigen Namen zu geben. Der Name des Service wird auch im Code verwendet und schlägt damit die Brücke zwischen Wiki und Code. Abhängig von der Technologie, mit dem der Dienst realisiert wird, nutzen wir den Namen des Bausteins als Namensraum, als gleichnamige Klasse oder als Prefix für eine Menge von Klassen. Der Name kann aber auch als Bezeichnung einer Konfigurationsdatei verwendet werden.

Die dynamische und statische Sicht im Baustein soll dem Leser beim Navigieren im Code unterstützen. Wir wollen aber nur das dokumentieren, was wir nicht durch lesbaren Code bereits ausreichend dokumentiert haben. Mit Swagger kann beispielsweise ein REST-Service eindeutig beschrieben werden. Eine WSDL beschreibt ein Web-Service. Datentypen beschreiben wir mit einem XML-, AVRO– oder JSON-Schema. Docker nutzen wir, um agile Vorgehensmodelle, allen voran Scrum, und die Idee der DevOps optimal zu unterstützen. In der statischen Sicht beschreiben wir die Konfigurationsmöglichkeiten des Containers.

Code und andere Artefakte der Entwickler in einem Code-Repository sind somit Teil der Dokumentation. Ein Leser der Produktdokumentation wird durch den Baustein Service in die Lage versetzt, den Code für diesen Dienst zu finden und zu verstehen.

Weitere Quellen

Es gibt eine Reihe von Ansätzen, die Software-Architektur quasi als wissenschaftliche Disziplin betrachten, Kernaufgaben des Architekturentwurfs definieren und Vorlagen für die Dokumentation zur Verfügung stellen.

Das Kapitel 22 mit dem Titel “Using TOGAF to Define & Govern SOAs” beschäftigt sich ausschließlich mit der Frage, was für ein SOA-basiertes System in den verschiedenen Phasen dokumentiert werden kann. Interessant ist der letzte Satz:

When delivering SOA with TOGAF, the practitioner should never lose sight of the final objective: SOA solutions that address managing the enterprise’s complexity and provide business agility.

Der Software-Experte muss am Ende selbst entscheiden, was und wie genau er Elemente eines SOA-basierten Systems dokumentiert.

Quelle: TOGAF9 online documentation

In der Bausteinsicht wird die statische Zerlegung des Systems in Bausteine (Module, Komponenten, Subsysteme, Teilsysteme, Klassen, Interfaces, Pakete, Bibliotheken, Frameworks, Schichten, Partitionen, Tiers, Funktionen, Makros, Operationen, Datenstrukturen, …) sowie deren Beziehungen dokumentiert. Dienste werden als Teilsysteme beschrieben. Das Zusammenspiel der Bausteine wird in der Laufzeitsicht beschrieben.

Quelle: ARC42 online documentation

Definition

Beschreibung

Der Baustein Service beschreibt einen fachlichen Dienst des Systems und gibt ihm einen eindeutigen Namen. Der Name des Baustein wird auch für die Implementierung im Code-Repository verwendet und schlägt damit die Brücke zwischen Wiki und Code.

Der Baustein Service wird für Entwickler geschrieben.

Struktur

Abschnitt Steckbrief

Der Abschnitt enthält eine Tabelle mit Zeilen für eine Kurzbeschreibung des Dienstes und eine Liste der eingesetzten Technologien.

ktip Der Steckbrief wird so gestaltet, dass sich aus dem Namen, der Kurzbeschreibung und der eingesetzten Technologien sehr leicht ein Katalog erstellen lässt. In Confluence nutzen wir das Makro Seiteneigenschaften für den Steckbrief. Der Katalog wird mit dem Makro Seiteneigenschaftsbericht erstellt.
Abschnitt Beschreibung

Hier befindet sich der Überblick über den Dienst, d.h. eine Art “management summary” des Dienstes.

ktip Ein Komponentendiagramm ist an dieser Stelle hilfreich. Der Autor muss jedoch sicherstellen, dass er in der Lage ist, das Bild dauerhaft zu pflegen. In  Confluence nutzen wir das Konzept der Medienbibliothek für die Ablage der Bilddatei.
Abschnitt dynamische Sicht

Der Abschnitt enthält einen Überblick über das Verhalten dieses Dienstes, z.B. das Verhalten beim Start des Dienstes oder Besonderheiten der Datenverarbeitung und Datenhaltung. Wichtig ist, dass wir hier vor allem die Sicht von außen beschreiben. Abläufe im Inneren beschreiben wir nur ergänzend zum lesbaren Code als Spezifikation im gleichnamigen Abschnitt.

ktip Dieser Abschnitt ist sehr gut geeignet zur Verlinkung von Konzepten, die mit dem Baustein Spec beschrieben wurden.
Abschnitt statische Sicht

Der Abschnitt enthält einen Überblick über die Strukturen dieses Dienstes, z.B. ein Liste der Eingangs- und Ausgangsdaten. Wichtig ist, dass wir hier vor allem die Sicht von außen beschreiben. Strukturen im Inneren beschreiben wir nur ergänzend zum lesbaren Code als Spezifikation im gleichnamigen Abschnitt.

ktip Dieser Abschnitt ist sehr gut geeignet zur Verlinkung von Datenstrukturen, die mit den Bausteinen Event und Entity beschrieben wurden.
Abschnitt Spezifikation

In diesem Abschnitt befinden sich die Beschreibungen für Abläufe und Datenstrukturen im Inneren des Dienstes. Dazu zählen insbesondere Beschreibungen von Algorithmen und Geschäftsregeln. Auch die Möglichkeiten zur Konfiguration werden hier dokumentiert.

ktip Der Abschnitt liegt in der Verantwortung des Entwicklerteams. Es bietet sich an, ein Artefakt (z.B. eine Asciidoc-Datei) direkt aus dem Code-Repository zu verwenden und Confluence für die Veröffentlichung der Inhalte zu nutzen.