Der Baustein Service


Methode

Moti­vation für den Ein­satz

Unab­hängig vom Archi­tektur­stil besteht jedes IT-System aus Diensten. Ein Micro­service mit einem REST-API ist ein ein Dienst. In einem reaktiven IT-System gibt es Dienste, die Nach­richten­objekte produ­zieren oder konsu­mieren. Auch in mono­lithischen IT-Systemen mit klassi­schen Appli­kations­servern lassen sich Dienste identi­fizieren. Der Bau­stein Service ist ein Arte­fakt der System­struk­tur, mit dem wir solche Ergeb­nisse der Soft­ware-Ent­wick­lung doku­mentieren. Dabei steht der fach­liche Nutzen des Dienstes im Vorder­grund. Der Titel des Bau­steins gibt einem Dienst einen ein­deutigen Namen.

Autoren wollen im Bau­stein Service nur das doku­mentieren, was Ent­wick­ler nicht durch les­bare Teile vom Code oder code-nahe Arte­fakte bereits aus­reichend gut doku­mentiert haben. Mit Swagger kann beispiels­weise ein auf REST basieren­der Dienst spezifi­ziert werden, mit WSDL ein auf SOAP basieren­der Dienst. Autoren beschrei­ben im Wiki nur, was sich gar nicht oder sehr schwer aus dem Code heraus­lesen lässt.

Wissens­­­­­manage­­ment richtig organi­­sieren.
Ziel­gerichtet. Agil. Iterativ.


Pro­zesse

Pro­jekt­manage­ment

Der Pro­dukt­­verant­wort­liche hat mit dem Bau­stein Service die Mög­lich­keit, früh­zeitig einen wich­tigen Dienst als Ent­wurf zu erfassen, wenn es für das Ver­ständnis der Anwen­dungs­domäne hilf­reich ist. Er macht das in Abstim­mung mit dem Team.

Im Steck­brief des Bau­steins befindet sich eine Liste der geplan­ten Techno­logien für die Implemen­tierung des Dienstes. Das ist eine sehr wert­volle Infor­mation für das Archi­tektur­manage­ment, um Themen wie Lizenz­kosten, tech­nische Unter­stützung vom Her­steller oder unter­nehmens­weite Vor­gaben recht­zeitig zu behan­deln.

 


Pro­zesse

Anfor­derungs­analyse

Der Pro­dukt­­verant­wort­liche hat mit dem Bau­stein Service die Mög­lich­keit, alle ein- und ausgehenden Daten und das Verhalten eines Dienstes zu beschrei­ben, die wich­tig für das Ver­ständnis der Fähig­keiten der Soft­ware sind.

Beson­ders bei Diensten, die Schnitt­stellen des IT-Systems zu anderen IT-Systemen reali­sieren, besteht oft die Not­wendig­keit, früh­zeitig Daten­struk­turen, Proto­kolle und nicht funktio­nale Aspekte wie Sicher­heit oder Robust­heit zu fixie­ren. Er macht das in Abstim­mung mit dem Team.

 


Pro­zesse

Pro­dukt­entwick­lung

Der Bau­stein Service ist für Leser (z.B. Ent­wick­ler oder Tester) der zen­trale Ein­stieg, um sich über die Bedeu­tung eines Dienstes zu infor­mieren. Der Über­blick im Bau­stein muss jeden Leser in die Lage ver­setzen, den Dienst fach­lich einzu­ordnen. Über die Ver­knüpfung der ein- und aus­gehenden Daten mit den Bau­steinen Entity oder Event bekommt ein Leser Infor­mationen zu Objekten, die eine wich­tige Rolle in der Daten­ver­arbei­tung und -spei­cherung spielen. In der im Bau­stein ver­öffent­lichten Spezifi­kation finden Leser alle Details zur Imple­mentierung des Dienstes.

Gemäß Prinzip COD gilt der Titel des Bau­steins und die Namen der beschrie­benen Eigen­schaften als Vor­gabe für den Namen der Imple­mentierungs­klasse eines Dienstes. Mit dieser ein­­fach umzu­­setzen­den Regel muss kein Autor mehr eine spezi­elle Doku­­mentation im Wiki schrei­ben, um einen Dienst mit der tech­­nischen Lösung zu ver­­knüpfen. Der Titel des Bau­steins reicht als Ein­­stieg in die Imple­­mentierung.

Seiten­vorlagen für alle Bau­steine und hilf­reiche Makros für die Ver­wendung in Con­fluence.


Quali­tät

Seiten­vor­lage des Bau­steins

Confluence unter­stützt mit Seiten­vor­lagen die Idee der Bau­steine optimal. Das fol­gende Bei­spiel kann direkt als HTML im Editor der Seiten­vor­lagen ein­gefügt werden.

