API auf Huma v2 migriert, 100 % Übereinstimmung
Die HTTP‑API von Fiber auf Huma v2 migriert — 649 Pfade und 760
Operationen — und eine vollständige Übereinstimmung (100 %) zwischen
den registrierten Serverrouten und der veröffentlichten
OpenAPI‑Beschreibung erreicht und beibehalten.
2025

Situation. Die API begann auf Fiber, mit von Hand geschriebener
Anfragevalidierung für jeden Endpunkt. Für wenige Endpunkte ist das
vertretbar, mit wachsender API jedoch nicht mehr. Individuelle
Prüfungen erzeugen Wartungsaufwand und kleine Inkonsistenzen, weil
jeder Endpunkt seine eigenen Sonderregeln hat. Eine gemeinsame
Beschreibung der API‑Struktur fehlte außerdem.

Aufgabe. Die Validierung sollte aus Typen statt aus
handgeschriebenen Prüfungen entstehen. Ein tatsächlicher API‑Vertrag
sollte die Schnittstelle beschreiben, ohne eine große vollständige
Neuentwicklung zu verlangen.

Massnahmen. Die HTTP‑Schicht wechselte auf Huma v2 über Fiber; die
vorhandene Laufzeit blieb damit bestehen. Jeder Endpunkt erhält
Eingabe- und Ausgabe‑Structs, aus deren Typen Huma
Anfragevalidierung und Antwortmodellierung erzeugt. Die
OpenAPI‑Beschreibung entsteht dabei mit, sodass die Dokumentation
dem Code folgt statt in einem Wiki zu veralten. Neue Endpunkte
wurden mit Huma geschrieben, bestehende Routen migriert. Genau zwei
blieben direkt auf Fiber: die WebSocket‑Endpunkte, für die der
direkte Socketzugriff sinnvoll ist und Humas Anfrage‑Antwort‑Modell
nicht passt. Daraus sind 649 Pfade mit 760 Operationen geworden.
Eine CI‑Prüfung vergleicht die tatsächlich vom Server registrierten
Routen mit den in OpenAPI angekündigten. Die Übereinstimmung beträgt
100 % und bleibt bestehen, weil eine nicht beschriebene Route den
Build scheitern lässt.

Ergebnis. Neue Endpunkte erhalten ohne Zusatzarbeit Validierung und
aktuelle Dokumentation. Eine ganze Klasse von Fehlern nach dem
Muster "hier wurde dieses Feld nicht geprüft" entfiel. Bei 760
Operationen ist die Beschreibung der einzig praktikable Einstieg in
die API. Ihre garantierte Vollständigkeit zählt deshalb noch mehr
als bei fünfzig. Der typisierte Vertrag machte Änderungen sicherer
und die Übergabe einfacher, weil die Typen die Erwartungen eines
Endpunkts beschreiben.

Kategorien:
1Plattformarchitektur	/de/categories/platform-architecture/	engineer.company	70
1Backend‑Entwicklung	/de/categories/backend/	engineer.company	70
1APIs und Integration	/de/categories/api/	engineer.company	70
1Migrationen und Modernisierung	/de/categories/migration/	engineer.company	70
1Tests und Qualitätssicherung	/de/categories/testing/	engineer.company	70
1Dokumentation	/de/categories/documentation/	engineer.company	70

Leistungen:
1Plattform- und Lösungsarchitektur	/de/services/platform-architecture/	engineer.company	70
1Backend- und API‑Entwicklung	/de/services/backend-development/	engineer.company	70
1Werkzeuge für KI‑Agenten und MCP‑Server	/de/services/ai-tools/	engineer.company	70
1Technische Dokumentation	/de/services/technical-documentation/	engineer.company	70

hDiese Seite im Web	URL:https://engineer.company/de/portfolio/migrated-the-api-to-huma-v2-at-100-parity/	engineer.company	70
