Produktdaten in Magento GraphQL erweitern: eigene Felder und Extension Attributes

1. Warum Produktdaten-Erweiterungen in Magento GraphQL anspruchsvoll sind

Magento liefert von Haus aus ein umfangreiches GraphQL-Schema für Produktdaten. ProductInterface deckt die meisten Standard-Felder ab, aber jedes Projekt hat spezifische Anforderungen: ein Herstellerlabel, das aus einem EAV-Attribut kommt, eine Lieferzeitangabe aus einem externen System oder ein berechnetes Feld, das erst im Resolver durch Geschäftslogik erzeugt wird. Diese Felder müssen ins Schema und in die Resolver-Schicht integriert werden — ohne das bestehende System zu destabilisieren.

Die Komplexität entsteht aus zwei Richtungen: Einerseits muss das Schema korrekt definiert sein (Typen, Nullability, Beschreibungen), andererseits muss der Resolver die Daten effizient liefern. Da bei einer Produktliste viele Produkte gleichzeitig geladen werden, führt ein Resolver, der pro Produkt eine separate Datenbankabfrage macht, direkt in das klassische N+1-Problem. Bei 20 Produkten bedeutet das 21 Datenbankabfragen statt einer — messbar langsamer und bei wachsenden Listen exponentiell schlimmer.

2. Das Schema erweitern: ProductInterface und eigene Typen

Die Schema-Erweiterung in Magento GraphQL erfolgt über .graphqls-Dateien in der etc/-Direktive eines Moduls. Das Schlüsselwort extend type erlaubt es, einen bestehenden Typ um neue Felder zu ergänzen, ohne den Original-Typ zu verändern. Für Produktfelder ist ProductInterface der richtige Ankerpunkt — er wird von allen Produkttypen (SimpleProduct, ConfigurableProduct etc.) implementiert und stellt sicher, dass das neue Feld bei allen Produkttypen verfügbar ist.

Neben einfachen Skalarfeldern (String, Int, Float, Boolean) können auch eigene Typen definiert und als Feldtyp verwendet werden. Das ist besonders nützlich, wenn das neue Feld eine strukturierte Dateneinheit zurückgibt — etwa ein Objekt mit mehreren Unterfeldern. In diesem Fall definiert man zuerst den eigenen Typ mit type MyCustomData und referenziert ihn dann im extend type ProductInterface. Die Datei muss im Verzeichnis etc/ des Moduls liegen und den Namen schema.graphqls tragen.

# etc/schema.graphqls — extend ProductInterface with custom fields
extend type ProductInterface {
  # Simple scalar field from EAV attribute
  manufacturer_label: String @doc(description: "Human-readable manufacturer name from EAV attribute")

  # Structured custom data as object type
  delivery_info: DeliveryInfo @doc(description: "Delivery time and availability info from external system")
    @resolver(class: "Vendor\\Module\\Model\\Resolver\\DeliveryInfo")
}

# Custom object type for structured return values
type DeliveryInfo {
  estimated_days: Int @doc(description: "Estimated delivery days")
  in_stock: Boolean! @doc(description: "Whether the product is currently in stock")
  message: String @doc(description: "Optional human-readable delivery message")
}

3. Den Resolver implementieren: sauber und testbar

Jedes Feld mit einer @resolver-Annotation in der Schema-Datei braucht eine korrespondierende PHP-Klasse, die ResolverInterface implementiert. Der Resolver bekommt über den $value-Parameter Zugriff auf die bereits geladenen Produktdaten — das ist das Array, das der übergeordnete Produkt-Resolver zurückgegeben hat. Die Produkt-ID steckt typischerweise in $value['entity_id'] oder $value['model']->getId().

Entscheidend für die Qualität des Resolvers ist die strikte Trennung von Präsentation und Datenzugriff. Der Resolver selbst sollte keine SQL-Queries formulieren und keine Services kennen, die weit mehr können als das, was für dieses Feld nötig ist. Stattdessen delegiert er an einen spezialisierten Service oder ein Repository, das über Constructor Property Promotion injiziert wird. Das macht den Resolver klein, lesbar und über Unit-Tests testbar — ohne Magento-Framework zu booten.

# Query to test the extended product fields
query ProductWithCustomFields {
  products(search: "jacket", pageSize: 5) {
    items {
      sku
      name
      manufacturer_label
      delivery_info {
        estimated_days
        in_stock
        message
      }
      price_range {
        minimum_price {
          final_price { value currency }
        }
      }
    }
  }
}

4. Extension Attributes korrekt verdrahten

Extension Attributes sind das offizielle Erweiterungskonzept in Magento für Service Contracts. Sie erlauben es, Modellen zusätzliche Daten anzuhängen, ohne die Basisklasse zu verändern. Im GraphQL-Kontext sind Extension Attributes besonders nützlich, wenn die zusätzlichen Daten bereits beim Laden des Produktmodells verfügbar gemacht werden — etwa über einen Plugin auf dem Repository-Load-Mechanismus. Das vermeidet separate Datenbankabfragen im Resolver, weil die Daten bereits im Modell stecken.

