GraphQL-Fragmente im Hyvä-Theme wiederverwendbar strukturieren

1. Das Problem: duplizierte Felder in jeder Produkt-Query

In einem gewachsenen Hyvä-Theme fragen Produktliste, Warenkorb, Wunschliste und Cross-Selling-Slider fast immer dieselben Basisfelder ab: SKU, Name, Bild, Preisbereich und URL-Key. Sind diese Felder in jeder Query-Datei einzeln ausgeschrieben, wächst mit jeder neuen Verwendungsstelle das Risiko, dass eine Anpassung an einer Stelle vorgenommen wird und an allen anderen vergessen geht.

Die Folgen zeigen sich meist erst in Produktion: ein Sonderpreis, der auf der Wunschliste fehlt, weil die dortige Query nie um special_price ergänzt wurde, oder eine Preisformatierung, die zwischen Kategorieseite und Warenkorb leicht abweicht, weil beide Stellen unabhängig voneinander gepflegt wurden. Der Wartungsaufwand skaliert dabei nicht mit der Anzahl der Felder, sondern mit der Anzahl der Stellen, an denen dieselben Felder erneut abgetippt wurden.

2. GraphQL-Fragment-Grundlagen kurz wiederholt

Ein benanntes Fragment definiert eine Feldauswahl einmalig für einen bestimmten Typ und lässt sich anschließend per Spread-Operator in beliebig vielen Queries einbinden. Für Magento bedeutet das konkret: Ein Fragment ProductCardFields auf ProductInterface beschreibt exakt die Felder, die eine Produktkarte benötigt, und jede Query, die eine Produktkarte rendert, bindet dieses eine Fragment ein, statt die Felder erneut zu deklarieren.

Magentos GraphQL-Schema unterstützt Fragmente wie jeder standardkonforme GraphQL-Server, ohne Sonderbehandlung. Das funktioniert unabhängig davon, ob im Hyvä-Frontend ein schlanker Fetch-basierter GraphQL-Client oder eine umfangreichere Bibliothek mit Query-Caching zum Einsatz kommt, denn Fragmente sind reine Syntax auf Ebene des Query-Dokuments und werden vor dem Versand zu einer vollständigen Query zusammengesetzt.

fragment ProductCardFields on ProductInterface {
  sku
  name
  url_key
  small_image {
    url
    label
  }
  price_range {
    minimum_price {
      regular_price { value currency }
      final_price { value currency }
    }
  }
}

query CategoryProducts($categoryId: String!) {
  products(filter: { category_id: { eq: $categoryId } }) {
    items {
      ...ProductCardFields
    }
  }
}

query WishlistItems($wishlistId: ID!) {
  wishlist(id: $wishlistId) {
    items_v2 {
      items {
        product {
          ...ProductCardFields
        }
      }
    }
  }
}

3. Fragment-Komposition in Schichten: Preis-, Karten- und Detail-Fragment

In der Praxis lohnt sich eine geschichtete Struktur statt eines einzigen großen Fragments: Ein kleines ProductPriceFields-Fragment kapselt ausschließlich die Preislogik, ProductCardFields bindet dieses Preis-Fragment ein und ergänzt Bild und Name, und ProductDetailFields baut wiederum auf ProductCardFields auf und ergänzt Beschreibung sowie kundenspezifische Attribute. Ändert sich ein Preisfeld, etwa weil ein neues Tier-Price-Feld hinzukommt, genügt eine Änderung an genau einer Stelle, und sie wirkt überall dort, wo Preise angezeigt werden.

Diese Schichtung spiegelt bewusst die Struktur der Hyvä-Templates wider: Ein price.phtml-Partial rendert dieselben Felder, die das Preis-Fragment liefert, ein product-card.phtml bindet dieses Partial ein, genau wie die zugehörige Query das Preis-Fragment einbindet. Wenn Template-Grenzen und Fragment-Grenzen aufeinander abgestimmt sind, lässt sich beides gemeinsam denken, statt getrennte mentale Modelle für Markup und Datenabfrage zu pflegen.

fragment ProductPriceFields on ProductInterface {
  price_range {
    minimum_price {
      regular_price { value currency }
      final_price { value currency }
      discount { percent_off }
    }
  }
}

