Versionierung von WebService-Schnittstellen

DOAG Konferenz 16. – 18.11.2010, Nürnberg Christian Wiesing [email protected] www.ordix.de

Agenda

„ Einleitung „ Code First vs. Contract First „ Zulässige und unzulässige Änderungen eines Web-Service „ Konvertierung von Web-Service-Objekten „ Arten der Versionierung „ Naming-Strategien „ Isolierung von Web-Services „ Releasemanagement „ Fazit Versionierung von Web-Service-Schnittstellen

2 / 49

Einleitung

„ Web-Services sind mittlerweile eine der meist genutzten Mechanismen für den systemweiten Datenaustausch „ Ein Web-Service ist mit aktuellen Frameworks schnell implementiert „ Die Einbindung in eine bestehende Struktur ist meist relativ problemlos „ Es reichen meistens schon einfache Annotationen, um Web-Services innerhalb eines WS-Containers bereitzustellen: @WebService public class WebServiceImpl { public String sayHello(String name) { return "Hello, " + name + "!"; } } Versionierung von Web-Service-Schnittstellen

3 / 49

Einleitung

Web-Service

Präsentationsschicht

Business-Schicht

Persistenzschicht

Versionierung von Web-Service-Schnittstellen

4 / 49

Einleitung

„ Es muss bedacht werden, welche Rolle der Web-Service in einer bestehenden SOA-Architektur spielt „ Anforderungen an diese Architektur müssen zuvor definiert werden „ Grundsatz: Eine Web-Service-Schnittstelle, welche einmal produktiv genommen wurde, darf nicht mehr ohne weiteres geändert oder entfernt werden. „ Auch über eine Versionierung und ein ordentliches Releasemanagement der Schnittstellen sollte sich jedes Projekt Gedanken machen

Versionierung von Web-Service-Schnittstellen

5 / 49

Einleitung

Unter Web-Service-Versionierung versteht man das gleichzeitige Bereitstellen des selben Web-Services unter verschiedenen Versionen.

Web-Service Version 1

Web-Service Version 2

Web-Service Version 3

Präsentationsschicht

Business-Schicht

Persistenzschicht

Versionierung von Web-Service-Schnittstellen

6 / 49

Frage

Welches Entwicklungsverfahren (Code First oder Contract First) eignet sich besser für die Web-Service-Versionierung?

Versionierung von Web-Service-Schnittstellen

7 / 49

Code First vs. Contract First

„ Vor dem Bereitstellen eines Web-Services stellt sich immer die Frage, nach welchem Verfahren dieser entwickelt werden soll „ Hierbei wird zwischen zwei Verfahren unterschieden: ƒ Code First ƒ Contract First „ Beide Verfahren eignen sich prinzipiell für die Versionierung von Web-ServiceSchnittstellen

Versionierung von Web-Service-Schnittstellen

8 / 49

Code First

„ Es werden verschiedene Web-Service-Objekte und Klassen mit Methoden implementiert „ Auf Basis dieser Klassen wird anschließend die WSDL generiert „ Beim Code First-Ansatz besteht immer die Gefahr, dass während des Entwicklungsprozesses eine Web-Service-Klasse geändert wird „ Auf Basis dieser Änderungen wird eine neue WSDL generiert, was zu Instabilitäten bei der Web-Service-Schnittstelle führen kann

Versionierung von Web-Service-Schnittstellen

9 / 49

Contract First

„ Zunächst wird die WSDL (Contract) und die zugehörigen XSD-Dateien definiert und erstellt „ Anschießend werden auf Basis der WSDL die zugehörigen Klassen generiert „ Die Implementierung einer WSDL kann bei großen Web-Services schnell kompliziert und unübersichtlich werden „ Die WSDL wird in der Regel nicht so schnell (unbeabsichtigt) angepasst wie normaler Java-Code „ Da sie sowohl die Grundlage für den Web-Service-Client als auch für den Server ist, sollte diese stabil gehalten werden „ Daher eignet sich Contract First tendenziell besser für die Versionierung Versionierung von Web-Service-Schnittstellen

10 / 49

Situation

Eine bestehende Web-Service-Schnittstelle soll angepasst werden! Frage Welche Änderungen können vorgenommen werden, ohne bestehende Systeme zu beeinflussen?

Versionierung von Web-Service-Schnittstellen

11 / 49

Änderung des bestehenden Web-Service

„ Welche Änderungen können überhaupt vorgenommen werden, ohne andere Systeme zu beeinflussen? „ Zulässige Änderungen: ƒ Hinzufügen einer neuen WSDL und somit Web-Service ƒ Neue Web-Service-Methode hinzufügen ƒ Neue XML-Schema-Typen definieren rückwärts kompatibel!

Versionierung von Web-Service-Schnittstellen

12 / 49

Änderung des bestehenden Web-Service

„ Unzulässige Änderungen: ƒ Änderungen an der Signatur von Methoden (Parameter, Name, Rückgabewert) ƒ Änderung bestehender XML-Schema-Typen ƒ Entfernen von Methoden und Typen nicht rückwärts kompatibel!

