API-Design. Kai SpichaleЧитать онлайн книгу.

       3.5Entwurf mit Szenarien und Codebeispielen

      Hilfreich zum Entwurf einer API sind Beispiele, die die Verwendung der API aus Clientperspektive zeigen. Als Grundlage für diese Beispiele sind repräsentative Anwendungsszenarien geeignet.

       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.