Das Erlernen des Erstellens von GraphQL-APIs kann recht herausfordernd sein. Aber du kannst in 10 Minuten lernen, wie man GraphQL-APIs *benutzt*! Und zufällig habe ich die perfekte API dafür: die brandneue, frisch aus dem VS-Code stammende State of JavaScript GraphQL API.
Die State of JavaScript-Umfrage ist eine jährliche Umfrage zur JavaScript-Landschaft. Wir führen sie seit vier Jahren durch, und die jüngste Ausgabe erreichte über 20.000 Entwickler.
Wir haben uns immer auf Gatsby verlassen, um unsere Showcase-Website zu erstellen, aber bis dieses Jahr haben wir unsere Daten in Form von statischen YAML-Dateien an Gatsby übergeben, die durch eine Art archaische Magie generiert wurden, die Sterblichen als „ElasticSearch“ bekannt ist.
Da Gatsby jedoch sowieso alle Datenquellen, die es verarbeitet, als GraphQL ausgibt, dachten wir, wir könnten die Zwischenstation überspringen und es direkt mit GraphQL füttern! Ja, ich weiß, diese Metapher wird mit jeder Sekunde ekelhafter und ich bereue es bereits. Mein Punkt ist: Wir haben eine interne GraphQL-API für unsere Daten erstellt und stellen sie jetzt jedem zur Verfügung, damit auch Sie unsere Datensätze einfach ausbeuten können!
„Aber halt“, sagen Sie. „Ich habe mein ganzes Leben damit verbracht, das Schwert zu studieren, was mir keine Zeit ließ, GraphQL zu lernen!“ Keine Sorge: Dafür ist dieser Artikel da.
Was ist GraphQL?
Im Wesentlichen ist GraphQL eine Syntax, mit der Sie angeben können, welche Daten Sie von einer API erhalten möchten. Beachten Sie, dass ich *API* und nicht Datenbank gesagt habe. Im Gegensatz zu SQL geht eine GraphQL-Abfrage nicht direkt an Ihre Datenbank, sondern an Ihren GraphQL-API-Endpunkt, der wiederum eine Verbindung zu einer Datenbank oder einer anderen Datenquelle herstellen kann.
Der große Vorteil von GraphQL gegenüber älteren Paradigmen wie REST ist, dass Sie anfordern können, was Sie wollen. Zum Beispiel
query {
user(id: "foo123") {
name
}
}würde Ihnen ein Benutzerobjekt mit einem einzigen name-Feld liefern. Brauchen Sie auch die E-Mail? Tun Sie einfach
query {
user(id: "foo123") {
name
email
}
}Wie Sie sehen, unterstützt das Benutzerfeld in diesem Beispiel ein id-Argument. Und jetzt kommen wir zur coolsten Funktion von GraphQL, dem Nesting
query {
user(id: "foo123") {
name
email
posts {
title
body
}
}
}Hier sagen wir, dass wir die posts des Benutzers finden und deren title und body laden möchten. Das Schöne an GraphQL ist, dass unsere API-Schicht die Arbeit leisten kann, herauszufinden, wie diese zusätzlichen Informationen in diesem spezifischen Format abgerufen werden, da wir nicht direkt mit der Datenbank sprechen, auch wenn sie in unserer tatsächlichen Datenbank nicht verschachtelt gespeichert ist.
Sebastian Scholl erklärt GraphQL auf wunderbare Weise, als ob Sie ihn zum ersten Mal auf einer Cocktailparty treffen würden.
GraphiQL vorstellen
GraphiQL (beachten Sie das „i“ darin) ist die gängigste GraphQL-IDE, und es ist das Werkzeug, mit dem wir die State of JavaScript API erkunden werden. Sie können sie jetzt unter graphiql.stateofjs.com starten, und sie wird automatisch eine Verbindung zu unserem Endpunkt herstellen (der api.stateofjs.com/graphql ist). Die Benutzeroberfläche besteht aus drei Hauptelementen: dem Explorer-Panel, dem Query Builder und den Ergebnis-Panels. Wir werden später das Docs-Panel hinzufügen, aber halten wir es vorerst einfach.
Der Explorer-Tab ist Teil einer Turbo-Version von GraphiQL, die von OneGraph entwickelt und gepflegt wird. Vielen Dank an sie für ihre Hilfe bei der Integration. Schauen Sie sich unbedingt ihr Beispiel-Repo an, wenn Sie Ihre eigene GraphiQL-Instanz bereitstellen möchten.
Keine Sorge, ich werde Sie noch nicht zum Schreiben von Code zwingen. Beginnen wir stattdessen mit einer vorhandenen GraphQL-Abfrage, wie z. B. der, die sich auf die Entwicklererfahrung mit React in den letzten vier Jahren bezieht.
Erinnern Sie sich, wie ich sagte, dass wir GraphQL intern zum Erstellen unserer Website verwendet haben? Wir stellen nicht nur die API zur Verfügung, sondern auch die Abfragen selbst. Klicken Sie auf den kleinen „Export“-Button, kopieren Sie die Abfrage im „GraphQL“-Tab, fügen Sie sie in das Query Builder-Fenster von GraphiQL ein und klicken Sie auf den „Play“-Button.
Wenn alles nach Plan lief, sollten Ihre Daten im Ergebnis-Panel erscheinen. Nehmen wir uns einen Moment Zeit, um die Abfrage zu analysieren.
query react_experienceQuery {
survey(survey: js) {
tool(id: react) {
id
entity {
homepage
name
github {
url
}
}
experience {
allYears {
year
total
completion {
count
percentage
}
awarenessInterestSatisfaction {
awareness
interest
satisfaction
}
buckets {
id
count
percentage
}
}
}
}
}
}Zuerst kommt das query-Schlüsselwort, das den Beginn unserer GraphQL-Abfrage definiert, zusammen mit dem Namen der Abfrage, react_experienceQuery. Abfragenamen sind in GraphQL optional, können aber für Debugging-Zwecke nützlich sein.
Dann haben wir unser erstes Feld, survey, das ein survey-Argument annimmt. (Wir haben auch eine State of CSS-Umfrage, daher mussten wir die betreffende Umfrage angeben.) Dann haben wir ein tool-Feld, das ein id-Argument annimmt. Und alles danach bezieht sich auf die API-Ergebnisse für dieses spezifische Werkzeug. entity gibt Ihnen Informationen über das ausgewählte Werkzeug (z. B. React) und experience enthält die tatsächlichen statistischen Daten.
Nun, anstatt hier weiter durch all diese Felder zu gehen, werde ich Ihnen einen kleinen Trick beibringen: Drücken Sie Command + Klick (oder Control + Klick) auf eines dieser Felder in GraphiQL, und es wird das Docs-Panel geöffnet. Glückwunsch, Sie haben gerade einen weiteren der pfiffigen Tricks von GraphQL miterlebt, die Selbst-Dokumentation! Sie können Dokumentation direkt in Ihre API-Definition schreiben, und GraphiQL macht sie dann für Endbenutzer verfügbar.
Variablen ändern
Lassen Sie uns die Dinge ein wenig anpassen: Ersetzen Sie im Query Builder „react“ durch „vuejs“ und Sie werden eine weitere coole GraphQL-Sache bemerken: Autovervollständigung. Das ist sehr hilfreich, um Fehler zu vermeiden oder Zeit zu sparen! Drücken Sie erneut „Play“, und Sie erhalten dieselben Daten, aber diesmal für Vue.
Den Explorer nutzen
Wir werden nun ein weiteres GraphQL-Mächtigkeitswerkzeug freischalten: den Explorer. Der Explorer ist im Grunde ein Baum Ihrer gesamten API, der es Ihnen nicht nur ermöglicht, seine Struktur zu visualisieren, sondern auch Abfragen zu erstellen, ohne eine einzige Zeile Code zu schreiben! Versuchen wir also, unsere React-Abfrage diesmal mit dem Explorer nachzubilden.
Öffnen Sie zuerst einen neuen Browser-Tab und laden Sie graphiql.stateofjs.com darin, um frisch zu beginnen. Klicken Sie auf den survey-Knoten im Explorer, und darunter auf den tool-Knoten, und klicken Sie auf „Play“. Das id-Feld des Werkzeugs sollte automatisch zu den Ergebnissen hinzugefügt werden und – übrigens – dies ist ein guter Zeitpunkt, um den Standardargumentwert („typescript“) in „react“ zu ändern.
Als nächstes bohren wir weiter. Wenn Sie entity ohne Unterfelder hinzufügen, sollten Sie eine kleine rote Wellenlinie darunter sehen, die Ihnen mitteilt, dass Sie mindestens ein oder mehrere Unterfelder angeben müssen. Fügen wir also id, name und homepage als Minimum hinzu. Ein weiterer nützlicher Trick: Sie können GraphiQL automatisch anweisen, alle Unterfelder eines Feldes hinzuzufügen, indem Sie es im Explorer mit Option+Control+Klick auswählen.
Als Nächstes kommt experience. Fügen Sie weiterhin Felder und Unterfelder hinzu, bis Sie etwas erhalten, das der ursprünglichen Abfrage, die Sie von der State of JavaScript-Website kopiert haben, nahekommt. Jedes ausgewählte Element wird sofort im Query Builder-Panel angezeigt. Da haben Sie es, Sie haben gerade Ihre erste GraphQL-Abfrage geschrieben!
Daten filtern
Sie haben vielleicht einen violetten filters-Eintrag unter experience bemerkt. Dies ist eigentlich der Hauptgrund, warum Sie unsere GraphQL-API nutzen sollten, im Gegensatz zum bloßen Durchsuchen unserer Website: Jede vom API bereitgestellte Aggregation kann nach einer Reihe von Faktoren gefiltert werden, wie z. B. Geschlecht des Befragten, Unternehmensgröße, Gehalt oder Land.
Erweitern Sie filters und wählen Sie companySize und dann eq und range_more_than_1000. Sie haben gerade die Popularität von React bei großen Unternehmen berechnet! Wählen Sie stattdessen range_1 und Sie können sie nun mit denselben Datenpunkten bei Freiberuflern und unabhängigen Entwicklern vergleichen.
Es ist wichtig zu beachten, dass GraphQL nur sehr low-level Primitive definiert, wie z. B. Felder und Argumente, daher sind diese eq, in, nin, usw. Filter nicht Teil von GraphQL selbst, sondern einfach Argumente, die wir selbst bei der Einrichtung der API definiert haben. Das kann anfangs viel Arbeit sein, gibt Ihnen aber die volle Kontrolle darüber, wie Clients Ihre API abfragen können.
Fazit
Hoffentlich haben Sie gesehen, dass das Abfragen einer GraphQL-API keine große Sache ist, besonders mit fantastischen Werkzeugen wie GraphiQL, die Ihnen dabei helfen. Nun, die Integration von GraphQL-Daten in eine reale Anwendung ist eine andere Sache, aber das liegt hauptsächlich an der Komplexität der Datenübertragung zwischen Client und Server. Der GraphQL-Teil selbst ist eigentlich ganz einfach!
Egal, ob Sie mit GraphQL beginnen möchten oder nur genug lernen wollen, um unsere Daten abzufragen und einige erstaunliche neue Erkenntnisse zu gewinnen, ich hoffe, dieser Leitfaden war nützlich!
Und wenn Sie an unserer nächsten Umfrage teilnehmen möchten (die die State of CSS 2020 sein wird), dann melden Sie sich unbedingt für unseren Mailingliste an, damit Sie benachrichtigt werden, wenn wir sie starten.
State of JavaScript API Referenz
Weitere Informationen zur API (einschließlich Links zum tatsächlichen Endpunkt und zum GitHub-Repository) finden Sie unter api.stateofjs.com.
Hier ist ein kurzes Glossar der im State of JS API verwendeten Begriffe.
Top-Level-Felder
- Demographics: Fasst alle demografischen Informationen wie Geschlecht, Unternehmensgröße, Gehalt usw. zusammen.
- Entity: Bietet Zugriff auf weitere Informationen über eine bestimmte „Entität“ (Bibliothek, Framework, Programmiersprache usw.).
- Feature: Nutzungsdaten für ein bestimmtes JavaScript- oder CSS-Feature.
- Features: Dasselbe, aber über eine Reihe von Features.
- Matrices: Bietet Zugriff auf die Daten, die zur Erstellung unserer kreuzreferenziellen Heatmaps verwendet werden.
- Opinion: Meinungsdaten für eine bestimmte Frage (z. B. „Glauben Sie, dass sich JavaScript in die richtige Richtung entwickelt?“).
- OtherTools: Daten für den Abschnitt „Andere Werkzeuge“ (Texteditoren, Browser, Bundler usw.).
- Resources: Daten für den Abschnitt „Ressourcen“ (Websites, Blogs, Podcasts usw.).
- Tool: Erfahrungsdaten für ein bestimmtes Werkzeug (Bibliothek, Framework usw.).
- Tools: Dasselbe, aber über eine Reihe von Werkzeugen.
- ToolsRankings: Rankings (Bekanntheit, Interesse, Zufriedenheit) über eine Reihe von Werkzeugen.
Gemeinsame Felder
- Completion: Welcher Anteil der Umfrageteilnehmer hat eine bestimmte Frage beantwortet.
- Buckets: Das Array, das die tatsächlichen Daten enthält.
- Year/allYears: Ob die Daten für ein bestimmtes Umfragejahr abgerufen werden sollen; oder ein Array, das alle Jahre enthält.
Aber welche Datenbank soll ich in der React-App verwenden? Ich habe es geschafft, eine statische Anwendung mit React JS zu erstellen, möchte sie aber dynamisch fortsetzen. Können Sie eine Datenbank vorschlagen, die ich dafür verwenden kann? Funktioniert SQL mit JS? (Weil ich weiß, wie man es codiert)