Versionierung von Web-Service-Schnittstellen

13 / 49

Änderung des bestehenden Web-Service

„ Für alle nicht rückwärts kompatiblen Änderungen an einer Web-ServiceSchnittstelle muss eine neue WSDL erstellt werden „ Alle angebundenen Systeme müssen die Änderungen zeitgleich (bis zum Zeitpunkt der Produktivsetzung) nachziehen „ Nur rückwärts kompatible Änderungen können auch in einem bestehenden Web-Service durchgeführt werden, ohne die zugehörigen Clients zu beeinflussen „ Änderungen sollten aber generell mit Bedacht vorgenommen werden, da man i. d. R. keine Information über die jeweilige Implementierung der Clients besitzt

Versionierung von Web-Service-Schnittstellen

14 / 49

Situation

Innerhalb der Business-Logik steht ein größeres Refactoring an und eine Vielzahl von Anforderungen wurden realisiert. Frage Wie schaffe ich es dennoch meine Schnittstelle stabil zu halten?

Versionierung von Web-Service-Schnittstellen

15 / 49

Konvertierung

„ Ein Web-Service sollte niemals Business-Objekte über eine Web-ServiceSchnittstelle versenden! „ Business-Objekte unterliegen häufig vielen Änderungen und eignen sich dadurch nicht für eine stabile Schnittstelle „ Auf dieses Problem sollte vor allem beim Code First-Ansatz geachtet werden „ Durch den Konverter werden spezielle Web-Service-Objekte erzeugt „ Der Konverter ist die spätere Schnittstelle zwischen den einzelnen WebService-Versionen und der Business-Logik Entkopplung zur bisherigen Anwendungslogik

Versionierung von Web-Service-Schnittstellen

16 / 49

Konvertierung Web-Service (Version 3)

Präsentationsschicht

Web-Service (Version 2) Web-Service (Version 1) Konverter WS-Objekte

Konverter

Konverter BusinessObjekte

Business-Schicht

Persistenzschicht Versionierung von Web-Service-Schnittstellen

17 / 49

Konvertierung

„ Die Web-Service-Objekte dürfen nur die Informationen enthalten, die für andere Systeme auch von Relevanz sind unnötige Informationen vermeiden „ Dadurch können sie relativ „schlank“ gehalten werden und erzeugen somit keinen überflüssigen Datentransfer „ Nur in dem Konverter werden bei produktiven Web-Service-Schnittstellen noch Änderungen vorgenommen, dabei bleiben die Web-Service-Objekte aber unverändert „ Dieses Vorgehen ermöglicht, dass auch komplexe Änderungen innerhalb der Business-Logik in die „alte“ Form des jeweiligen Web-Service konvertiert werden können

Versionierung von Web-Service-Schnittstellen

18 / 49

Konvertierung Server class Mitarbeiter { Abteilung abteilung; Adresse adresse; String name; String vorname; Integer alter; ... }

Versionierung von Web-Service-Schnittstellen

Web-Service

Konverter

Client class MitarbeiterWS{ Long abteilungsId; Long adressId; String name; String vorname; Integer alter; ... }

19 / 49

Situation

Die Web-Service-Schnittstelle soll neue Funktionalitäten erhalten und einige Methoden entsprechend angepasst werden. Frage Wie können die Anforderungen umgesetzt werden ohne andere Systeme direkt zu beeinflussen?

Versionierung von Web-Service-Schnittstellen

20 / 49

Situation

Client

Client

WSDL

Server

Client

Versionierung von Web-Service-Schnittstellen

21 / 49

Arten der Versionierung

„ Grundsätzlich unterscheidet sich die Versionierung in zwei Arten: ƒ Package-Versionierung ƒ Endpoint-Versionierung

Versionierung von Web-Service-Schnittstellen

22 / 49

Package-Versionierung

„ Die Package-Versionierung bezeichnet die „einfache“ Duplizierung des Quellcodes innerhalb des Verzeichnisbaumes eines Projektes „ Hierbei existieren die identischen Klassen, mit unterschiedlichen Implementierungen, innerhalb der Package-Struktur: de.ordix.webservice.version1 - ServiceKlasse1.java - ServiceKlasse2.java - WebService.wsdl de.ordix.webservice.version2 - ServiceKlasse1.java - ServiceKlasse2.java - WebService.wsdl Versionierung von Web-Service-Schnittstellen

23 / 49

Package-Versionierung

„ Innerhalb des neu erzeugten Package wird zusätzlich die Zugriffsinformation des jeweiligen Web-Services angepasst „ Dieses Prinzip macht aber die Abgrenzung der Schnittstellen voneinander schwierig und den Quellcode über lange Sicht unübersichtlich „ Vor allem birgt es das Risiko unbeabsichtigt eine bestehende Schnittstelle zu ändern „ Darüber hinaus besteht das Risiko zwischen den Web-Services Abhängigkeiten zu erzeugen

