Un backend web clean en NodeJS

Le but de ce "hands-on" est de réaliser un backend web complet en NodeJS de manière progressive avec des étapes simples, en essayant de produire du code moderne et de qualité et se poser les bonnes questions.

Cette matière à vocation pédagogique peut aisément servir de "boilerplate" pour des besoins variés de réalisation que ce soit pour accompagner un frontend ou une app mobile.

L'idée est de proposer un cadre simple et suffisamment évolutif pour servir de base à étendre avec vos propres besoins (bases / stores, files de message, …)

Etape 1

TODO lien Git

Projet initial

Créer le projet :

$ mkdir web-backend
$ cd web-backend
$ npm init
…
package name: (web-backend)
version: (1.0.0) 0.0.1
description: A clean web backend powered by NodeJS
entry point: (index.js) src/server.js
test command: 
git repository: 
keywords: 
license: (ISC) 
…

Pour propulser notre serveur web, plusieurs choix sont possibles :

• Express : le framework le plus connu, historique, mais qui ne supporte pas les promesses et l'instruction async ce qui nous empêche d'utiliser du code moderne
• NestJS : framework complet tout en un qui inclut beaucoup de briques et propose un cadre proche d'Angular, surdimensionné et trop structurant pour notre besoin
• Fastify : assez proche d'express en terme de fonctionnalités et positionnement, plus moderne, assez ouvert, extensible et performant

Nous partirons sur Fastify qui a le mérite d'être complètement "promisifé" et efficace pour faire des choses simples.

Mais auparavant un peu de préparation pour installer des dépendances proprement…

Préparation du projet

Ce que l'on souhaite :

• configurer npm pour sauvegarder par défaut les dépendances dans package.json
• stocker les modules npm téléchargés dans un répertoire local tmp pour ne pas polluer le scope global

On en profite aussi pour créer notre .gitignore afin d'éviter de pousser dans le référentiel des sources des fichiers qui n'ont pas vocation à l'être (temporaires, personnels ou générés).

Copier ce contenu dans ./.gitignore :

# IDE settings
/.idea/
/.npm/
/.vscode/
/*.iml

# installed NPM modules
/node_modules/

# temp files
/tmp/
.DS_Store

# log files
npm-debug.log

# local files
*.local
.env

Configurer NPM :

Créer un fichier ./.npmrc avec le contenu suivant :

cache=./.npm
engine-strict=true
save=true
save-exact=true
tag-version-prefix=""

Ajouter private: true au fichier ./package.json, pour obtenir ceci :

{
  "name": "web-backend",
  "version": "0.0.1",
  "private": true,
  "description": "A clean web backend powered by NodeJS",
…
}

Dépendances NPM

Installation de la dépendance fastify :

$ npm i fastify

Scripts NPM

Ajoutons une fonctionnalité de watch avec nodemon, bien pratique pendant les phases de mise au point pour redémarrer notre futur serveur à chaud :

$ npm i -D nodemon

On ajoute la configuration dans ./nodemon.json :

{
  "watch": [
    "package.json",
    "src",
    ".env"
  ],
  "ext": "js,json"
}

Déclarons les scripts NPM start et watch qui permettent de normaliser nos interactions avec le projet :

{
  …
    "scripts": {
    "start": "node --experimental-specifier-resolution=node src/server",
    "test": "echo \"Error: no test specified\" && exit 1",
    "watch": "nodemon --exec npm start"
  },
  …
}

On souhaite utiliser une syntaxe moderne (ECMAScript) pour profiter des instructions import / export, il faut pour cela ajouter une option dans la commande node, et déclarer le type de résolution des modules node avec module dans package.json :

{
  …
  "type": "module",
  …
}

Etape 2

Serveur "Hello"

Créer le source principal du serveur minimal ./src/server.js :

import Fastify from 'fastify'

const fastify = Fastify()

fastify.get('/', async () => ({ hello: 'world' }))

const start = async () => {
  try {
    await fastify.listen(3000)
  } catch (err) {
    fastify.log.error(err)
    process.exit(1)
  }
}

void start()

Démarrage de notre serveur :

$ npm run watch

Il est temps maintenant de tester le fonctionnement de notre serveur avec un client HTTP (cURL, Postman, ou encore httpie).

Par exemple avec httpie :

$ http :3000/
HTTP/1.1 200 OK
Connection: keep-alive
Date: Thu, 24 Mar 2022 08:50:54 GMT
Keep-Alive: timeout=5
content-length: 17
content-type: application/json; charset=utf-8

{
    "hello": "world"
}

C'est le moment de se congratuler avant de s'intéresser à l'itération suivante 😄

TODO

Etape 3

Ajouter une base Mongo

Provisionner un serveur mongodb local pour nos tests avec Docker

Ajouter les dépendances NPM

Intégration du client Mongo avec Fastify

Plugin Mongodb

Route /animals

Ajouter une configuration pour centraliser