API-Design. Kai Spichale

Чтение книги онлайн.

СКАЧАТЬ Kommunikation zwischen Client und API beschreiben

      Die Kommunikation zwischen Client und API kann zu Beginn mit Interaktionsbeispielen beschrieben werden. Man sollte Notationen verwenden, mit denen man gut arbeiten kann. Es müssen keine formal korrekten UML-Sequenzdiagramme sein. Auch einfache Skizzen auf einem Whiteboard eignen sich gut für diese Aufgabe. Die Entwürfe können dann mit Kollegen oder Teammitgliedern diskutiert und gemeinsam verbessert werden. Wenn Sie die API einer Bibliothek entwerfen, können Sie diesen Schritt auch überspringen.

       Szenarien mit Code aufschreiben

      Im zweiten Schritt folgen bereits Codebeispiele für die Benutzung der API entsprechend den Anwendungsszenarien. Viele objektorientierte Ansätze beginnen mit dem Entwurf des Objektmodells und schreiben die Beispiele für die resultierende API danach. Eine API, die mit einem derartigen Bottom-up-Ansatz entsteht, spiegelt häufig die Struktur der internen Implementierung wider und ist schwerer zu benutzen. Beginnen Sie stattdessen den Entwurf der API mit einem Top-down-Ansatz aus der Perspektive der späteren API-Benutzer. Die API wird nur dann gut, wenn sie für die wichtigen Benutzungsszenarien optimiert wird.

      Schreiben Sie die Codebeispiele entsprechend der Priorität der Szenarien, sodass die wichtigsten Szenarien am elegantesten mit der API zu lösen sind. Nutzen Sie die Programmiersprachen und Technologien der späteren API-Benutzer.

      Es ist wichtig, eine API früh und häufig mit Beispielen auszuprobieren.

      Angenommen Sie wollen die API eines Audit-Logs entwerfen, das Benutzerinteraktionen speichert, um eventuellen Missbrauch einer Anwendung feststellen zu können. Die Codebeispiele für die Szenarien des Audit-Logs könnten folgendermaßen lauten:

      // Szenario 1: Erfolgreiche Benutzeranmeldung loggen

      AuditLogger logger = new AuditLogger();

      AuditEvent event = logger.event()

      .name("user login")

      .status(SUCCESS)

      .user("user1")

      .date(new Date())

      .build();

      logger.log(event);

      // Szenario 2: Fehlgeschlagene Benutzeranmeldung loggen

      AuditLogger logger = new AuditLogger();

      AuditEvent event = logger.event()

      .name("user login")

      .status(FAILURE)

      .user("user1")

      .date(new Date())

      .detail("failure explanation", "wrong password")

      .detail("user locked", "true")

      .build();

      logger.log(event);

      Zur Erzeugung der AuditEvent-Instanzen könnten Sie beispielsweise mit verschiedenen Erzeugungsmustern experimentieren und deren Vor- und Nachteile abwägen. Die Beispiele helfen Ihnen außerdem, eventuelle Entwurfsfehler frühzeitig zu erkennen. Erst wenn Sie eine API mehrfach auf diese Weise geschrieben haben, sollten Sie weitere Details spezifizieren oder mit der Implementierung beginnen. Aus den Codebeispielen ergibt sich folgendes API-Design für das AuditLog:

      public class AuditLogger {

      public AuditLogger() { }

      public AuditEventBuilder event() { }

      public void log(AuditEvent event) { }

      }

      public class AuditEventBuilder {

      public AuditEventBuilder name(String name) { }

      public AuditEventBuilder status(String success) { }

      public AuditEventBuilder user(String user) { }

      public AuditEventBuilder date(Date date) { }

      public AuditEventBuilder detail(String key, String value) {

      }

      public AuditEvent build() { }

      }

      public class AuditEvent {

      // Getter-Methoden

      }

      Die Codebeispiele sind die Grundlage für eine szenariobasierte API-Spezifikation. Diese kann Teil einer größeren Spezifikation sein oder in einem separaten Dokument abgelegt werden. Die geschriebenen Beispiele können als Teil der Spezifikation, als ausführbare Dokumentation und für Testzwecke verwendet werden.

       3.6Spezifikation erstellen

      Nachdem die Klassen und Interfaces der zu entwerfenden API mithilfe der Codebeispiele identifiziert worden sind, könnte eine formale Spezifikation erstellt werden. API-Spezifikationen dieser Art werden beispielsweise im Rahmen des Java Community Process (JCP) erarbeitet, um neue Sprachelemente aufzunehmen, aber auch APIs zu erweitern oder zu verändern. Die Spezifikationen definieren die Konzepte der API und die Anforderungen an Implementierungen. Eine textuelle Spezifikation kann durch ein detailliertes JavaDoc vervollständigt werden. Darin werden konkrete Packages, Interfaces, Klassen etc. genannt und beschrieben. Weitere Details zu JavaDoc finden Sie in Kapitel 12.

      Prinzipiell können Sie eine API-Spezifikation in folgende Abschnitte gliedern:

       Allgemeine Spezifikation

       Auf dieser Ebene können Eigenschaften spezifiziert werden, die für die gesamte API gültig sind. Beispielsweise kann festlegt werden, dass alle Objekte Thread-sicher sind. Abweichungen werden explizit angegeben. Ein anderes Beispiel ist der Umgang mit Unchecked Exceptions.

       Package-Spezifikation

       Diese Angaben sind gültig für alle Elemente innerhalb eines Packages. Der Zweck des Packages sollte kurz und präzise beschrieben sein. Verweise auf andere Dokumente können hier ebenfalls eingefügt werden.

       Klassen- und Interface-Spezifikation

       Dieser Abschnitt beginnt stets mit einer kurzen und präzisen Beschreibung des Objektes. Es folgen Angaben zu Thread-Sicherheit, Zustand (Immutability), Serialisierung, erlaubte Implementierungsvarianten, eventuelle Hardwareabhängigkeiten, Sicherheitseinschränkungen und Verweise auf andere Dokumente.

       Feldspezifikation

       Zur Spezifikation eines Feldes gehört dessen Bedeutung, Wertebereich und eine Aussage, СКАЧАТЬ