Bitte hier Klicken, um den Quelltext anzuzeigen
<ac:layout>
<ac:layout-section ac:type="single">
    <ac:layout-cell>
    <h1>Steckbrief</h1>
    <ac:structured-macro ac:macro-id="602764ad-f953-4c2a-9ee5-db2568da1960" ac:name="details" ac:schema-version="1">
        <ac:rich-text-body>
        <table class="relative-table wrapped" style="width: 100.0%;">
            <colgroup> <col style="width: 25.0%;"/> <col style="width: 75.0%;"/> </colgroup>
            <tbody>
            <tr>
                <th>Kurzbeschreibung</th>
                <td>
                <div class="content-wrapper">
                    <ac:structured-macro ac:macro-id="5ea10a2b-3496-49c5-85b3-e80e9a47c6d2" ac:name="excerpt" ac:schema-version="1">
                    <ac:parameter ac:name="atlassian-macro-output-type">BLOCK</ac:parameter>
                    <ac:rich-text-body>
                        <p>
                        <ac:placeholder>Kurzbeschreibung der Komponente (management summary).</ac:placeholder>
                        </p>
                    </ac:rich-text-body>
                    </ac:structured-macro>
                </div>
                </td>
            </tr>
            <tr>
                <th colspan="1">Technologie</th>
                <td colspan="1">
                <ac:placeholder>Komma-separierte Liste der verwendeten Module.</ac:placeholder>
                </td>
            </tr>
            </tbody>
        </table>
        </ac:rich-text-body>
    </ac:structured-macro>
    <h1>Beschreibung</h1>
    <h2>Verhalten beim Neustart</h2>
    <p>Keine Angabe. <ac:placeholder>oder das Verhalten beim Neustart ist eine Erkenntnis aus dem Exceptiontest. Was ist zu beachten, wenn die Komponente neu gestartet wird? </ac:placeholder>
    </p>
    <h2>Datenhaltung</h2>
    <p>Keine Angabe. <ac:placeholder>oder einen Überblick über gespeicherte Daten der Komponente geben oder den Leervermerk Keine, wenn die Komponente zustandslos ist. </ac:placeholder>
    </p>
    <h2>Datenverarbeitung</h2>
    <p>Keine Angabe <ac:placeholder>oder einen Überblick über Verarbeitungsregeln, verwendeten Algorithmen und andere Besonderheiten der Komponente geben. </ac:placeholder>
    </p>
    <h2>Eingangsdaten</h2>
    <table class="relative-table wrapped" style="width: 100.0%;">
        <colgroup> <col style="width: 25.0%;"/> <col style="width: 75.0%;"/> </colgroup>
        <tbody>
        <tr>
            <th>Datentyp</th>
            <th>Beschreibung</th>
        </tr>
        <tr>
            <td>
            <ac:placeholder>Bitte hier einen Link zum Nachrichtenmodell oder einer Event-Seite einfügen</ac:placeholder>
            </td>
            <td>
            <ac:placeholder>Bitte hier kurz die Bedeutung des Datentyps und die Herkunft der Daten erklären.</ac:placeholder>
            </td>
        </tr>
        </tbody>
    </table>
    <h2>Ausgangsdaten</h2>
    <table class="relative-table wrapped" style="width: 100.0%;">
        <colgroup> <col style="width: 25.0%;"/> <col style="width: 75.0%;"/> </colgroup>
        <tbody>
        <tr>
            <th>Datentyp</th>
            <th>Beschreibung</th>
        </tr>
        <tr>
            <td>
            <ac:placeholder>Bitte hier einen Link zum Nachrichtenmodell oder einer Event-Seite einfügen</ac:placeholder>
            </td>
            <td>
            <ac:placeholder>Hier bitte die Bedeutung des Datentyps erklären.</ac:placeholder>
            </td>
        </tr>
        </tbody>
    </table>
    </ac:layout-cell>
</ac:layout-section>
<ac:layout-section ac:type="single">
    <ac:layout-cell>
    <p>
        <br/>
    </p>
    </ac:layout-cell>
</ac:layout-section>
<ac:layout-section ac:type="single">
    <ac:layout-cell>
    <h1>Spezifikation</h1>
    <ac:structured-macro ac:macro-id="d5b48f6f-d8c9-4dee-87c6-51b29ee116f9" ac:name="panel" ac:schema-version="1">
        <ac:parameter ac:name="borderWidth">0</ac:parameter>
        <ac:parameter ac:name="borderStyle">none</ac:parameter>
        <ac:rich-text-body>
        <p>
            <ac:placeholder>Bitte hier das Markdown-Dokument aus dem Git-Repository mit dem Markdown-Editor einfügen.</ac:placeholder>
        </p>
        </ac:rich-text-body>
    </ac:structured-macro>
    </ac:layout-cell>
</ac:layout-section>
</ac:layout>

 


Struk­tur

Eigen­schaf­ten des Bau­steins

Der Bau­stein Service repräsen­tiert einen Dienst (engl. service) des IT-Systems. Er hat einen Steck­brief mit einer Kurz­beschrei­bung und einer Liste der einge­setzten Techno­logien. Er beschreibt das Ver­halten des Dienstes. Der Seiten­titel beginnt immer mit Service. Durch die Seiten­vor­lage hat jede Seite das Stich­wort service. Sie kann aber um weitere Schlag­worte ergänzt wer­den. Dadurch wird die Seite leich­ter auf­find­bar.

Der Bau­stein Service hat eine Unter­seite für jede ver­öffent­lichten Spezifi­kation. Erlaubt der Archi­tektur­stil mehr als eine Version des Dienstes, z.B. durch versio­nierte Schnitt­stellen, dann gibt es auch mehr als eine gül­tige Spezifi­kation mit ent­sprechen­der Kenn­zeich­nung.

Der Bau­stein Service bündelt eine mit der Implemen­tierung wachsende Menge von Hand­lungs­anwei­sungen.

Der Bau­stein Service hat einen Zustand. Er ist in Arbeit, wenn keine Spezifi­kation vor­handen ist. Er ist fertig, wenn eine Spezifi­kation vor­handen ist und die Implemen­tierung Teil eines Pro­dukt­inkre­mentes ist.

Der Bau­stein Service hat durch die Spezifi­kation einen Bezug zu einem Pro­dukt­inkre­ment.

Der Bau­stein Service wird in der Sprache der Ent­wick­ler geschrie­ben.