Für das Verdrahten von Extension Attributes im GraphQL-Resolver gibt es zwei Wege: Entweder liest der Resolver das Attribut direkt aus dem Produkt-Modell, wenn es im $value['model'] verfügbar ist, oder er verwendet die entity_id, um über einen Service zu laden. Der erste Weg ist schneller, der zweite entkoppelter. Wichtig: Extension Attributes werden erst geladen, wenn sie explizit angefordert werden — das Magento-System lädt sie nicht automatisch für alle Produkte. Ein Plugin auf dem Produkt-Repository-Load kann das ändern und das Attribut vorab befüllen.

5. N+1-Probleme erkennen und vermeiden

Das N+1-Problem ist in GraphQL allgegenwärtig und in Magento besonders kritisch, weil die Datenbankschicht über EAV ohnehin schon viele Queries generiert. Das klassische Szenario: Eine Produktliste lädt 20 Produkte, und für jedes Produkt löst der Resolver ein zusätzliches SELECT aus — zum Beispiel um das Herstellerlabel aus der EAV-Tabelle zu laden. Das ergibt 20 zusätzliche Queries für eine einzige GraphQL-Anfrage.

Die korrekte Lösung ist Batching: Statt pro Produkt eine Abfrage zu machen, sammelt man alle IDs und führt eine einzige Abfrage für alle Produkte gleichzeitig aus. In Magento kann das über einen Batch-Loader implementiert werden, der die IDs in der ersten Phase sammelt und in der zweiten Phase mit einer einzigen Repository-Abfrage alle Daten auf einmal lädt. DataLoader-Bibliotheken (bekannt aus der JavaScript-Welt) implementieren dieses Pattern; in PHP kann man es mit einem einfachen Akkumulator-Muster nachbauen.

# BAD: This query triggers N+1 if each product loads manufacturer_label separately
# For 20 products = 1 products query + 20 manufacturer_label queries = 21 DB queries
query BadProductList {
  products(search: "jacket", pageSize: 20) {
    items {
      sku
      name
      manufacturer_label  # Resolver called once per product — N queries!
    }
  }
}

# GOOD: Same query — but resolver uses batch-loading strategy
# 1 products query + 1 batch query for all manufacturer labels = 2 DB queries
query GoodProductList {
  products(search: "jacket", pageSize: 20) {
    items {
      sku
      name
      manufacturer_label  # Resolver uses BatchLoader — single query for all IDs
    }
  }
}

6. Typische Fehlerbilder bei der Erweiterung

Ein häufiger Fehler ist das direkte Schreiben von SQL im Resolver. Das untergräbt die Abstraktionsschicht und macht den Resolver nicht mehr unabhängig von der Datenbankstruktur testbar. Repositories und Service Contracts sind der korrekte Weg, auch wenn sie mehr Code erfordern. Ein weiterer Fehler ist das Laden des vollständigen Produkt-Modells im Resolver, wenn bereits die ID und die benötigten Daten über das $value-Array verfügbar sind. Das führt zu doppelten Loads und unnötiger Last.

Auch die Schema-Definition enthält häufig Fehler: Felder, die immer einen Wert zurückgeben, sollten als String! (non-nullable) deklariert sein. Nullable-Felder (String ohne !) signalisieren dem Client, dass der Wert fehlen kann — was zu optionaler Behandlung im Frontend führt, die eigentlich nicht nötig wäre. Fehlende @doc-Annotationen erschweren die Selbstdokumentation des Schemas und sind in Teams eine häufige Quelle von Missverständnissen über Feldintention und -werte.

7. EAV-Attribute im GraphQL-Kontext

EAV-Attribute (Entity-Attribute-Value) sind der normale Weg in Magento, Produktdaten ohne Schema-Migration zu erweitern. Im GraphQL-Kontext ist das Laden von EAV-Attribut-Werten aber mit Vorsicht zu genießen: EAV-Abfragen sind intern teuer, weil die Daten auf mehrere Tabellen verteilt sind und Joins erfordern. Wer für jedes Produkt ein EAV-Attribut einzeln lädt, summiert diesen Overhead schnell auf kritische Werte.

Die empfohlene Strategie ist es, EAV-Attribute, die häufig im GraphQL-Kontext verwendet werden, beim Produktladen vorab mit zu laden und über Extension Attributes am Produkt-Modell zu befestigen. Das Magento-Modell-Load-Mechanismus lädt bei Verwendung von getProduct()` oder Repository-Methoden nicht automatisch alle EAV-Attribute — sie werden lazy geladen. Wer gezielt bestimmte Attribute vorladen will, kann das über die `addAttributeToSelect`-Methode auf der Collection oder über einen Plugin auf dem Repository-Load steuern.