beug.k@beugsiud.deandClaude Opus 5.5
eb1fa0b2e4
- 0016: verified edition, signature scheme and feature set; build-time account/public key, nonce, fingerprint, grace semantics, license files - 0019: OpenAPI contract tests instead of generated server stubs - 0020: Argon2id, TOTP, OIDC with PKCE, sessions, CSRF, rate limits, RBAC Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1.6 KiB
1.6 KiB
0019 – OpenAPI: Vertragstests statt generierter Server-Stubs
- Status: Akzeptiert, ersetzt den Server-Teil von 0012
- Datum: 2026-10-12
Kontext
0012 sah vor, das Server-Interface mit oapi-codegen aus der Spezifikation zu generieren. Auf dem Entwicklungsrechner verhindert eine Sicherheitsrichtlinie, lokal gebaute Werkzeuge auszuführen. Ein Generator, der nur in der CI läuft, würde jede API-Änderung zu einer Runde über die CI machen. Wichtiger ist ohnehin das Ziel hinter 0012: Server und Spezifikation dürfen nicht auseinanderlaufen.
Entscheidung
server/api/openapi.yamlbleibt die verbindliche Quelle.- Handler werden von Hand geschrieben, mit typisierten Request-/Response-Strukturen.
- Vertragstests (mit
kin-openapi) sichern die Übereinstimmung:- Die Spezifikation ist gültiges OpenAPI 3.0.
- Jede Operation der Spezifikation ist im Router registriert und umgekehrt (Methode + Pfadmuster).
- Eine Test-Middleware validiert in allen API-Tests jede Anfrage und jede Antwort gegen die Spezifikation. Eine undokumentierte Antwort lässt den Test fehlschlagen.
- Frontend unverändert:
openapi-typescripterzeugt die Typen (läuft unter Node),openapi-fetchist der Client. Die CI prüft, dass die generierten Typen aktuell sind.
Konsequenzen
Kein generierter Go-Code und keine Generator-Abhängigkeit im Build. Abweichungen fallen in den Tests auf statt beim Kompilieren. Das ist etwas später, aber genauso verbindlich, solange jede Route getestet ist. Die CI-Abdeckung wird deshalb für server/internal/httpapi ausdrücklich ausgewiesen.