Versionierung von Web-Service-Schnittstellen

24 / 49

Endpoint-Versionierung

„ Endpoint-Versionierung bezeichnet das Auslagern der Web-ServiceSchnittstelle (inklusive des Konverters) in ein eigenes Projekt „ Hierbei wird das Anlegen einer neuen Version der Schnittstelle durch ein Versions-Verwaltungssystem (wie z. B. CVS oder SubVersion) realisiert „ Bei jeder neuen Web-Service-Version wird somit das gesamte Web-ServiceProjekt dupliziert „ Kein Risiko von Abhängigkeiten zu anderen Web-Service-Versionen

Versionierung von Web-Service-Schnittstellen

25 / 49

Endpoint-Versionierung

Web-Service-Projekt

Head / Truck – Version 3

Versionierung von Web-Service-Schnittstellen

in Entwicklung

Branch 2 – Version 2

poduktiv

Branch 1 – Version 1

poduktiv

26 / 49

Endpoint-Versionierung

„ Der Hauptzweig bleibt die aktuelle Entwicklungsversion, welche solange geändert werden kann bis diese produktiv gesetzt wird „ Anschließend wird auch auf Basis dieser Version ein Branch erstellt, um sie von der aktuellen Weiterentwicklung abzukapseln „ Dadurch ist eine genaue Abgrenzung gewährleistet und ein Quellcode muss nicht unnötig im eigentlichen Hauptprojekt dupliziert werden

Versionierung von Web-Service-Schnittstellen

27 / 49

Endpoint-Versionierung

„ Auf Basis dieses Web-Service-Projektes wird ein einzelnes EAR bzw. WARArchiv zu erzeugt „ Dieses kann unabhängig von dem bestehenden Projekt auf dem Applikationsserver deployed werden „ Der Aufwand bei dieser Vorgehensweise ist initial relativ hoch, da der WebService aus dem bestehenden Projekt herausgelöst werden muss „ Im späteren Entwicklungsverlauf reduziert sich hingegen der Aufwand für die weitere Pflege und Wartung der Schnittstellen

Versionierung von Web-Service-Schnittstellen

28 / 49

Vergleich der Versionierungsarten

„ Package-Versionierung ist zunächst am schnellsten und einfachsten zu realisieren „ Für Endpoint-Versionierung müssen die Web-Services in ein eigens Unterprojekt/Modul ausgelagert werden „ Dadurch wird eine übersichtliche Abgrenzung voneinander gewährleistet und es existieren keine Doubletten mehr im Klassenbaum „ Die Endpoint-Version bietet auf längere Sicht die bessere Wartbarkeit und ist generell für eine stabile Versionierung geeignet

Versionierung von Web-Service-Schnittstellen

29 / 49

Frage

Wie erstelle ich bei der Endpoint-Versionierung eine neue Web-Service-Version?

Versionierung von Web-Service-Schnittstellen

30 / 49

Endpoint-Versionierung

„ Falls noch nicht geschehen muss zunächst der Web-Service in ein eigenes Projekte oder Modul ausgegliedert werden „ Das aktuelle Projekt repräsentiert immer die aktuelle (höchste) Version der Schnittstelle „ Auf Basis dieses Projektes wird anschließend ein Branch erstellt, wodurch die Version „fixiert“ wird „ Die Version des Hauptprojektes (Head/Trunk) wird um eins erhöht und der zugehörige Namespace entsprechend angepasst „ Es existieren demnach immer genauso viele Branches, wie aktuell produktive Web-Service-Versionen Versionierung von Web-Service-Schnittstellen

31 / 49

Endpoint-Versionierung

„ Mit Hilfe von Ant-Contrib können mehrere Branches innerhalb eines BuildProzesses gebaut werden: ${checkoutTagWS} wird gebaut

„ Das Element @{checkoutWSTag} beinhaltet eine Komma separierte Liste mit allen zu bauenden WS-Branches Versionierung von Web-Service-Schnittstellen

32 / 49

Frage

Wie sollte sich der Namensraum bzw. die URL der jeweiligen Versionen unterscheiden?

Versionierung von Web-Service-Schnittstellen

33 / 49

Naming-Strategien

„ Für die Vergabe des Web-Service-Namen kann z. B. folgende Konvention verwendet werden: ./SERVICE_NAME „ Major bezeichnet die Hauptversion des Service „ Minor ist die fortlaufende Sub-Version der Hauptversion „ Ein neues Major Release enthält Änderungen, die den Client zwingen eine neue Version auf Basis der aktuellen WSDL zu erzeugen „ Während bei einem Minor-Release die Abwärtskompatibilität mit dem „Verbraucher“ aufrecht erhalten würde „ Kleinere Versionsänderungen beinhalten in der Regel nur interne Korrekturen Versionierung von Web-Service-Schnittstellen

34 / 49

Naming-Strategien

„ Bei der Standard Namensgebung wird der jeweilige Versionsstempel nach dem eigentlichen Web-Service geführt. Der verwendete Namespace könnte demnach wie folgt aussehen: