GraphQL-Queries mit KI generieren lassen

1. Warum sich GraphQL-Queries gut für KI-Generierung eignen

Eine GraphQL-Query ist eine textuelle, stark strukturierte Anfrage mit klar definierter Grammatik: geschweifte Klammern, verschachtelte Felder, benannte Operationen und typisierte Argumente. Diese formale Strenge kommt Sprachmodellen entgegen, weil ein bekanntes, häufig trainiertes Muster als Vorlage dient. Anders als bei einer frei formulierten REST-Anfrage zwingt die Syntax selbst zu einer bestimmten Form, was die Fehlerquote gegenüber offenem Prosa-zu-Code-Prompting spürbar senkt.

Trotzdem bleibt eine zentrale Einschränkung bestehen: Claude kennt aus dem Training das öffentlich dokumentierte Magento-GraphQL-Schema, nicht aber projektspezifische Erweiterungen, benutzerdefinierte Attribute oder den exakten Versionsstand der tatsächlich installierten Instanz. Wer beschreibt „Ich brauche eine Query für den Warenkorb mit Preisen und Produktbildern“, bekommt einen plausiblen ersten Entwurf, der aber vor dem produktiven Einsatz gegen das echte Schema geprüft werden muss, weil Felder anders benannt sein oder schlicht nicht existieren können.

2. Wie das Magento-GraphQL-Schema aufgebaut ist

Magento stellt sein komplettes GraphQL-Schema über den Endpunkt /graphql bereit und macht es per Introspection maschinenlesbar abfragbar. Zentrale Wurzeltypen sind Query für Leseoperationen und Mutation für Schreiboperationen, ergänzt um eine große Zahl an Objekttypen wie CartItemInterface, ProductInterface oder StoreConfig. Jeder Typ definiert exakt, welche Felder existieren, welchen Rückgabetyp sie liefern und welche Argumente sie akzeptieren, und genau diese Information macht Introspection vollständig abrufbar.

Wichtig für die Arbeit mit KI-Assistenten ist die Unterscheidung zwischen dem Core-Schema aus magento/module-quote-graph-ql und modulspezifischen Erweiterungen, etwa aus Drittanbieter-Modulen oder eigenen Erweiterungen für individuelle Produktattribute. Jedes installierte Modul kann per schema.graphqls-Deklaration eigene Typen und Felder hinzufügen. Ein konkretes Schema entspricht deshalb in der Praxis nie exakt dem, was ein Sprachmodell aus öffentlicher Dokumentation gelernt hat, weil individuelle Erweiterungen naturgemäß nicht im Trainingsmaterial vorkommen konnten.

3. Von der Beschreibung zur ersten Query

Der Prompt für eine GraphQL-Query sollte die benötigten Daten so konkret wie möglich beschreiben: welche Entität abgefragt wird, welche Felder tatsächlich gebraucht werden und welche Filter oder Sortierungen relevant sind. Ein Prompt wie „Erstelle eine Query, die für einen Warenkorb anhand der maskierten Cart-ID die enthaltenen Artikel mit Menge, Produktname, Bild und Zwischensumme sowie den Gesamtpreis zurückgibt“ liefert deutlich präzisere Ergebnisse als eine vage Formulierung wie „Warenkorb-Query bauen“.

In der Praxis lohnt sich ein zweistufiges Vorgehen: Claude liefert zunächst einen Entwurf basierend auf allgemeinem GraphQL- und Magento-Wissen, danach wird dieser Entwurf gegen das reale Schema der Zielinstanz abgeglichen. Diese Trennung ist bewusst, weil das Sprachmodell in der ersten Stufe schnell iterieren kann, ohne bei jedem Zwischenschritt echte Introspection-Daten liefern zu müssen. Erst wenn die Struktur der Query grundsätzlich passt, folgt die eigentliche Verifikation gegen das laufende System.

Der folgende Rohentwurf zeigt, wie ein erster Vorschlag für die eingangs beschriebene Warenkorb-Query typischerweise aussieht, direkt aus der Beschreibung generiert und noch ungeprüft gegen das reale Schema.

