Zum Inhalt springen

GraphQL-Patterns für Fortgeschrittene: Lerne den AST lieben!

Verschwommene Bewegungsansicht einer Stadtlandschaft durch einen Tunnel mit überlagertem Text „GraphQL Teil 3“.

Apollo Server ist verblüffend einfach aufzusetzen. Du startest mit einem simplen GraphQL-Schema, implementierst ein paar Resolver und los geht's. Ist dein Use Case aber komplexer, musst du besser verstehen, was hinter den Kulissen passiert – und wenn möglich, wie du es anpassen kannst. Genau das schauen wir uns in diesem Artikel an.

Dieser Artikel setzt etwas Praxiserfahrung mit serverseitigem GraphQL voraus, insbesondere mit Apollo Server. Er ist Teil einer Serie von smartive über GraphQL auf Enterprise-Niveau.

Warum sich ein Blick ins Innere von Apollo Server lohnt

Vielleicht hast du das Gefühl, mehr über das GraphQL-Schema wissen zu müssen:

  • Was macht Apollo Server mit dem GraphQL-Schema?
  • Wo und wie komme ich in einem Resolver daran?
  • Wie kann ich das GraphQL-Schema transformieren?
  • Kann ich das Schema (oder Teile davon) programmatisch generieren?

Oder vielleicht bereiten dir die Queries Kopfzerbrechen, die beim GraphQL-Server ankommen:

  • Wie kann ich die Query analysieren, die vom Client kommt?
  • Wie bringe ich die Query mit dem Schema in Verbindung (z. B. um eigene Validierungs-Direktiven zu finden)?
  • Wie nutze ich die Query, um komplexere Resolver zu schreiben (z. B. um Daten in einem allmächtigen Root Resolver rekursiv zu joinen)?

Um diese und viele weitere fortgeschrittene GraphQL-Fragen zu beantworten, musst du dich in den Innereien von Apollo Server sicher bewegen. Genauer gesagt: Du musst verstehen, wie Apollo Server bestimmte GraphQL-Kernbibliotheken einsetzt und wie du sie zu deinem Vorteil nutzt.

Lasst, die ihr eintretet, alle Hoffnung fahren (ohne TypeScript)

Achtung: Wir betreten ein kaum dokumentiertes Gebiet im GraphQL-Land. Du bist hier grösstenteils auf dich allein gestellt. Beim Erkunden dieser Innereien hat sich TypeScript als unverzichtbar erwiesen. Nichts bringt dich hier so weiter wie ctrl-click (abgesehen von console.log).

GraphQL-Schemas verstehen

Es gibt verschiedene Wege, dein GraphQL-Schema zu definieren. Am direktesten geht es mit einer schema.graphql-Datei.

type Book {
  title: String
  author: String
}
type Query {
  books: [Book]
}

Dann definierst du ein paar Resolver und übergibst alles an Apollo Server.

import { readFileSync } from "fs";
import { ApolloServer } from "apollo-server";

const typeDefs = readFileSync("schema.graphql", "UTF8");

const resolvers = {
  Query: {
    books: () => {
      /* get them books */
    }
  }
};

const server = new ApolloServer({ typeDefs, resolvers });

server.listen().then(({ url }) => {
  console.log(`🚀  Server ready at ${url}`);
});

Okay, aber was macht Apollo mit diesen Informationen? Wo komme ich daran? Und wie kann ich sie verändern?

Ausführbare Schemas

Im Hintergrund macht Apollo Folgendes:

  1. Den Schema-String in einen Abstract Syntax Tree (AST) parsen
  2. Den AST in ein GraphQLSchema umwandeln
  3. Die Resolver-Funktionen zum GraphQLSchema-Objekt hinzufügen

Anders gesagt: Die Apollo-Initialisierung oben entspricht Folgendem:

import { buildASTSchema, parse, DocumentNode, GraphQLSchema } from "graphql";
import { addResolveFunctionsToSchema } from "graphql-tools";

const ast: DocumentNode = parse(typeDefs);
const schema: GraphQLSchema = buildASTSchema(ast);
addResolveFunctionsToSchema({
  schema,
  resolvers
});

const server = new ApolloServer({ schema });

Stell es dir so vor: Der AST ist eine Repräsentation des Schema-Dokuments, das GraphQLSchema-Objekt hingegen eine Datenstruktur, die GraphQL-Queries auflösen kann. Beide Typen sind übrigens im Package graphql definiert, der Kernimplementierung der GraphQL-Sprache.

Schema und AST im Resolver holen

Wo finden wir also aus einem Resolver heraus das GraphQLSchema-Objekt, das bei der Initialisierung erzeugt wurde? Im mysteriösen info-Objekt.

Diagramm mit GraphQL-Resolver-Parametern - Parent, Args, Context, Info -, die jeweils mit ihrer Rolle bei der Abfrageverarbeitung beschriftet sind.

Im Beispiel unten greifen wir auf das Schema zu und suchen nach einer Typdefinition. Die Typen in einem GraphQLSchema enthalten oft nicht alle nötigen Informationen. Zum Glück hängt der passende AST-Knoten immer am entsprechenden Typ.

const resolvers = {
  Query: {
    books: (parent: any, args: any, ctx: Context, info: GraphQLResolveInfo) => {
      const bookType = info.schema.getType("Book") as GraphQLObjectType;
      const bookAst: ObjectTypeDefinitionNode = bookType.astNode;
    }
  }
};

Nimm dir einen Moment Zeit, um die Struktur von bookAst zu verstehen:

{
  kind: 'ObjectTypeDefinition',
  name: {
    kind: 'Name',
    value: 'Book',
  },
  interfaces: [],
  directives: [],
  fields: [
    {
      kind: 'FieldDefinition',
      name: {
        kind: 'Name',
        value: 'title',
      },
      arguments: [],
      type: {
        kind: 'NamedType',
        name: {
          kind: 'Name',
          value: 'String',
        },
      },
      directives: [],
    },
    {
      kind: 'FieldDefinition',
      name: {
        kind: 'Name',
        value: 'author',
      },
      arguments: [],
      type: {
        kind: 'NamedType',
        name: {
          kind: 'Name',
          value: 'String',
        },
      },
      directives: [],
    }
  ],
}

Wie du siehst, ist ein Abstract Syntax Tree wirklich genau das: ein grosses, ganz gewöhnliches JavaScript-Objekt, das (einen Teil) des ursprünglichen Dokuments repräsentiert.

Als Faustregel: Das GraphQLSchema hat ein paar nützliche Hilfsfunktionen (z. B. um schnell Vererbungsstrukturen herauszufinden), aber grundsätzlich findest du alle Informationen, die du brauchst, in den AST-Objekten. Verweist ein AST-Objekt auf einen anderen Typ, musst du diesen über das GraphQLSchema-Objekt suchen.

GraphQL-Schemas nutzen

Mit diesem Wissen kannst du fortgeschrittene GraphQL-Programmier-Patterns einsetzen:

  • Du willst ein Schema programmatisch generieren? Bau einen vollständigen AST (ein DocumentNode-Objekt) und übergib ihn wie im Beispiel oben an buildASTSchema.
  • Du willst ein bestehendes Schema beliebig transformieren? Hast du Zugriff auf den vollständigen AST (das DocumentNode-Objekt), dann ändere diesen. Ich vermute allerdings, dass die Referenz auf den vollständigen AST verloren geht. In dem Fall nimm das Snippet unten, um das Schema in einen String umzuwandeln, diesen zu parsen und den resultierenden AST zu ändern.
  • Du willst eigene Schema-Direktiven in deinen Resolvern nutzen? Schau dir den AST an.
  • Du musst in deinen Resolvern bestimmte Eigenschaften von Typen kennen? Schau dir den AST an.

Die folgende Funktion ist praktisch, wenn du ein Schema wieder in einen String umwandeln willst (die ursprüngliche printSchema-Funktion im Package graphql verliert eigene Direktiven).

import { GraphQLSchema, print } from 'graphql';

export function printSchema(schema: GraphQLSchema): string {
  return [
    ...schema.getDirectives().map(d => print(d.astNode)),
    ...Object.values(schema.getTypeMap())
      .filter(t => !t.name.match(/^__/))
      .sort((a, b) => (a.name > b.name ? 1 : -1))
      .map(t => print(t.astNode)),
  ]
    .filter(Boolean)
    .map(s => `${s}\\n`)
    .join('\\n');
}

GraphQL-Queries verstehen

Bis hierhin haben wir gesehen: Apollo macht aus deinem Schema ein Objekt und stellt es im info-Objekt deines Resolvers bereit.

Und was ist mit den Queries, die an den Server geschickt werden? Dasselbe: Apollo macht aus Queries ASTs und legt sie im info-Objekt deines Resolvers ab.

Angenommen, wir schicken folgende Query an unseren GraphQL-Server:

query {
  books {
    title
  }
}

So finden wir sie in unserem Resolver:

const resolvers = {
  Query: {
    books: (parent: any, args: any, ctx: Context, info: GraphQLResolveInfo) => {
      const fieldName: string = info.fieldName;
      const fieldNodes: FieldNode[] = info.fieldNodes;
    }
  }
};

Der Wert von fieldName ist "books", damit kommst du also an den Kontext des aktuellen Resolvers. fieldNodes sieht so aus:

[
  {
    kind: 'Field',
    name: {
      kind: 'Name',
      value: 'books',
    },
    arguments: [],
    directives: [],
    selectionSet: {
      kind: 'SelectionSet',
      selections: [
        {
          kind: 'Field',
          name: {
            kind: 'Name',
            value: 'title',
          },
          arguments: [],
          directives: [],
        },
      ],
    },
  },
]

Auch hier, wie du siehst, ein ganz gewöhnliches JavaScript-Objekt, diesmal als Repräsentation deiner Query.

Hinweis: Im info-Objekt stecken noch mehr Leckerbissen. Mehr Infos (Wortspiel nicht beabsichtigt) findest du in diesem Artikel.

Query-Informationen nutzen

Mit diesem Wissen und dem, was du über das GraphQLSchema-Objekt weisst, kannst du ziemlich viel zaubern (einiges davon zeigen wir in kommenden Artikeln), zum Beispiel:

  • Eigene Validierungs-Decorators implementieren
  • SQL-Queries automatisch generieren
  • Daten, die weiter unten in der Query gebraucht werden, schon in einem übergeordneten Resolver vorladen (z. B. mit SQL JOINS)
  • Einen allmächtigen Root Resolver implementieren

GraphQL-Applikationen auf Enterprise-Niveau bauen

Du willst GraphQL-Profi werden? Folge uns und lies unsere ganze Serie über GraphQL-Applikationen auf Enterprise-Niveau.

Du brauchst ein Expert*innen-Team für deine anspruchsvolle Webapplikation? Wirf einen Blick in unser Portfolio.

Ein Mann mit Brille, Bart und kurzen Haaren in einem marineblauen Button-Down-Hemd und khakifarbenen Hosen steht lächelnd vor einem blauen Hintergrund.

Geschrieben von
Nicola Marcacci Rossi

Technology|April 2019

Ähnliche Challenge auf dem Tisch? Lass uns drüber reden.

Weitere Artikel

© 2026 smartive AG