Foto von Sebastian Unrau auf Unsplash

So entwerfen Sie GraphQL-Abfragen und -Mutationen: benutzerdefinierter Skalar

Im ersten Teil dieser Serie haben wir die verschiedenen in der GraphQL-Spezifikation verfügbaren eingebauten Skalare erörtert. Im zweiten Teil sind wir zu Enums übergegangen. Im letzten Teil dieser Reihe werden wir auf Skalare zurückkommen. Wir werden uns jedoch auf die sogenannten „benutzerdefinierten Skalare“ konzentrieren. Wir werden zuerst den Modellskalar für DateTime definieren, dann die Aufgabendefinition für die Felder createdAt und updatedAt erweitern, die im Grunde Zeitstempel für jede neue Aufgabe sind.

Testen Sie den bevorstehenden kostenlosen GraphQL-Sprachkurs mit in-Browser-Übungen
Aus dem kommenden GraphQL-Sprachkurs

Einführung

Wie wir in diesem Artikel besprochen haben, haben wir in der GraphQL-Spezifikation verschiedene eingebaute Skalartypen. Aber was können wir tun, wenn wir Skalare verwenden müssen, die nicht in der GraphQL-Spezifikation definiert sind? Die Antwort ist, den sogenannten "benutzerdefinierten Skalar" zu verwenden. Wie in den vorherigen Artikeln werden wir graphql-js verwenden. Die Implementierung des benutzerdefinierten GraphQL-Skalars kann in anderen GraphQL-Implementierungen variieren. In einigen dieser Implementierungen können möglicherweise nicht einmal benutzerdefinierte Skalare verwendet werden.

Wir werden mit demselben Repository fortfahren wie mit den Aufzählungen und den eingebauten Skalaren. Mit diesem Befehl können Sie das GitHub-Repository klonen

git clone https://github.com/a7v8x/express-graphql-demo.git -b feature / 3-graphql-scalars

Benutzerdefinierte Skalardefinition

Kommen wir nun zum Entwerfen des DateTime-Skalars. Wir werden validator js library verwenden, um zu testen, ob der Wert im ISO8601-Format für Datum und Uhrzeit vorliegt. Die vereinfachte Definition des DateTime-Skalars kann wie folgt lauten

In graphql-js hat jede benutzerdefinierte Skalartypdefinition unterschiedliche Felder und Methoden, die definiert werden sollten. Genau wie bei Eingabe- / Ausgabeobjekttypen müssen wir den erforderlichen Feldnamen des Skalars definieren. Das Beschreibungsfeld ist wieder obligatorisch. Wenn Sie den Artikel über eingebaute Skalare lesen, haben wir die Eingabe und den Ergebniszwang für jeden Typ durchlaufen. Dies ist in der graphql-js-Bibliothek für eingebaute Skalare definiert. Wenn wir jedoch unseren eigenen benutzerdefinierten Skalar definieren, müssen wir diese Regeln angeben. Aus diesem Grund müssen wir für jeden benutzerdefinierten Skalar einige Methoden definieren. Diese sind:

  • serialisieren

Die Serialisierungsfunktion bezieht sich auf den Ergebniszwang. Das erste Argument für diese Funktion ist der empfangene Wert. In unserem Fall möchten wir überprüfen, ob der Wert im ISO8601-Datumsformat vorliegt. Wenn der empfangene Wert die Validierung besteht, möchten wir diesen Wert zurückgeben. Andernfalls würden wir den GraphQL-Fehler auslösen.

  • parseValue, parseLiteral

Die Funktionen parseValue und parseLiteral beziehen sich auf den Eingabezwang. Der Unterschied besteht darin, dass wir in parseValue auf die mit den Variablen übergebene Eingabe verweisen. Wenn wir parseValue verwenden, ist das erste Argument dieser Funktion der Wert selbst. Auf der anderen Seite hat die parseLiteral-Funktion als erstes Argument den ast-Wert im folgenden Format

Deshalb müssen wir den Wert aus der ast-Variablen extrahieren und ihn erneut anhand unserer Regeln validieren.

Implementierung

Wir haben die Definition unseres benutzerdefinierten Skalars abgeschlossen und können ihn daher im Schema implementieren. Wir wenden es auf die Zeitstempelfelder createdAt und updatedAt an. Wir können einfach unseren Datum / Uhrzeit-Skalar importieren und ihn als Typ für diese Felder verwenden.

Überprüfen wir nun, ob unsere definierten Regeln wie erwartet funktionieren. Gehen Sie einfach zu / graphiql und versuchen Sie, die grundlegende getTasks-Abfrage aufzurufen:

Wenn unser benutzerdefinierter Skalar für Datum und Uhrzeit korrekt implementiert ist, sollten Sie Folgendes erhalten:

Testen wir nun unsere Serialisierungsfunktion. Wechseln Sie einfach zur Datei taskDb.js und weisen Sie createdAt oder updatedAt einer Zeichenfolge zu, die nicht im ISO8601-Datumsformat vorliegt. Ich ändere das Feld createdAt in 2017–10–06T14: 54: 54 + 0. Wenn wir nun versuchen, die getTasks-Abfrage aufzurufen, wird der GraphQL-Server den folgenden Fehler auslösen:

Zusammenfassung

Benutzerdefinierte Skalare bieten einen noch größeren Vorteil, wenn wir eine Sammlung unserer vordefinierten benutzerdefinierten Skalare haben. Dann können wir die meisten unserer benutzerdefinierten Validierungen zentralisieren und sie von unseren Resolverfunktionen auf unsere benutzerdefinierten Skalartypen verschieben. Unser einfacher Skalar für Datum und Uhrzeit war ein hervorragendes Beispiel für ein Modell. Wenn Sie jedoch komplexere Skalare wie JSON oder genauer definierte Skalare für Datum und Uhrzeit usw. verwenden möchten, können Sie einige der Open-Source-npm-Pakete verwenden. Diese schließen ein:

  • JSON: Verwenden von JSON als Skalar https://github.com/taion/graphql-type-json.
  • Date Time: Dies ist eine Bibliothek, die Sie für einen genau definierten Date Time-Skalar verwenden können. In dieser Bibliothek sind auch separate Zeit- und Datumsskalare verfügbar: https://github.com/excitement-engineer/graphql-iso-date.
  • Datum Uhrzeit und E-Mail: Dieses Paket ist eine kleine Sammlung benutzerdefinierter Skalare https://github.com/adriano-di-giovanni/graphql-scalars.

Selbst wenn es einige benutzerdefinierte Skalare gibt, die als Open Source veröffentlicht werden. Es gibt nur einige von ihnen. Wenn Sie gute Tipps zu benutzerdefinierten Skalardefinitionen haben, können Sie diese im Kommentarbereich weiter unten veröffentlichen.

Hat dir dieser Beitrag gefallen? Dann klatschen Sie für diesen Artikel, da es für andere leichter ist, ihn zu finden. Das Repository mit den Beispielen und dem Projekt-Setup kann von diesem GitHub-Zweig geklont werden. Sie können frühzeitig auf den bevorstehenden kostenlosen GraphQL-Kurs zugreifen, indem Sie sich bei graphqlmastery.com anmelden.