Enums mit unbekannten Werten behandeln

[larsp79]

Strings mit eingeschränktem Wertebereich (Enums) müssen mit neuen, unbekannten Werten umgehen können

Warum wird die API nicht gleich ohne Einschränkung von Wertebereichen definiert und statt ´enum´ einach nur String verwendet? Dies ist auf Konsumentenseite wesentlich einfacher zu handhaben, da man nicht darauf angewiesen ist, dass ein verwendete Object Mapper unbekannte Enums sauber ignorieren kann.

[dos-meta]

Was muss der Konsument aktuell tun, um mit unbekannten Werten klar zu kommen? Eigentlich nur READ_UNKNOWN_ENUM_VALUES_AS_NULL im ObjectMapper setzen, korrekt? Wenn wir String verwenden würden, verlieren wir an der Stelle die Dokumentation der gültigen Ausprägungen. Alternativ würden wir wohl die description erweitern oder examples verwenden.
Ich bin da offen für, glaube aber wir ändern unsere Enums selten bis gar nicht. :)

[larsp79]

Eigentlich nur READ_UNKNOWN_ENUM_VALUES_AS_NULL im ObjectMapper setzen, korrekt?

Wenn unsere Partner alle Java und Jackson verwenden, dann ja. Andere Sprachen und ObjectMapper sollten jedoch auch berücksichtigt werden. Wir können keine Annahme darüber treffen mit welcher Technologie unsere Partner diese Schnittstelle anbinden.

Wenn wir String verwenden würden, verlieren wir an der Stelle die Dokumentation der gültigen Ausprägungen.

Die Enum könnte als eigener Typ definiert werden und bei der Beschreibung des Properties darauf verwiesen werden. Falls unsere Partner aus der Swagger Beschreibung den Code generieren, haben sie sofort die bekannten Enum Werte und müssen diese nicht aus der Doku abtippen.

Ich bin da offen für, glaube aber wir ändern unsere Enums selten bis gar nicht.

Wenn die sich so selten ändern, ist doch auch ein Breaking Change der API ok. Sollte dann nur alle paar Jahre mal auftreten und wir müssten eine Zeit lang 2 verschiedene API Versionen unterstützen.

[gomil]

ich bin zwispältig

zum Einen finde ich enums gut, da dann automatisch der Wertebereich klar ist und man als Client/Reader durch entsprechende Code-Generierung unterstützt wird.

zum Anderen beschränken wir uns bei der Weiterentwicklung der API - falls wir neue ENUM-Ausprägungen hinzufügen wollen, dann wäre das ein Breaking-Change und den würden wir verrmutlich vermeiden wollen, da es soviel Aufwand macht (alle Clients müssen umgestellt sein, bevor wir das neue ENUM wirklich mitsenden dürfen)

Einen Lösungsansatz liefert Martin Fowler mit dem TolerantReader-Pattern
https://www.martinfowler.com/bliki/TolerantReader.html
tldr: Reader soll möglichst wenig Annahmen treffen => da spielt READ_UNKNOWN_ENUM_VALUES_AS_NULL genau rein
Susanne propagiert dieses Pattern auch in unseren GrapgQL-SST

[larsp79]

alle Clients müssen umgestellt sein, bevor wir das neue ENUM wirklich mitsenden dürfen

ist das nicht häufig der Fall?

Wenn ich mir z.B. Anrede anschaue und mir als implentierender Entwickler die Readme durchgelesen habe muss ich entscheiden, wie ich unbkeannte Werte behandle. Mit READ_UNKNOWN_ENUM_VALUES_AS_NULL z.B. fehlt der Wert dann. Dh. in KS wurde eine neue unbekannte Anrede ausgewählt und die aufgerufene Implementierung sieht nur null und generiert dann eine Vollständigkeitsmeldung, dass diese Angabe jedoch erforderlich ist.

[larsp79]

Meine Gedanken, wenn ich diese Schnittstelle bereitstellen soll um bei Europace eingebunden zu werden:

• super, eine Swagger Definition, damit kann ich mir den API Code generieren lassen und muss die API nicht von Hand abtippen 😄
• Oh, es können auch unbekannte Enum Werte geliefert werden 🤔
  • ich kann den Service tolerant machen und nur Map verwenden. Für meine zu implementierende Angebotslogik möchte ich jedoch auf eine typisierte Api setzen. Das bedeutet ich müsste die Map von Hand in die API Objekte transformieren, was viel Arbeit ist 👎
  • Ich passe die Swagger Codegen an, um Enums als Strings zu generieren. Dann muss ich die angepasste Swagger Codegen aber auch noch mit pflegen 😒
  • Ich passe den Object Mapper an um unbekannte Enums als null zu liefern. Das bedeutet aber auch, dass unbekannte Enum Werte wie fehlende Angaben behandelt werden, was nicht bei jedem Enum Wert passt. 👎
  • ich passe die gelieferte Swagger Definition händisch an, um Strings statt Enums zu erhalten und kann dann auch mit unbekannte Enum Werte in meiner Logik arbeiten und diese z.B. zu loggen oder auch Meldungen zu generieren, dass dieser Wert nicht akzeptiert wird. Da sich die API nicht so häufig ändern sollte, muss ich das halt bei der nächsten API Änderung wieder machen. Nicht schön, aber einfacher als die Alternativen.