Java-Paketnamen für die Versionierung externer APIs

Question

Gibt es Konventionen für die Benennung von Java-Paketen, die Klassen enthalten, die eine externe, versionierte API verwenden?

Nehmen wir an, wir haben ein semantisches Versionshauptschema einer Dienstleistung und wir müssen einen Verbraucher implementieren, der mit einer bestimmten Version dieser API kompatibel und an diese gebunden ist. Was sind die besten Praktiken, um die Pakete (und Klassen) zu benennen?

Derzeit verwenden wir das Schema: ${service}_${M}_${N} (mit M = Hauptversion, N = Nebenversion). Zum Beispiel: com.example.theService_1_0.. Aber Sonarqube beschwert sich, dass es Konventionen nicht entspricht. Natürlich kann ich diese Regel einfach deaktivieren, aber ich frage mich, ob es Best Practices gibt?

Ich bin auf der Suche nach einem allgemeinen Ansatz, der nicht nur REST-spezifisch ist, weil ich Consumer-Implementierungen für WebService, REST und CORBA getroffen habe. Und ich bin nicht sicher, Artefakt-Versionierung (wie in Maven) funktioniert hier gut, da es sich auf die Version der Implementierung und nicht die API bezieht.

Ich weiß, es gibt Fragen um api versioning, aber das sind über den Hersteller, nicht der Verbraucher.

Answer 1

Ja, Java-Paketnamen haben eine starke und mehrdeutige Konvention für die Angabe von Abhängigkeiten Versionen: nicht.

Wenn Sie Ihre Anwendung ändern, um eine neue Version einer externen API zu verwenden, erstellen Sie eine neue Version Ihrer Anwendung. Die Versionsnummer, nach der Sie suchen, ist die Versionsnummer Ihrer Anwendung. Bei vielen Java-Projekten werden die Versionen der Abhängigkeiten von einer Maven-Konfigurationsdatei verwaltet.

In jedem Fall, wenn Klassen eine bestimmte API-Version verwenden, haben die Klassen- und Paketnamen keinen Einfluss auf diese Informationen, was die Kapselung verletzen würde, abgesehen von allem anderen. Diese Namen haben einen anderen Zweck.

Beachten Sie, dass dies bei der Verwendung von HTTP/REST-APIs oder Java-APIs nicht anders ist. Schließlich glaube ich nicht, dass Sie Ihre Klasse TheServiceWithLog4J_12_1_5 nennen würden. Ich hoffe zumindest nicht.

Sie haben nicht erwähnt, ob Sie mehrere Versionen dieser externen API gleichzeitig unterstützen müssen. Selbst wenn Sie dies tun würden, würde ich dennoch nicht empfehlen, die API-Versionsnummer im Paketnamen anzugeben. Verwenden Sie stattdessen den Paketnamen, um anzugeben, warum Sie haben zwei Versionen und der wichtige Unterschied.