API Platform im Enterprise-Maßstab: GraphQL, Pagination und N+1-Abwehr in Symfony

Wenn ein Team API Platform GraphQL Symfony zum ersten Mal in der Produktion betreibt, ist die Demo glorreich. Eine einzige Annotation stellt eine Entität gleichzeitig über REST und GraphQL bereit, die OpenAPI-Doku generiert sich von selbst, und das Frontend-Team hört auf, Tickets für Endpunkte einzureichen. Sechs Monate später piept genau dieses Setup den Bereitschaftsingenieur um 2 Uhr nachts an, weil eine verschachtelte GraphQL-Abfrage 4.000 Datenbank-Roundtrips auslöst und ein paginierter Collection-Endpunkt gerade versucht hat, eine halbe Million Zeilen in eine einzige Antwort zu serialisieren.

Nichts davon ist ein Fehler im Framework. API Platform tut genau das, was du ihm gesagt hast. Das Problem ist, dass die Defaults, die einen Prototypen mühelos machen, nicht die Defaults sind, die Enterprise-Traffic überstehen. Dieser Beitrag geht die drei Fehlermodi durch, die im Maßstab auftauchen, nämlich GraphQL-Auflösungskosten, unbegrenzte Pagination und die klassische N+1-Abfrage, und die konkreten Muster, die jeden davon von der Produktion fernhalten.

Warum der Maßstab die Regeln ändert

In Prototypengröße ist jede Abfrage schnell, weil jede Tabelle klein ist. Ein naives SELECT, das drei Entitäten joint und Indizes ignoriert, kommt in zwei Millisekunden gegen tausend Zeilen zurück. Dieselbe Abfrage gegen vier Millionen Zeilen, einige hundert Mal pro Sekunde ausgeführt, ist ein anderer Organismus. Zwei Dinge brechen die Prototyp-Annahmen: Das Datenvolumen wächst, und die Zugriffsmuster werden feindselig. Echte Clients fordern tief verschachtelte Daten an, verlangen Seite 9.000 und hämmern in einer Schleife auf den am günstigsten aussehenden Endpunkt ein.

API Platform sitzt auf Doctrine, und Doctrine ist ein Lazy-Loading-ORM. Lazy Loading ist wunderbar für die Ergonomie der Entwickler und tückisch für die Performance, weil die Kosten einer Beziehung an der Stelle, an der du den Code schreibst, unsichtbar sind und erst unter Last sichtbar werden. Eine API-Platform-Anwendung zu skalieren ist im Wesentlichen die Disziplin, diese versteckten Kosten explizit und begrenzt zu machen.

N+1-Abfragen: der Standard-Fehlermodus

Das N+1-Problem ist einfach zu formulieren. Du holst eine Collection von N Entitäten mit einer Abfrage, greifst dann auf jeder eine Beziehung ab und löst N zusätzliche Abfragen aus. Hole 100 Bestellungen, lies order.customer.name auf jeder, und du hast gerade 101 Abfragen statt 2 ausgeführt. Unter GraphQL potenziert sich das, weil ein Client Beziehungen in einer einzigen Anfrage mehrere Ebenen tief verschachteln kann und jede Ebene die Roundtrips multipliziert.

Die erste Abwehr ist die Fähigkeit des EntityManager, verwandte Daten eager zu holen. Für REST-Collections hänge eine Doctrine-Extension an, die dem Query-Builder für die Beziehungen, von denen du weißt, dass sie gelesen werden, einen Join und einen WITH-Fetch hinzufügt. Das QueryCollectionExtensionInterface von API Platform ist der richtige Hook: Du erhältst den Query-Builder, bevor er ausgeführt wird, und kannst leftJoin- und addSelect-Aufrufe hinzufügen, sodass die verwandten Entitäten im selben Result-Set ankommen.

public function applyToCollection(
    QueryBuilder $qb,
    QueryNameGeneratorInterface $gen,
    string $resourceClass,
    ?Operation $operation = null,
    array $context = []
): void {
    if (Order::class !== $resourceClass) {
        return;
    }
    $alias = $qb->getRootAliases()[0];
    $qb->leftJoin("$alias.customer", 'c')->addSelect('c');
}