# First draft generated from the plain description, not yet verified
query GetCart($cartId: String!) {
  cart(cart_id: $cartId) {
    id
    email
    total_quantity
    items {
      quantity
      product {
        name
        sku
        thumbnail_url
      }
      row_total
    }
    grand_total
  }
}

Zwei Details in diesem Entwurf sind typische Kandidaten für spätere Korrekturen: thumbnail_url und grand_total als flache Skalarfelder klingen plausibel, entsprechen aber nicht zwingend der tatsächlichen Schachtelung im installierten Schema. Genau diese Art von Abweichung deckt der nächste Abschnitt systematisch auf.

4. Das Halluzinationsrisiko bei generierten Queries

Der häufigste Fehler in KI-generierten Magento-Queries ist das erfundene Feld, das zur restlichen Namenskonvention passen würde, aber im Schema nicht existiert. Ein typisches Beispiel: Claude schlägt cart.total_quantity vor, weil dieses Muster in älteren REST-basierten Codebeispielen häufig auftaucht, während das tatsächliche GraphQL-Feld cart.total_quantity in manchen Magento-Versionen existiert, in anderen aber unter einem anderen Pfad liegt oder zusätzliche Argumente verlangt. Solche Verwechslungen zwischen REST- und GraphQL-Konventionen sind eine der häufigsten Fehlerquellen.

Eine zweite Fehlerquelle ist die falsche Verschachtelung: Ein Feld existiert zwar im Schema, aber nicht auf dem angenommenen Elterntyp, sondern erst eine Ebene tiefer oder höher. Führt man eine solche Query aus, antwortet der Magento-GraphQL-Server mit einer klaren Fehlermeldung wie Cannot query field "x" on type "y", was die Halluzination sofort sichtbar macht. Gefährlicher sind Fälle, in denen ein syntaktisch gültiges, aber semantisch falsches Feld verwendet wird, etwa ein ähnlich benanntes Feld mit abweichender Bedeutung, das die Query fehlerfrei ausführt, aber falsche Daten liefert.

5. Schema-Introspection zur Verifikation nutzen

Die einzig zuverlässige Verifikationsmethode ist die Schema-Introspection der tatsächlichen Zielinstanz. GraphQL bringt dafür eingebaute Meta-Felder wie __type und __schema mit, die Struktur, Felder und Argumente jedes Typs zur Laufzeit zurückgeben. Statt der generierten Query blind zu vertrauen, fragt man gezielt ab, welche Felder ein Typ wie Cart tatsächlich besitzt, und vergleicht das Ergebnis mit dem, was Claude vorgeschlagen hat.

In der Praxis lohnt sich ein kurzes Shell-Kommando, das die Introspection direkt gegen die lokale Entwicklungsumgebung ausführt, bevor eine generierte Query überhaupt in den Code übernommen wird. Das dauert selten länger als wenige Sekunden, verhindert aber zuverlässig, dass ein erfundenes Feld unbemerkt in einen Commit gelangt und erst beim Storefront-Test als Laufzeitfehler auffällt.

#!/usr/bin/env bash
# Verify that a field actually exists on a given GraphQL type
# before trusting an AI-generated Magento cart query
set -euo pipefail

ENDPOINT="https://magento.local/graphql"
TYPE_NAME="Cart"

curl -s -X POST "$ENDPOINT" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query IntrospectType($name: String!) { __type(name: $name) { name fields { name type { name kind ofType { name } } } } }",
    "variables": { "name": "'"$TYPE_NAME"'" }
  }' | jq -r '.data.__type.fields[].name' | sort > /tmp/actual_fields.txt

echo "Fields Claude suggested (edit before running):"
echo "email applied_coupons items prices" | tr ' ' '\n' | sort > /tmp/suggested_fields.txt

echo "Fields not found on type $TYPE_NAME:"
comm -23 /tmp/suggested_fields.txt /tmp/actual_fields.txt

6. Praxisbeispiel: eine Warenkorb-Query für den Storefront

