Ceci est une ancienne révision du document !
This month marks the final Command & Conquer article I’ll be writing. For more details on why, you may want to look at last month’s article. That being said, I wanted to do something a little different for the last article. The first part of the article will be dedicated to some articles I’m most proud of having written, and the second half will be dedicated to writing a GraphQL API to track my Go games. So if you’re interested in one but not the other, you know where to jump to.
L'article Command & Conquer de ce mois sera le dernier que j'écrirai. Pour des détails supplémentaires sur les raisons de cela, vous pouvez lire l'article du mois dernier. Cela dit, je voulais faire quelque chose d'un peu différent dans ce dernier numéro. La première partie de l'article sera consacrée à quelques articles que je suis le plus fier d'avoir écrit, et l'autre moitié sera dédiée à l'écriture d'une API GraphQL pour suivre mes jeux de Go. Aussi, si vous êtes intéressé à l'un, mais pas l'autre, voous savez où aller.
Part 1 I’ve been writing for FCM since issue #21 - 131 issues ago! Over that time I’ve written some articles that are, as of now, obsolete, and some that hold up to the test of time. Below you’ll find a list of my favorite articles that I’ve written, and what issue they appeared in: • CLI Cookbook - FCM #76. I’m most proud of this one because we managed to get the community involved and actually created something together. I can’t guarantee that all the commands are still accurate, but I’m sure there are still a good few ideas that are valid. The actual PDF/LaTeX documents can be found here: https://github.com/lswest/cli-cookbook
1ère partie
J'ai écrit pour le FCM depuis ne n° 21 - il y a 131 numéros ! Pendant tout ce temps, j'ai écrit des articles qui sont, à l'heure actuelle, obsolètes, et certains qui ont supporté le passge du temps. Ci-dessous, vous trouverez une liste de mes articles préférés que j'ai écrit et dans quels numéros ils sont apparus : ••CLI Cookbook - FCM n° 76. C'est de celui là que je suis le plus fier parce que nous avons réussi à y associer la communauté pour vraiment créer quelque chose ensemble. Je ne peux pas assurer que toutes les commandes ont encore parfaites, mais je suis sûr qu'il y a encore quelques bonnes idées toujours valables. Les vrais documents PDF/LaTeX peuvent être trouvés ici : https://github.com/lswest/cli-cookbook
• Flexbox Stylus - FCM #92. This was another fun little project I wrote for myself that yielded a great article. I built a set of helper functions for Stylus to easily create/manage Flexbox settings. Not terribly useful in this day and age, but still fun. • Tailwind CSS - FCM #134. This article introduced my readers to a tool that completely changed my approach to designing and styling websites, and is a method I still use to this day. Definitely a worthwhile read to anyone who’s interested in web development.
••Flexbox Stylus - FCM n° 92. C'était un autre petit projet sympathique que j'ai écrit pour moi qui est devenu un superbe article. J'ai construit un jeu de fonctions d'aide pour Stylus pour écrire/gérer facilement les paramètres de Flexbox. Plus tellement utile aujourd'hui, mais toujours agréable. ••Tailwind CSS - FCM n° 134. Cet article présentait à mes lecteurs un outil qui avait complètement changé mon approche de concevoir et de styliser mes sites Web, et j'utilise encore cette méthode aujourd'hui. C'est vraiment quelque chose de valeur à lire par toute personne intéressée par le développement Web.
• My web development articles. I won’t list all the issues I had web development focused articles in (though there will be a few at the end of this item). The reason I’m proud of these articles is quite simple - I both enjoyed the topic, and used the knowledge in my professional life (I still do!). In writing those sorts of articles, I always hoped to make the entry into new web technologies easier for beginners. Noteworthy articles: Gatsby Multi-Language (151), AMP (127), CSS Grids (125), Static Site Generation (103). There are other articles on a wide range of topics - guitar, note taking, virtualization, etc. Unfortunately, I don’t have a complete list of articles anywhere for easy browsing. If any readers have something like that, they’re welcome to email it to me (address below).
Mes articles sur le développement Web. Je ne voudrais pas lister tous les numéros dans lesquels je me suis concentré sur le développement Web (bien qu'il y en ait quelques uns au bas de cet sujet). La raison pour laquelle je suis fier de ces articles est plutôt simple - j'ai apprécié le sujet en même temps que j'ai utilisé mes connaissances dans ma vie professionnelle (je continue encore !). En écrivant ces genres d'articles, j'ai toujours espéré rendre l'entrée dans le monde des nouvelles technologies Web plus facile pour les débutants. Des articles de valeur : Multi-langage avec Gatsby (151), AMP (127), grilles CSS (125), Génération d'un site statique (103).
Il y a d'autres articles sur une large étendue de sujets - guitare, prise de note, virtualisation, etc. Malheureusement, je n'ai pas de liste complète des articles quelque part pour une recherche aisée. Si un lecteur a quelque chose comme cela, j'apprécierai qu'il me l'envoie par mail (mon adresse ci-dessous).
Part 2 Now, on to other topics near and dear to my heart: Go & GraphQL. For anyone not familiar with Go, it’s an ancient chinese board game (estimated at over 2500 years old), played with black and white stones on a 19×19 grid. It’s also known as Baduk or Weiqi in Korea and China, respectively.
2ème partie
Et maintenant, passons à d'autres sujets qui me sont proches et chers à mon cœur : le Go et GraphQL.
Pour ceux qui ne sont pas familiers avec le Go, c'est un jeu chinois ancien sur plateau (on l'estime vieux de plus 2500 ans environ), qui se joue avec des pierres noires et blanches sur une grille de 19×19. Il est aussi appelé respectivement Baduk ou Weigi en Corée et en Chine.
GraphQL is a (much) more recent invention. It’s a query language for APIs that define a schema of data, and allow flexible querying for information. Basic example - you could define a schema for a book and an author, and keep track of things like ISBN, number of pages, publishing date, author, title, etc. Anyone who has access to the API can, using the same URL, selectively query only the data they want (i.e. title, author, and cover page) instead of getting everything back every time. It’s the backend to Gatsby’s static site generation (controlled via the gatsby-node.js file), and is extremely powerful. Ever since using it for the first time, I’ve wanted to create my own GraphQL API to replace my aging Ruby on Rails application that I use for tracking movies and video games I want to see/buy. I have since converted the information I already had (stored in a sqlite database from Rails) into mongodb, and written the API to the point where it can access and create entries in the database. Now it’s time to expand the functionality - adding in my Go games. I will not be covering the frontend aspect (planned to be a Gatsby PWA that hydrates data on load), as it’s not been completed yet, and GraphQL is flexible enough that you can access it from pretty much anything.
GraphQL est une invention (beaucoup) plus récente. C'est un langage de requête pour les API qui définit un schéma de données et permet un requêtage flexible pour des informations. Un exemple simple - vous pouvez défnir un schéma pour un livre et un auteur, et conserver la trace de choses comme l'ISBN, le nombre de pages, la date de publication, l'auteur, le titre, etc. Quiconque a accès à l'API peut, en utilisant la même URL, requérir sélectivement que les données qu'il veut (par ex., le titre, l'auteur et la page de couverture) au lieu de tout récupérer à chaque fois. C'est l'arrière-boutique de la génération de site statique avec Gatsby (pilotée via le fichier gatsby-node.js) et il est extrêmement puissant. À tel point que, quand je l'ai utilisé pour la première fois, j'ai voulu créer ma propre API GraphQL pour remplacer mon application Ruby on Rails vieillissante que j'utilise pour suivre les films et les jeux vidéos que je veux acheter. Depuis, j'ai converti les informations que j'avais déjà (conservées dans une base de données sqlite en Rails) en mongodb, et écrit l'API jusqu'au point où je peux accéder et créer des entrées dans la base de données. Maintenant, il est temps d'étendre la fonctionnalité - en y ajoutant mes jeux de Go. Je ne couvrirait pas l'aspect de présentation (prévu d'être un PWA Gatsby qui hydrate les données à charger), car il n'est pas encore terminé et GraphQL est suffisament flexible pour que vous puissiez accéder à n'importe quelle chose.
All code has been placed into a Gist here: https://gist.github.com/lswest/d2118f4fa0225b80993acb7337fdefc2 I will be linking to individual files throughout the article! So there’s no need to grab them all now.
Tout le code a été mis dans un Gist ici : https://gist.github.com/lswest/d2118f4fa0225b80993acb7337fdefc2
Au cours de l'article, je ferai le lien avec des fichiers spécifiques ! Aussi, il n'y a pas besoin de tous les récupérer pour le moment.
The Basics I set up my API using Express.js, mongoose, apollo-server, and apollo-server-express. Most aspects will remain the same regardless of implementation, but the actual connection to the database will differ. How does a GraphQL API work? You define a few schemas (think of it as a class definition) for queries, types, and mutations. Mutations are the create/update/delete aspect of CRUD, and queries are the “read” aspect. I won’t go into detail on the mutations, just a basic create function.
Les bases
J'ai paramétrémon API en utilisant Express.js, mongoose, apollo-server et apollo-server-express. La plupart des points ne changeront pas suivant l'implémentation, mais la connexion réelle à la base de données diffèrera.
Comme fonctionne l'API GraphQL ? Vous définissez quelques schémas ( voyez-les comme un définition de classe) pour les requêtes, les types et les mutations. Les mutations sont le côté créer/mettre à jour/effacer de CRUD et les requêtes sont l'aspect « lecture ». je ne rentrerai pas dans le détail des mutatons, juste une fonction créer de base.
GraphQL then takes your defined schema and uses it for validation, typing, and for understanding the requests sent to it. The schemas also control which fields from your database are available in the API. Basic folder structure: /src/models/ /src/schemas/ /src/resolvers/ /src/index.js /package.json
GraphQL prend ensuite le schéma défini et l'utilise pour la validation, le typage et pour comprendre les demandes qui lui sont envoyées. Les schémas contrôlent aussi quels sontles champs de la base de données qui sont disponibles dans l'API.
Structure de base des dossiers /src/models/ /src/schemas/ /src/resolvers/ /src/index.js /package.json
Requirements Make sure you’ve installed NodeJS (the LTS should be sufficient if you don’t want to be on the faster moving stable branch), mongodb (or your database system of choice), and have some test data prepared (for example a JSON block to import into mongodb or to hard-code into the app). To get the project up and running, you can do the following (if you prefer npm, all yarn commands have npm equivalents): yarn init yarn add -D nodemon @babel/core @babel/node @babel/preset-env
Create a .babelrc file with: { “presets”: [“@babel/preset-env”] } yarn add mongoose express graphql apollo-server apollo-server-express Add the following script to your package.json: “dev”: “nodemon –exec babel-node src/index.js” Using Compass or mongo’s CLI, be sure to create a database to store your data in if you want to use a database.
Step 1 Mongoose Schema For a mongodb implementation with mongoose, you define a mongoose.Schema (separate from the GraphQL Schema). Here you’re essentially defining the document structure to be stored/loaded from the collection(s). My Schema for Go looks like this: /src/models/goGames.js: https://gist.github.com/lswest/d2118f4fa0225b80993acb7337fdefc2#file-models-gogames-js
Basic explanation I defined fields for a ‘go’ game to include Title (i.e. Lucas VS George), the date played (currently defined as a String, as I haven’t yet figured out how to make dates work correctly), what server it was played on (KGS, IGS, FGS, online-go, etc), Black and White player names, Komi (the points given to White for going second), Result in the traditional notation - i.e. B+Res, and MyWin which tracks if I won this game (for statistics later on) - if I were to add someone else’s game, I’d simply leave this as false, and SGF. I tend to download my games’ SGF files and store them somewhere on my PC. While I won’t necessarily link them all on a web server, I can at least track the name. If I do eventually add them in as static files, I can then just update them to links.
The collection defines what I want the collection to be called in mongodb (currently, the collection does not exist - so I could have chosen anything here). You then apply the schema to a model, and export the resulting variable to use later on. Step 2 GraphQL Schema Once we’ve defined our mongodb server, we need to define our GraphQL schema. You should base the schema off your database definition, but it does not have to be a one-to-one match.
The GraphQL Schema I defined looks like this: /src/schemas/goGames.js: https://gist.github.com/lswest/d2118f4fa0225b80993acb7337fdefc2#file-schemas-gogames-js The GoGame type is a match for the mongoose Schema, and the createGoGame mutation takes pretty much all the fields.
The queries, however, are specialized. The first query (goGame) can only be filtered by ID and/or title, as it returns a single instance it makes sense to be as restrictive as possible to avoid weird results. The allGoGames query can be filtered using pretty much all fields except Komi and Result. As my goal for this API is to track my own games, I’m more likely to search for games where I was black or white, and perhaps define if it was a win or a loss. I don’t think I’ll ever search for all games where Komi was 0.5, for example. If I end up needing this, I can simply add it in as an option. Similarly, I won’t necessarily be filtering by result, as I’ll never (at that point) know which player was which. The field is important for a quick overview, but shouldn’t be very useful when filtering what I want to see. I also added a Limit field to the allGoGames, to limit the number of results returned.
Step 3 Resolvers Okay, we’ve now defined our schemas and given some thought to the options available in a query. However, until we define our resolvers, the query won’t work. A resolver is a function that defines what happens with the parameters we defined in our schema. For my Go games, it looks like this: /src/resolvers/goGames.js: https://gist.github.com/lswest/d2118f4fa0225b80993acb7337fdefc2#file-resolvers-gogames-js Admittedly, almost all my resolvers look like this, with the only difference being variable names and the models used. The goGame resolver is the simplest - I take any of the args passed through (Title or _id), and then run a findOne on the collection.
The allGoGames resolver is more complicated. I pass in all the args, including a field called Limit. The idea behind ‘limit’ is to set a maximum number of results (ie. if I want a top 10). As this field doesn’t exist in the mongodb document, it will never yield results if it’s just passed in that way. Instead, I check if args has a property ‘Limit’. If it does, I create a copy of the object and delete the ‘Limit’ property. I then adjust the mongodb command to pass in the remaining arguments and use args.Limit in the .limit() function. If args.Limit doesn’t exist, I just run a find() on all the args. The createGoGame resolver takes all the arguments I specified in the GraphQL Schema. However, it also needs an id. Instead of forcing the user or client to generate one, I instead add an _id field to the object using mongoose.Types.ObjectId() before creating the item.
Step 4 - Putting it all together The first thing I would recommend you do is create an index.js file in both /src/schemas and /src/resolvers. This file will serve as an aggregator for all your schemas and resolvers once you have more than one. /src/schemas/index.js: https://gist.github.com/lswest/d2118f4fa0225b80993acb7337fdefc2#file-schemas-index-js /src/resolvers/index.js: https://gist.github.com/lswest/d2118f4fa0225b80993acb7337fdefc2#file-resolvers-index-js
Now for the heart of the server: /src/index.js: https://gist.github.com/lswest/d2118f4fa0225b80993acb7337fdefc2#file-src-index-js Be sure to replace {MONGO_URL} with your actual mongodb connection string (most likely mongodb:localhost:27017/{database}), where {database} is whatever database name you defined manually in step 1. Step 5 - Trying it out Once you’ve started the server with yarn dev, the server should be running on localhost:5000. However, the root doesn’t return anything as we only defined the path “/graphql”. So head on over to http://localhost:5000/graphql and have a play around on your graphiql instance. To create items: mutation { createGoGame(Title:“Example”,PlayedDate:“2019-12-06”,Server:“Fox”,Black:“Player1”,White:“Player2”,Komi:“7.5”,Result:“B+Res”,MyWin:false,SGF:“2019-12-06 - example.sgf”) { _id } } The above will generate an entry and return the id for you to use in a goGame query. To query items: { goGame(_id: “id from above”) { Title } } To see them all, you can also run: { allGoGames { Title } } So, I hope this last article has gotten you enthused for GraphQL. To all my avid readers - thank you for your time and interest over these years! As always, if you want to send me a message you can reach me at lswest34+fcm@gmail.com. Especially if you happen to have a good list of my articles and what issues they appeared in!**