Okamžik
Typ odpovědi získá pole. Implementace je správná, testy procházejí a publikovaná specifikace stále popisuje tvar z minulého měsíce — takže každý spotřebitel z ní vygenerovaný je špatně způsobem, který se projeví v cizí codebase.
Proč k tomu dochází
Specifikace je druhá, ručně udržovaná reprezentace něčeho, co kód už vyjadřuje přesně. Dvě reprezentace jednoho faktu vyžadují akt synchronizace a ten akt se provádí z paměti. Poprvé, kdy někdo spěchá, se přeskočí, a od té chvíle je dokument nedůvěryhodný, takže jej lidé přestanou číst, takže se přestane aktualizovat úplně.
Proč to lepší model nevyřeší
Pracovník, který má změnit implementaci, změní implementaci. Žádat ho, aby aktualizoval také specifikaci, znamená žádat, aby synchronizaci provedlo něco jiného, co může zapomenout; řešením je mít jednu reprezentaci.
Co to stojí
Rozbití konzumenti, jejichž rozbití zjistí konzument, ne producent. A pomalá ztráta samotného dokumentu: jakmile byla specifikace dvakrát nesprávná, bere se jako dokumentace, ne jako kontrakt.
Co Majordomus dělá
Operace se deklaruje jednou, jako typovaný deskriptor vedle své implementace, s typy vstupu a výstupu. Vše vnější se odvozuje z této deklarace: nástroj MCP, trasa HTTP, operace OpenAPI se schématy a příklady, procházitelná reference, cíl měření výkonu a generovaná dokumentace. Přidat operaci úpravou registru transportu nebo souboru specifikace není možné, protože to jsou výstupy. generate --check pojmenuje každý generovaný soubor, který se liší od toho, co deklarace vytváří, a CI strom odmítne.
Před a po
before handler.rs (new field) + openapi.yaml (hand-written, unchanged)
after $ majordomus generate --check
stale: docs/generated/openapi.json (differs)
[reproduce: majordomus generate]Co nedělá
Nehodnotí návrh rozhraní a nerozhoduje, zda je změna zpětně nekompatibilní. Odstraňuje možnost, že se popis a chování udržují zvlášť.