Ein realistisches Anwendungsbeispiel ist die Warenkorb-Query für die Checkout-Seite eines Hyvä-Themes: Sie muss die enthaltenen Artikel, deren Preise, das Produktbild und den Gesamtpreis inklusive Steuern liefern. Nach der Introspection-Prüfung aus dem vorherigen Abschnitt lässt sich eine Query formulieren, die ausschließlich verifizierte Felder verwendet und die maskierte Cart-ID als Variable statt als hartkodierten Wert übergibt, damit sie sowohl für eingeloggte Kunden als auch für Gäste funktioniert.

Der folgende Request-Body zeigt die finale, gegen das Schema geprüfte Query als vollständige GraphQL-Anfrage, wie sie ein Frontend-Client an den /graphql-Endpunkt sendet. Wichtig ist, dass Preise konsequent über das Money-Objekt mit value und currency abgefragt werden, statt einen einzelnen Zahlenwert anzunehmen, ein Detail, das in generierten Erst-Entwürfen häufig fehlt.

{
  "query": "query GetCart($cartId: String!) { cart(cart_id: $cartId) { id email items { uid quantity product { name sku thumbnail { url } } prices { row_total { value currency } } } prices { grand_total { value currency } subtotal_excluding_tax { value currency } applied_taxes { amount { value currency } } } } }",
  "variables": {
    "cartId": "b3f1c9a7e2d4f6a8b1c3d5e7f9a0b2c4"
  }
}

7. Mutationen generieren lassen: zusätzliche Vorsicht bei Schreiboperationen

Mutationen wie addProductsToCart, applyCouponToCart oder setShippingAddressesOnCart verändern echten Systemzustand, weshalb eine halluzinierte Mutation potenziell teurer ist als eine fehlerhafte Query. Ein zusätzliches Risiko: Magento-Mutationen geben häufig ein user_errors-Array zurück, das fachliche Fehler wie „Produkt nicht verfügbar“ signalisiert, ohne dass die HTTP-Antwort selbst einen Fehlerstatus meldet. Ein generierter Client, der dieses Array nicht abfragt, meldet fälschlich Erfolg, obwohl die Mutation fachlich fehlgeschlagen ist.

Bei jeder KI-generierten Mutation lohnt sich deshalb eine bewusste Kontrolle: Wird user_errors im Rückgabetyp abgefragt und im Frontend-Code tatsächlich ausgewertet? Wird die Mutation zunächst gegen eine Staging-Instanz getestet, bevor sie im Storefront-Code landet? Das folgende Beispiel zeigt einen Alpine.js-Handler, der eine verifizierte Mutation aufruft und Fehler aus user_errors korrekt an die Nutzeroberfläche weiterreicht, statt sie stillschweigend zu ignorieren.

// Alpine.js component calling a verified addProductsToCart mutation
document.addEventListener('alpine:init', () => {
  Alpine.data('addToCartForm', () => ({
    loading: false,
    errorMessage: '',

    async addToCart(cartId, sku, quantity) {
      this.loading = true;
      this.errorMessage = '';

      const response = await fetch('/graphql', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          query: `mutation AddToCart($cartId: String!, $sku: String!, $qty: Float!) {
            addProductsToCart(cartId: $cartId, cartItems: [{ sku: $sku, quantity: $qty }]) {
              cart { id total_quantity }
              user_errors { code message }
            }
          }`,
          variables: { cartId, sku, qty: quantity }
        })
      });

      const { data } = await response.json();
      const userErrors = data.addProductsToCart.user_errors;

      // Mutation can succeed on the transport level but still fail on the business level
      if (userErrors.length > 0) {
        this.errorMessage = userErrors[0].message;
      }
      this.loading = false;
    }
  }));
});

8. Testing und Validierung generierter Queries automatisieren

Manuelle Introspection-Checks reichen in größeren Projekten mit vielen Storefront-Queries nicht aus, deshalb sollte die Verifikation Teil der CI-Pipeline werden. Ein einfaches Python-Skript kann jede Query-Datei im Projekt parsen, die referenzierten Feldnamen extrahieren und sie automatisch gegen ein aktuelles Introspection-Dump abgleichen, wodurch erfundene Felder auffallen, bevor ein Reviewer die Query überhaupt zu Gesicht bekommt.