fragment ProductCardFields on ProductInterface {
  sku
  name
  url_key
  small_image { url label }
  ...ProductPriceFields
}

fragment ProductDetailFields on ProductInterface {
  ...ProductCardFields
  description { html }
  meta_description
  categories { name url_path }
}

4. Fragmente zentral organisieren statt inline in jeder Query-Datei

Statt Fragmente in jeder Query-Datei erneut zu definieren, empfiehlt sich ein eigenes Verzeichnis für wiederverwendbare Fragmente, aus dem jede Query importiert, was sie tatsächlich braucht. Der Hyvä-GraphQL-Client baut die finale Query aus Hauptdokument und importierten Fragmenten zusammen, sodass am Ende genau eine vollständige Anfrage an den Server geht, während der Quelltext selbst modular bleibt und sich einzelne Fragmente unabhängig testen lassen.

Eine Stolperfalle dabei sind Namenskollisionen: Definieren zwei Teams unabhängig voneinander ein Fragment namens ProductFields mit unterschiedlichem Inhalt, entsteht beim Zusammenbau der Query ein Konflikt, der sich erst zur Laufzeit als kryptischer Fehler zeigt. Eine feature-präfixierte Namenskonvention, etwa PlpProductCardFields versus CheckoutProductFields, verhindert solche Kollisionen zuverlässig, auch wenn mehrere Teams parallel an unterschiedlichen Bereichen des Themes arbeiten.

// app/design/frontend/Vendor/hyva-child/web/js/graphql/fragments/product-card.js
export const PLP_PRODUCT_CARD_FIELDS = /* GraphQL */ `
  fragment PlpProductCardFields on ProductInterface {
    sku
    name
    url_key
    small_image { url label }
  }
`;

// app/design/frontend/Vendor/hyva-child/web/js/graphql/queries/category-products.js
import { PLP_PRODUCT_CARD_FIELDS } from '../fragments/product-card';

export const CATEGORY_PRODUCTS_QUERY = /* GraphQL */ `
  ${PLP_PRODUCT_CARD_FIELDS}
  query CategoryProducts($categoryId: String!) {
    products(filter: { category_id: { eq: $categoryId } }) {
      items { ...PlpProductCardFields }
    }
  }
`;

5. Query-Größe und Netzwerk-Overhead durch Fragmente reduzieren

Fragment-Wiederverwendung wirkt sich nicht in erster Linie über bessere Kompression aus, sondern darüber, dass jede einzelne Query nur die Felder enthält, die die jeweilige Ansicht tatsächlich benötigt. Eine Wunschliste, die nur das schlanke ProductCardFields-Fragment einbindet, überträgt spürbar weniger Daten als eine Query, die versehentlich das vollständige ProductDetailFields-Fragment mit Beschreibung und Kategorie-Baum mitschleppt, nur weil es an anderer Stelle ohnehin schon existierte.

Bei persistierten Queries zahlt sich Fragment-Disziplin zusätzlich aus: Ein überschaubarer, klar geschichteter Satz an Query-Dokumenten lässt sich gegen eine Allow-List auf Serverseite deutlich einfacher prüfen und pflegen als Dutzende beinahe identischer, unabhängig voneinander gewachsener Queries, die sich im Laufe der Zeit leise auseinanderentwickelt haben.

6. Fragmente und clientseitiges Caching im Hyvä-Frontend

Normalisiertes clientseitiges Caching setzt voraus, dass dieselbe Entität, etwa ein Produkt mit einer bestimmten SKU, an jeder Aufrufstelle mit derselben Feldform zurückkommt. Fragmente garantieren genau das: Wird überall dasselbe ProductCardFields-Fragment verwendet, lassen sich Cache-Einträge für dieselbe SKU verlustfrei zusammenführen, statt dass Karte, Wunschliste und Warenkorb jeweils einen eigenen, leicht abweichenden Teilausschnitt derselben Entität im Cache hinterlegen.