Für GraphQL reicht der Join-Trick allein nicht, weil der Client die Form der Abfrage zur Anfragezeit bestimmt und du nicht jeden möglichen Pfad vorjoinen kannst. Hier verdient sich das DataLoader-Muster seinen Platz. Ein DataLoader bündelt die Beziehungs-Lookups, die während einer einzigen GraphQL-Auflösung passieren: Statt customer für jede von 100 Bestellungen einzeln aufzulösen, sammelt er die 100 Kunden-IDs, setzt eine WHERE id IN (...)-Abfrage ab und übergibt jedem Resolver sein Ergebnis. API Platform integriert sich darüber mit benutzerdefinierten Resolvern und der darunterliegenden webonyx/graphql-php-Laufzeit. Die Faustregel ist deutlich: Jede in einem GraphQL-Schema erreichbare Beziehung braucht entweder einen Eager-Join oder einen gebündelten Loader, niemals einen Lazy-Fetch pro Zeile.

Das günstigste Erkennungswerkzeug steckt bereits in deinem Stack. Aktiviere den Doctrine-SQL-Logger in deiner Testumgebung und prüfe die Abfrageanzahl per Assertion. Ein funktionaler Test, der eine repräsentative GraphQL-Abfrage abfeuert und fehlschlägt, wenn die Datenbank öfter als eine feste Anzahl berührt wurde, verwandelt N+1-Regressionen in rote CI-Läufe statt in Anrufe um 2 Uhr nachts.

Pagination: Lass den Client niemals unbegrenzt wählen

API Platform paginiert Collections standardmäßig, was sich anfühlt, als sei das Problem bereits gelöst. Ist es nicht, aus zwei Gründen. Erstens ist die Standard-Seitengröße ein Ausgangspunkt, keine Obergrenze, und Clients können sie oft über den itemsPerPage-Parameter überschreiben. Ohne ein hartes Maximum kann eine einzige Anfrage fünfzigtausend Elemente verlangen und Datenbank und Serializer zwingen, sie alle zu materialisieren. Zweitens degradiert die Offset-Pagination selbst. LIMIT 20 OFFSET 100000 zwingt die Datenbank, sich durch hunderttausend Zeilen zu zählen, bevor sie sie verwirft, sodass tiefe Seiten langsamer werden, je weiter ein Client scrollt.

Der erste Fix ist eine Konfigurationsdisziplin. Setze sowohl ein Standard- als auch ein Maximum an Elementen pro Seite, und mache das Maximum erzwingbar statt beratend.

#[ApiResource(
    paginationItemsPerPage: 30,
    paginationMaximumItemsPerPage: 100,
    paginationClientItemsPerPage: true
)]
class Order {}

Mit gesetztem paginationMaximumItemsPerPage bekommt ein Client, der 50.000 verlangt, 100. Diese eine Zeile entfernt eine ganze Klasse von versehentlichem und absichtlichem Denial-of-Service.

Der tiefere Fix für große Datenmengen ist cursorbasierte Pagination. Statt eines Offsets übergibt der Client einen opaken Cursor, der den zuletzt gesehenen Sortierschlüssel kodiert, und die Abfrage wird zu WHERE id > :cursor ORDER BY id LIMIT 30. Diese Abfrage nutzt den Index und bleibt konstant in der Zeit, egal wie tief der Client scrollt. API Platform unterstützt Cursor-Pagination nativ über das paginationViaCursor-Attribut, gepaart mit einem korrekt indizierten und sortierten Feld. Der Kompromiss ist, dass Clients die Fähigkeit verlieren, zu einer beliebigen Seitenzahl zu springen, was für Infinite-Scroll und API-zu-API-Integrationen fast immer akzeptabel und für eine klassische Seitenzahl-UI fast nie akzeptabel ist. Wähle pro Ressource danach, wie die Daten tatsächlich konsumiert werden.

GraphQL-spezifische Kostenkontrollen