Ergänzend etablieren sich spezialisierte Werkzeuge wie graphql-inspector, die Breaking Changes zwischen zwei Schema-Ständen erkennen und Query-Dokumente direkt gegen ein Schema validieren können. In der CI-Pipeline kombiniert man beides sinnvoll: einen automatischen Schema-Export aus der laufenden Magento-Instanz und eine anschließende Validierung aller Query-Dateien, sodass jede neue oder von Claude vorgeschlagene Query denselben Prüfprozess durchläuft wie handgeschriebener Code.

#!/usr/bin/env python3
# Extract field names from a GraphQL query file and check them
# against a fresh introspection dump of the target schema
import json
import re
import sys
import urllib.request

def fetch_schema_fields(endpoint: str, type_name: str) -> set[str]:
    introspection_query = {
        "query": "query($name: String!) { __type(name: $name) { fields { name } } }",
        "variables": {"name": type_name},
    }
    request = urllib.request.Request(
        endpoint,
        data=json.dumps(introspection_query).encode(),
        headers={"Content-Type": "application/json"},
    )
    with urllib.request.urlopen(request, timeout=5) as response:
        payload = json.loads(response.read())
    fields = payload["data"]["__type"]["fields"]
    return {f["name"] for f in fields}

def extract_query_fields(query_text: str) -> set[str]:
    # Naive field extraction, sufficient for a first automated pass
    return set(re.findall(r"\b([a-z_][a-zA-Z0-9_]*)\s*(?:\(|\{)", query_text))

if __name__ == "__main__":
    endpoint = "https://magento.local/graphql"
    query_file = sys.argv[1]
    query_text = open(query_file).read()

    actual_fields = fetch_schema_fields(endpoint, "Cart")
    used_fields = extract_query_fields(query_text)
    unknown = used_fields - actual_fields - {"query", "mutation", "cart"}

    if unknown:
        print(f"[FAIL] Possibly hallucinated fields: {sorted(unknown)}")
        sys.exit(1)
    print("[OK] All referenced fields verified against schema")

9. KI-generierte GraphQL-Queries im Vergleich

Nicht jede KI-generierte Query birgt dasselbe Risiko, aber ein paar wiederkehrende Muster verdienen besondere Aufmerksamkeit. Die folgende Übersicht zeigt, welches Vorgehen riskant ist und welche empfohlene Praxis das jeweilige Risiko gezielt reduziert.

Auffällig ist, dass keine der empfohlenen Praktiken einen grundsätzlichen Verzicht auf KI-Unterstützung erfordert. Es geht nicht darum, generierte Queries pauschal zu misstrauen, sondern die Verifikation gezielt dort zu konzentrieren, wo ein unentdeckter Fehler den größten Schaden anrichtet: bei Schreiboperationen mit echten Nebenwirkungen und bei Feldern, die erstmals im Projekt verwendet werden.

10. Zusammenfassung

GraphQL-Queries mit KI generieren spart in der Praxis viel Tipparbeit, weil die strenge GraphQL-Syntax Sprachmodellen ein bekanntes Muster liefert, dem sie zuverlässig folgen können. Der entscheidende Schwachpunkt bleibt aber immer derselbe: Claude kennt das öffentliche Schema aus dem Training, nicht das tatsächlich installierte Schema einer konkreten Magento-Instanz mit ihren individuellen Erweiterungen. Erfundene Felder, falsche Verschachtelungen und ignorierte user_errors bei Mutationen sind die häufigsten Folgefehler.

Die wirksamste Gegenmaßnahme ist eine feste Verifikationsroutine: jede generierte Query per Introspection gegen das echte Schema prüfen, bei Mutationen konsequent user_errors auswerten, und automatisierte Schema-Validierung als Sicherheitsnetz in der CI-Pipeline etablieren. Keine dieser Maßnahmen macht die KI-Unterstützung überflüssig, sie verschiebt lediglich den Aufwand vom manuellen Schreiben der Query hin zur gezielten Verifikation an den Stellen, an denen ein unentdeckter Fehler am teuersten wäre.

11. FAQ: GraphQL-Queries mit KI generieren lassen