Backend for Frontend: Referenzarchitektur

Platziert client-spezifische Aggregation, Caching und Release-Kopplung in einer BFF-Schicht, während Domain-Services client-agnostisch bleiben, mit expliziten Regeln dafür, was nicht über die Grenze hinweg durchsickern darf.

Paketstatus: KI-unterstütztes Referenzpaket. Statische Paketvalidierung wurde bestanden; Implementierungsszenarien wurden noch nicht ausgeführt und eine menschliche Domänenprüfung ist vor stabiler Übernahme erforderlich.

Entscheidung

Führe pro Client-Familie ein Backend-for-Frontend (BFF) ein, wenn Aggregation, Payload-Gestaltung oder Release-Rhythmus sich über Web-, Mobile- oder Partner-Oberflächen unterscheiden. Domain-Services stellen stabile, client-neutrale Fähigkeiten bereit; BFFs übernehmen die Client-Kopplung und können sich innerhalb dokumentierter Grenzen unabhängig weiterentwickeln.

Umfang

• Verantwortlichkeiten von BFF versus Domain-Services.
• Erlaubte Aggregation, Caching, Authentifizierungsbeendigung und Anpassung von Paginierung.
• Verbotenes Durchsickern client-spezifischer Belange in Domain-APIs.
• Timeout-Budgets, Degradationsverhalten und Regeln für unabhängige Deployments.

Außerhalb dieses Blocks

• Allgemeine Microservice-Zerlegungsstrategie.
• CDN- und statische Asset-Lieferungsarchitektur.
• Vollständige API-Versionierungsrichtlinie (siehe API-Versionierungs-Referenzblock).

Vertrag

• Domain-Services exponieren keine client-spezifischen Feldnamen, UI-Konzepte oder Transportoptimierungen, die an einen Client gebunden sind.
• Jeder Aggregate dokumentiert Upstream-Endpunkte, max_upstream_calls und Komponenten-Kritikalität (required, optional oder sensitive) in aggregate_upstream_map; Tests prüfen Aufruf-Fan-out und Fehlerverhalten gegen diese Map.
• BFFs führen Response-Shaping durch und können mit TTL pro Aggregate cachen; Domain-Services bleiben cache-agnostisch, sofern kein Shared Cache explizit entworfen wurde.
• Jeder BFF dokumentiert sein Upstream-Call-Budget. Eine optionale Komponente kann eine strukturierte Teilantwort zurückgeben, wenn das Budget erschöpft ist; eine erforderliche oder sensitive Komponente schlägt den Aggregate-Call mit einem strukturierten Fehler für die gesamte Anfrage fehl.
• Authentifizierung kann am BFF enden, aber Domain-Services vertrauen client-übermittelten Identitäten nicht ohne validierte Service-zu-Service-Credentials.
• BFF-Releases können ohne Domain-Deployment ausgeliefert werden, wenn Änderungen auf das im BFF-Manifest gelistete Shaping beschränkt sind.
• Paginierungs- und Filteranpassungen sind Teil des BFF-Vertrags; Domain-Paginierungs-Defaults bleiben stabil.

Implementierungsleitfaden

• Generiere BFF OpenAPI- oder GraphQL-Schemas pro Client; verbiete das Importieren von Client-Typen in Domain-Module.
• Nutze Architekturtests, um verbotene Importe oder DTO-Felder in Domain-Paketen zu erkennen.
• Instrumentiere Upstream-Call-Zählungen pro BFF-Endpunkt, um N+1-Aggregationsregressionen zu erkennen.
• Überprüfe die Kritikalität von Aggregaten als Teil des API-Vertrags; leite sie nicht dynamisch daraus ab, ob ein Upstream zufällig antwortet.
• Dokumentiere Aggregate in example.yaml und versioniere sie zusammen mit dem BFF.

Fehlerbehandlung und Schutzmaßnahmen

• Wenn eine optionale Upstream-Komponente ausfällt, kann der BFF Teilantworten mit expliziten Fehler-Einträgen zurückgeben, statt synthetische Defaults zu liefern. Der Ausfall einer erforderlichen oder sensitiven Komponente führt zu einem strukturierten Fehler für die gesamte Anfrage ohne irreführende Teilaggregate.
• Schalte bei wiederholten Upstream-Ausfällen pro Aggregate einen Circuit Breaker ein, um Domain-Services zu schützen.
• Betten Sie keine Geschäftsregeln in den BFF ein, die in Domain-Services gehören, nur um schneller ausliefern zu können.

Verifikation und Betrieb

• Verfolge BFF-Upstream-Latenz, Fehlerquoten und Call-Fan-out pro Endpunkt.
• Überprüfe vierteljährlich, ob neue Client-Logik noch in den BFF gehört oder in die Domain.
• Teste unabhängige Deployments durch Veröffentlichung einer reinen BFF-Änderung in Staging.

Die ausführbar aussehenden Beispiele in diesem Paket sind Fixtures und Akzeptanzverträge. Validieren Sie die Paketstruktur vor der Übernahme; implementieren und führen Sie dann die Szenarien im Ziel-Repository aus.

Annahmen zur Übernahme

• Client-Namen, Aggregate und Timeout-Werte in example.yaml sind Profilentscheidungen für ein Dashboard-Produkt, keine universellen Defaults.
• Teams müssen Service-Identitäten und mTLS-Richtlinien an ihre Plattformstandards anpassen.

Referenzen

• Keine externe normative Quelle erforderlich; dieses Paket definiert eine BFF-Grenzentscheidung.