GraphQL übergibt die Abfragekonstruktion dem Client, was zugleich das Feature und das Risiko ist. Zwei Kontrollen halten diese Macht begrenzt. Die Begrenzung der Abfragetiefe weist Anfragen ab, die tiefer als eine konfigurierte Anzahl von Ebenen verschachteln, und stoppt so eine bösartige oder unachtsame Abfrage davon, den gesamten Objektgraphen abzulaufen. Die Analyse der Abfragekomplexität weist jedem Feld Kosten zu und weist Anfragen ab, deren Gesamtsumme ein Budget überschreitet, was die breiten-und-flachen Abfragen einfängt, die die Tiefenbegrenzung verfehlt. Beide werden in der GraphQL-Schicht konfiguriert, und beide sollten gesetzt sein, bevor der erste externe Client das Schema berührt.

Es lohnt sich auch, bewusst zu entscheiden, welche Entitäten überhaupt gegenüber GraphQL exponiert werden. Die Annotation, die das Exponieren trivial macht, macht auch das Über-Exponieren trivial. Beschränke Mutationen und sensible Lesepfade mit Security-Expressions und halte die Schema-Oberfläche auf das, was Clients wirklich brauchen. Ein kleineres Schema ist zugleich eine kleinere Angriffsfläche und eine kleinere Performance-Fläche.

Serialization-Groups halten Payloads ehrlich

Der letzte Hebel im Enterprise-Maßstab ist das, was das Gebäude verlässt. Die Normalization-Groups von API Platform steuern, welche Felder in einer Antwort erscheinen. Ohne explizite Groups neigt eine Entität dazu, alles zu serialisieren, einschließlich Beziehungen, die du nicht exponieren wolltest, und berechneter Felder, die während der Normalisierung zusätzliche Abfragen auslösen. Definiere Read- und Write-Groups pro Operation, sodass jeder Endpunkt eine bewusste, minimale Payload zurückgibt.

#[ApiResource(
    normalizationContext: ['groups' => ['order:read']],
    denormalizationContext: ['groups' => ['order:write']]
)]
class Order
{
    #[Groups(['order:read'])]
    public int $id;

    #[Groups(['order:read', 'order:write'])]
    public string $reference;
}

Enge Groups leisten doppelte Arbeit. Sie verkleinern die Antwortgröße, was in Mobilfunknetzen zählt, und sie verhindern, dass der Serializer Beziehungen berührt, die andernfalls Lazy Loads auslösen würden. Manches N+1 entpuppt sich als nicht in der Abfrage entstanden, sondern in einer Serialization-Group, die breiter war, als irgendjemand ahnte.

Alles zusammensetzen

API Platform GraphQL Symfony im Enterprise-Maßstab zu betreiben bedeutet nicht, gegen das Framework zu kämpfen. Es bedeutet, die Prototyp-Defaults durch explizite, begrenzte Entscheidungen zu ersetzen: Eager-Joins und DataLoader, damit Beziehungen niemals pro Zeile lazy laden, harte Pagination-Maxima und Cursor-Pagination, damit Collections konstant in der Zeit bleiben, Tiefen- und Komplexitätslimits, damit GraphQL nicht als Waffe genutzt werden kann, und enge Serialization-Groups, damit Payloads nur das tragen, wonach gefragt wurde. Füge der CI eine Assertion auf die Abfrageanzahl hinzu, und die meisten dieser Regressionen werden gefangen, bevor sie ausgeliefert werden.

Das Muster unter all dem ist dasselbe, das gute Engineering-Teams überall anwenden: Mach das teure Ding sichtbar, dann begrenze es. Wenn dein Team auf eine API starrt, die wunderschön demonstriert hat und nun unter echtem Traffic einknickt, ist das ein lösbares Problem, und meist eines, das schneller zu beheben als auszuhalten ist.

Bei Wolf-Tech helfen wir Produktteams, Symfony- und API-Platform-Systeme für die Produktionslast zu härten, von Custom Software Development bis zu gezieltem Code-Quality-Consulting an der API-Schicht, die du bereits hast. Wenn ein Performance-Review deiner API helfen würde, schreib an hello@wolf-tech.io oder finde uns unter wolf-tech.io.