Praktisches API-Design

Transkript

1 Praktisches API-Design Kai Spichale adesso AG

2 Eine API ist wie die Spitze eines Eisbergs.. 2

3 Klassische Funktionen einer API Entkopplung von Implementierung Client API Implementation Definiert Komponente durch ihre Operationen mit Ein- und Ausgabewerten Softwarewiederverwendung und Integration 3

4 Kommunikationsproblem bei Softwarewiederverwendung? Lösung: Kommunikation durch API > APIs werden für Menschen geschrieben > Perspektive ist beim API-Design entscheidend 4

5 Für wen ist API-Design relevant? 5

6 Entwurf 6

7 Empfohlene Vorgehensweise Anwendungsfälle Klein mit den wichtigsten Anforderungen beginnen API häufig schreiben Regelmäßiges Feedback Feedback API schreiben 7

8 Qualitätsmerkmale 8

9 Qualitätsmerkmale Konsistent Intuitiv verständlich Dokumentiert Einprägsam und leicht zu lernen Führt zu lesbarem Code Minimal Stabil Einfach erweiterbar Grundvoraussetzung: Nützlich und korrekt :-) 9

10 Konsistent str_repeat str_split str_word_count strcmp strlen strrev Konzeptionelle Integrität = kohärentes Design mit der Handschrift eines Architekten 10

11 Intuitiv verständlich Idealerweise ist Client-Code ohne Dokumentation verständlich Vorwissen ausnutzen und bekannte Konzepte wiederverwenden Starke Begriffe etablieren und diese konsequent wiederverwenden 11

12 Java Collection API java.util.list java.uilt.set java.util.map add add put addall addall putall contains contains containskey, containsvalue containsall containsall - remove remove remove removeall removeall - 12

13 Dokumentiert Gute Dokumentation ist unverzichtbar 13

14 Einprägsam und leicht zu lernen Einflussfaktoren > Konsistenz, Verständlichkeit und Dokumentation > Größe (Anzahl der Konzepte) > Vorwissen der Benutzer > Time to First Hello World 14

15 Führt zu lesbaren Code EntityManager em =...; CriteriaBuilder builder = em.getcriteriabuilder(); CriteriaQuery<Order> cq = builder.createquery(order.class); Root<Order> order = cq.from(order.class); order.join(order_.positions); cq.groupby(order.get(order_.id)).having( builder.gt(builder.count(order), 1)); TypedQuery<Order> query = em.createquery(cq); List<Order> result = query.getresultlist(); 15

16 Führt zu lesbaren Code EntityManager em =...; QOrder order = QOrder.order; JPQLQuery query = new JPAQuery(em); List<Order> list = query.from(order).where(order.positions.size().gt(1)).list(order).getresults(); 16

17 Schwer falsch zu benutzen new java.util.date(1983, 20, 1); int year = ; int month = 1-1; new java.util.date(year, month, 1); 17

18 Minimal Hinzugefügte Elemente können nachträglich nur schwer entfernt werden Im Zweifel Elemente weglassen Trade-off: Minimalität vs. Komfort > Gut: java.util.list.removeall() > Schlecht: java.util.list.removealleven() 18

19 Minimal Auslagerung in Hilfsklassen > z.b.: java.util.arrays, java.util.collections > Alle notwendige Methoden müssen public sein > Utility-Klassen können leicht um neue Hilfsmethoden erweitert werden > Collection-Interfaces bleiben klein Performance und Nebenläufigkeit > putifabsent() wäre in separater Hilfsklasse nicht threadsicher Optionale Methoden und Konstruktoren kennzeichnen > z:b.: java.io.printwriter enthält convenience Text 19

20 Stabil API-Änderungen sollten nur mit Sorgfalt durchgeführt werden Client Client Client Vertrag API v1 20

21 Einfach erweiterbar Welche Änderungen wird es in Zukunft geben? Erweiterung idealerweise abwärtskompatibel, sonst neue API-Version notwendig Anpassungsaufwand für Clients minimieren 21

22 Abwärtskompatibilität 22

23 Kompatibilität Trade-off: Abwärtskompatibilität vs. Flexibilität Code-Kompatibilität > Einfachste Form der Kompatibilität public class MyOwnClass extends OtherBaseClass { public List<ResultItem> getresults() { return } } Potentielle Konflikte durch Vererbung 23

24 Kompatibilität Binär-kompatibel: Programm kann neue Version ohne erneute Kompilierung verwenden Beispiel: > Kompilieren mit log4j > Linken gegen log4j Grundvoraussetzung: Dynamisches Linken > Einsprungadresse von virtuellen Methoden wird zur Laufzeit bestimmt 24

25 Funktionale Kompatibilität Verschiedene Bausteine können gelinkt werden und erfüllen ihre erwartete Funktion Erwartetes Verhalten Tatsächliches Verhalten Tatsächliches Verhalten der neuen Version 25 Bekannt als Amöben-Effekt (Jaroslav Tulach)