Im Hyvä-Frontend lässt sich ein solcher Cache pragmatisch als Alpine-Store umsetzen, der Produkte anhand der SKU indiziert und beim Lesen prüft, ob bereits ein vollständiger Eintrag vorliegt, bevor eine neue Anfrage ausgelöst wird. Weil die Feldform durch das Fragment garantiert konsistent ist, genügt ein einfacher Objekt-Merge, ohne dass eine komplexere Normalisierungsbibliothek notwendig wird.

// web/js/graphql/product-cache.js
const productCache = {};

export function mergeProduct(product) {
  productCache[product.sku] = { ...productCache[product.sku], ...product };
  return productCache[product.sku];
}

export function getCachedProduct(sku) {
  return productCache[sku] || null;
}

7. Versionierung von Fragmenten bei Schema-Änderungen zwischen Magento-Updates

Magento-Minor-Releases verschieben gelegentlich Felder im GraphQL-Schema, etwa wenn die Struktur von price_range um ein neues Feld für Staffelpreise erweitert wird oder ein bislang genutztes Feld als deprecated markiert und später entfernt wird. Liegen alle Produktfelder zentral in wenigen geschichteten Fragmenten, findet die Anpassung an genau dieser Stelle statt, statt in Dutzenden Dateien nach vereinzelten Vorkommen suchen zu müssen.

Bei größeren Breaking Changes empfiehlt sich eine übergangsweise parallele Fragment-Version, etwa ProductCardFieldsV2 neben dem bestehenden ProductCardFields, sodass einzelne Views nacheinander migriert und getestet werden können, bevor die alte Version entfernt wird. Ein kurzer Kommentarblock am Anfang jeder Fragment-Datei, der die minimal unterstützte Magento-Version dokumentiert, erspart bei zukünftigen Upgrades das mühsame Nachvollziehen, seit wann welches Feld überhaupt existiert.

# Kompatibel ab Magento 2.4.6, price_range.minimum_price ohne tier_prices
fragment ProductCardFields on ProductInterface {
  sku
  name
  price_range {
    minimum_price {
      regular_price { value currency }
      final_price { value currency }
    }
  }
}

# Ab Magento 2.4.8, ergänzt tier_prices für Staffelpreis-Anzeige
fragment ProductCardFieldsV2 on ProductInterface {
  sku
  name
  price_range {
    minimum_price {
      regular_price { value currency }
      final_price { value currency }
    }
  }
  price_tiers {
    quantity
    final_price { value currency }
  }
}

8. Testen und Schema-Validierung von Fragmenten in der CI-Pipeline

Eine Introspection-Query gegen die eigene Magento-Instanz liefert das vollständige, aktuell tatsächlich verfügbare Schema als Referenz. Ein kleines Skript, das alle Feldselektionen der eigenen Fragmente gegen dieses introspizierte Schema prüft, deckt Breaking Changes bereits auf, bevor ein Composer-Update von magento/module-graph-ql ungetestet in Produktion landet und dort erst durch fehlerhafte Antworten auffällt.

Läuft diese Prüfung als eigener Schritt in der CI-Pipeline vor jedem Deployment, schlägt der Build zuverlässig fehl, sobald ein Fragment ein Feld referenziert, das im Ziel-Schema nicht mehr existiert. Das verwandelt einen potenziellen Produktionsfehler in eine klar lesbare Fehlermeldung im Pull Request, lange bevor ein Kunde eine kaputte Produktkarte zu Gesicht bekommt.

9. Checkliste für eine wartbare Fragment-Struktur

Fragment-Komposition ist kein Selbstzweck, sondern zahlt sich vor allem dann aus, wenn das Team eine klare Konvention für Ablageort, Benennung und Schichtung konsequent einhält. Ein einziges undiszipliniert wachsendes Mega-Fragment, das versehentlich alle jemals benötigten Felder enthält, verursacht am Ende dieselben Probleme wie gar keine Fragmente, nur an einer einzigen, dafür umso unübersichtlicheren Stelle.

Die folgende Übersicht ordnet die in diesem Artikel besprochenen Maßnahmen nach Wirkung und Umsetzungsaufwand, damit sich ein Team zuerst auf die Punkte konzentrieren kann, die den größten Effekt bei überschaubarem Aufwand versprechen.

10. Zusammenfassung

11. FAQ: GraphQL-Fragmente im Hyvä-Theme