26 Design-Repertoire 26

27 Erzeugsmuster Verwendung von Konstruktoren mit Factories und Builder minimieren Vorteil Verwendung unterschiedlicher Subtypen Erzeugung komplexer Objekte vereinfachen Keine Konstruktoren mit vielen Parametern 27

28 Fluent API Führt zu leicht lesbaren Client-Code Realisierung einer internen DSL API-Benutzung wird in Kombination mit Autovervollständigung in IDE vereinfacht 28

29 Vererbung Kontroverse Ansätze: > Open Inheritance > Designed Inheritance Standardmäßig alle konkreten Klassen final machen > Vererbung verletzt Datenkapselung > Klassen müssen speziell für Vererbung entworfen werden > Für Wiederverwendung Kompositionen nutzen Beispiele: > Richtig: Set extends Collection > Falsch: OrderPositionSet extends Set<OrderPosition> 29

30 Template-Methode abstract class OrderSorter { public void sort(list<order> orders) { if(compare(o1, o2)) { } abstract compare(order o1, Order o2); } 30

31 API versus SPI Application Programming Interface Wird von Benutzern aufgerufen z.b.: FileSystem API, FileObject Methoden können i.d.r. hinzugefügt werden Service Provider Interface Wird durch Client-Code implementiert (Callback durch Framework) z.b.: LocalFileSystem, JarFileSystem werden implementiert Neue Methoden brechen Client-Code 31

32 Template-Methode public class OrderSorter { private final Comparator<? super Order> comp; public OrderSorter(Comparator<? super Order> comp) { } this.comp = comp; public void sort(list<order> orders) { } Collections.sort(orders, comp); } 32

33 Kontextobjekt als Parameter für SPI Schlechter Stil: public interface MyServiceProviderInterface { void callbackmethod(string param); } Besser: public interface ServiceProviderInterface { void callbackmethod(context param); } interface Context { String message(); Integer id(); } 33

34 Methoden mit Destruktorsemantik JDBC: Belegen und Freigeben von Ressourcen Reihenfolge beachten! Evtl. Ressourcen in umgekehrter Reihenfolge freigeben 34

35 Interface-Evolution Hinzufügen einer neuen abstrakten Methode war vor Java 8 eine inkompatible Änderung > Alte Lösung: Neues Interface erweitert altes Ab Java 8 Default-Methoden Bevorzuge Klassen vor Interfaces 35

36 Invarianten und Bedingungen Klassen sind selbst für die Einhaltung ihrer Invarianten verantwortlich (nicht Client) Klassen sollten ihrer Vorbedingungen möglichst gut überprüfen Nachbedingungen werden mit Tests überprüft 36

37 Fehlermeldungen Hilfreiche Fehlermeldungen erleichtern Benutzung Vermeidung von Checked Exceptions Exceptions auf einheitlichen Abstraktionsniveau Fail Fast: Melde Fehler so früh wie möglich > Kompilierzeitpunkt: statische Typisierung > Laufzeit: Methoden sollte falsche Parameter / Zustand sofort überprüfen 37

38 Immutability / Minimale Änderbarkeit Alle public und konkreten Klassen final und immutable machen Vorteile: > Thread-safe > Wiederverwendbar > Einfach Nachteile: > Separates Objekt für jeden Wert Falls mutable, dann sollte Zustandraum klein sein 38

39 Sinnvolle Defaults Vermeidung von Boilerplate-Code Geringe Einstiegshürden und Unterstützung für Neueinsteiger Boolean sind standardmäßig false (entsprechende Namen wählen) Defaults müssen dokumentiert sein 39

40 Globaler Zustand / Konfiguration Globaler Zustand ist problematisch weil: > Schwer testbar, nicht flexibel > Fehleranfällig, schwer verständlich Empfehlung: > Sei funktional, vermeide Zustand > Einbindung einer Bibliothek sollte keine Änderungen des globalen Zustand notwendig machen > Falls doch, dann ist es eine Applikation und keine Bibliothek Beispiel: > Log4j wird beim Laden automatisch konfiguriert > Unterschiedliche Konfigurationen für Log4j in einem Prozess nicht möglich 40

41 Dokumentation 41

42 Inhalt einer API-Dokumentation Allgemeine Übersicht: > Beschreibt Anwendungsgebiet und Funktion > Evtl. mit Architekturübersicht Entwicklerhandbuch: > Beschreibt wiederkehrende Aufgaben i.d.r. mit Beispielen Referenz 42

43 Dokumentation mit Beispielen Snippet: > Quellcode-Auszug mit Beschreibung Test: > Demonstrieren Funktionsumfang und Benutzung Tutorial: > Schritt-für-Schritt-Anleitung > Kochbuch Beispielapplikation: > Quellcode für komplette Applikation zeigt Benutzung der API 43

44 Empfehlung: Vorträge von Joshua Bloch 44

45 Kai