Guide

Fastify, le schéma comme source de vérité dans une API

Fastify est un framework Node où un schéma JSON valide l'entrée, sérialise la sortie et génère l'OpenAPI. Plugins, hooks, Zod, version 5 et comparaison avec Express.

L'équipe CodeWorlds19 min de lecture ·

Pratique HTML et CSS dans des leçons interactives avec un éditeur de code.

Crée un compte gratuit→
Dans cet article9

Fastify est un framework web Node dans lequel une description des données écrite sous forme de schéma JSON sert trois usages à la fois : elle valide l'entrée, construit la fonction qui sérialise la sortie et devient la documentation OpenAPI. La version actuelle est la 5.12.1, sortie le 18 août 2026, la licence est MIT, et le paquet embarque quinze dépendances de production.

Ce que fait réellement Fastify

Le framework est un ensemble de bibliothèques indépendantes reliées par une interface commune, et connaître ce découpage aide beaucoup à diagnostiquer les problèmes.

Le routage est assuré par find-my-way, un arbre de préfixes qui fait correspondre un chemin sans parcourir une liste d'expressions régulières. La validation s'appuie sur AJV, branché via @fastify/ajv-compiler, qui compile chaque schéma en une fonction de vérification une seule fois, au démarrage du serveur. La sérialisation des réponses est faite par fast-json-stringify, qui génère une fonction spécialisée à partir du schéma de réponse au lieu d'appeler JSON.stringify. Les logs passent par pino. L'ordre de chargement des plugins est piloté par avvio. Les tests sans ouvrir de socket réseau sont rendus possibles par light-my-request, exposé comme la méthode app.inject.

Cette composition explique d'où vient la différence avec Express. Dans Express, chacune de ces choses est une décision séparée : la validation s'ajoute comme middleware, la sérialisation est le JSON.stringify par défaut, et la documentation vit dans un fichier YAML distinct qui cesse de correspondre au code en une semaine. Dans Fastify, les trois sortent du même objet schema attaché à la route.

Ce que Fastify ne fait pas compte tout autant. Il n'a pas de couche d'accès aux données, donc les requêtes s'écrivent avec Prisma ou n'importe quel autre driver. Il ne rend pas d'interface, car c'est le terrain de Next.js. Il ne génère pas de client typé pour le navigateur à partir de la définition du serveur, ce que fait tRPC. Il n'impose ni structure de répertoires ni injection de dépendances, contrairement à NestJS, qui peut d'ailleurs utiliser Fastify comme couche de transport.

Version, licence et santé du projet

Le registre npm indique la version 5.12.1 du paquet fastify, publiée le 18 août 2026, et le nombre total de versions a dépassé trois cent vingt. Des versions mineures sortent régulièrement, ce qui, à la version majeure cinq, désigne un projet en maintenance et en amélioration progressive plutôt qu'en réécriture.

La licence est un cas exemplaire et il n'y a rien à démêler ici. Le fichier LICENSE du dépôt porte le texte MIT avec la mention « Copyright (c) 2016-present The Fastify team ». Le champ license du registre npm indique MIT. L'archive publiée fastify-5.12.1.tgz contient un fichier LICENSE à côté du code, si bien qu'une installation sans accès à GitHub dépose tout de même le texte complet de la licence sur le disque. Trois sources, une seule réponse. Les plugins officiels de l'espace de noms @fastify vérifiés pendant la rédaction de ce texte, à savoir cors, helmet, rate-limit, swagger, swagger-ui, under-pressure et autoload, déclarent aussi MIT, de même que fastify-plugin et fastify-type-provider-zod.

Un détail des métadonnées mérite l'attention, car il induit en erreur. Le package.json de la version 5.12.1 ne contient aucun champ engines. Un gestionnaire de paquets ne vous avertira donc pas lors de l'installation sur un Node obsolète, et le problème n'apparaît qu'à l'exécution. Vous devez surveiller vous-même la version du runtime, par exemple avec .nvmrc et une vérification dans le pipeline d'intégration continue.

Le modèle de maintenance est énoncé ouvertement. Le paquet publié contient les fichiers GOVERNANCE.md, PROJECT_CHARTER.md, SECURITY.md et SPONSORS.md, donc le projet dispose de règles écrites pour prendre des décisions et d'une voie pour signaler les vulnérabilités. Il n'y a pas de variante payante ni de contrat de support commercial. C'est un arrangement typique du logiciel open source et il comporte le risque habituel : le rythme des corrections dépend de la disponibilité de bénévoles plutôt que d'une obligation que vous pouvez faire valoir.

Installation et premier serveur

Entrer dans un projet prend quelques minutes, et la plupart des décisions de configuration se prennent à la création de l'instance.

Bash
# the framework core
npm install fastify

# the helper for plugins shared between contexts
npm install fastify-plugin

# common production add-ons
npm install @fastify/cors @fastify/helmet @fastify/rate-limit

# generating and exposing OpenAPI documentation
npm install @fastify/swagger @fastify/swagger-ui

L'instance est créée par une fonction fabrique, et les options passées à ce moment s'appliquent à tout le serveur.

TypeScript
import Fastify from 'fastify'

const app = Fastify({
  logger: { level: 'info' },
  bodyLimit: 1048576,
  requestIdHeader: 'x-request-id',
  disableRequestLogging: false,
  caseSensitive: true,
  ignoreTrailingSlash: false,
  maxParamLength: 200,
  pluginTimeout: 10000,
  connectionTimeout: 15000,
  keepAliveTimeout: 72000,
  forceCloseConnections: 'idle',
  trustProxy: true,
  ajv: {
    customOptions: {
      removeAdditional: 'all',
      coerceTypes: 'array',
      useDefaults: true,
      allErrors: false
    }
  }
})

app.get('/health', async () => ({ status: 'ok' }))

await app.listen({ port: 3000, host: '0.0.0.0' })

Plusieurs de ces champs ont des conséquences peu évidentes. Activer trustProxy permet de lire l'en-tête x-forwarded-for, ce qui est nécessaire derrière un reverse proxy et dangereux quand le serveur est directement exposé au réseau. La valeur 'idle' pour forceCloseConnections fait que app.close() ferme les connexions keep-alive inactives, sans quoi l'arrêt du processus peut rester bloqué jusqu'à l'expiration de keepAliveTimeout. Le champ pluginTimeout plafonne le temps de chargement d'un plugin et c'est une cause fréquente du message de démarrage lent quand un plugin attend une connexion à une base de données.

Les options removeAdditional, coerceTypes et useDefaults sont des réglages d'AJV passés par ajv.customOptions. La première supprime les champs absents du schéma, la deuxième convertit les types, si bien qu'un nombre arrivant dans la query string cesse d'être une chaîne, et la troisième remplit les valeurs par défaut déclarées dans le schéma. Le paquet ajv-formats est une dépendance de @fastify/ajv-compiler, donc le mot-clé format fonctionne sans installation supplémentaire.

Le schéma comme source de vérité

C'est la vraie raison pour laquelle on choisit Fastify. Un seul objet décrit le contrat de la route, et trois comportements d'exécution distincts découlent de cette description.

TypeScript
app.post('/invoices', {
  schema: {
    tags: ['invoices'],
    body: {
      type: 'object',
      required: ['customerId', 'amount'],
      additionalProperties: false,
      properties: {
        customerId: { type: 'string', format: 'uuid' },
        amount: { type: 'integer', minimum: 1 },
        currency: { type: 'string', enum: ['PLN', 'EUR'], default: 'PLN' },
        note: { type: 'string', maxLength: 500 }
      }
    },
    querystring: {
      type: 'object',
      properties: {
        dryRun: { type: 'boolean', default: false }
      }
    },
    response: {
      201: {
        type: 'object',
        properties: {
          id: { type: 'string' },
          amount: { type: 'integer' },
          currency: { type: 'string' },
          createdAt: { type: 'string' }
        }
      },
      422: {
        type: 'object',
        properties: {
          error: { type: 'string' },
          detail: { type: 'string' }
        }
      }
    }
  }
}, async (request, reply) => {
  const invoice = await app.db.invoice.create({ data: request.body })
  return reply.code(201).send(invoice)
})

La section body rejette une requête dont un champ manque ou dont le montant est négatif avant même que la fonction handler ne s'exécute. La section querystring transforme la chaîne "true" en booléen. La section response est celle qui surprend le plus souvent, car elle ne valide pas la sortie. Fastify en compile une fonction de sérialisation, et tout ce qui est absent du schéma n'atteint tout simplement pas la réponse. Cela fonctionne comme un garde-fou contre la fuite de champs que vous ne voulez pas exposer et, en même temps, comme un piège : un champ taxId ajouté dans la base n'apparaîtra pas dans le JSON tant que vous ne l'aurez pas ajouté au schéma, et aucune erreur ne vous le dit.

Les schémas répétés s'enregistrent une fois et se référencent via $ref, ce qui raccourcit les définitions de routes et garde le contrat à un seul endroit.

TypeScript
app.addSchema({
  $id: 'money',
  type: 'object',
  properties: {
    amount: { type: 'integer' },
    currency: { type: 'string', enum: ['PLN', 'EUR'] }
  }
})

app.get('/invoices/:id/total', {
  schema: {
    params: {
      type: 'object',
      properties: { id: { type: 'string' } }
    },
    response: { 200: { $ref: 'money#' } }
  }
}, async (request) => calculateTotal(request.params.id))

Écrire des schémas JSON à la main est fatigant, surtout quand les mêmes formes existent déjà sous forme de types TypeScript. La réponse est un type provider, qui remplace les compilateurs de validation et de sérialisation et boucle au passage l'inférence de types pour request.body.

TypeScript
import { z } from 'zod'
import {
  validatorCompiler,
  serializerCompiler,
  type ZodTypeProvider
} from 'fastify-type-provider-zod'

app.setValidatorCompiler(validatorCompiler)
app.setSerializerCompiler(serializerCompiler)

const typed = app.withTypeProvider<ZodTypeProvider>()

typed.post('/customers', {
  schema: {
    body: z.object({
      email: z.email(),
      plan: z.enum(['free', 'team'])
    }),
    response: {
      201: z.object({ id: z.string(), email: z.email() })
    }
  }
}, async (request, reply) => {
  const customer = await createCustomer(request.body)
  return reply.code(201).send(customer)
})

Le paquet fastify-type-provider-zod en version 7.0.0 exige Zod en 4.1.5 ou plus récent et Fastify à partir de la ligne 5.5, et il liste aussi @fastify/swagger comme dépendance pair. Cela découle directement de l'intention : le même schéma Zod doit produire à la fois la validation et l'entrée de documentation.

Le troisième rôle du schéma est OpenAPI. Le plugin @fastify/swagger collecte les schémas de chaque route enregistrée et en construit un document, tandis que @fastify/swagger-ui le sert à l'adresse de votre choix.

TypeScript
await app.register(import('@fastify/swagger'), {
  openapi: {
    info: { title: 'Billing API', version: '1.4.0' },
    servers: [{ url: 'https://api.example.com' }]
  },
  hideUntagged: true
})

await app.register(import('@fastify/swagger-ui'), {
  routePrefix: '/docs',
  uiConfig: { docExpansion: 'list', deepLinking: true },
  staticCSP: true
})

L'option hideUntagged ignore les routes sans champ tags, une façon pratique de garder les health checks et les routes internes hors de la documentation publique. Le plugin fonctionne en mode dynamic, c'est-à-dire qu'il lit l'état du serveur plutôt qu'un fichier séparé, donc la documentation ne peut pas dériver du code tant que les schémas sont complets.

L'encapsulation des plugins et son prix

Le second pilier de Fastify est moins évident, et il explique la plupart des questions de débutants. Appeler app.register n'ajoute rien à un espace partagé ; cela crée à la place un nouveau contexte enfant. Les décorateurs, hooks et schémas enregistrés dans ce contexte sont visibles pour ses enfants, mais pas pour ses frères ni pour son parent.

TypeScript
import fp from 'fastify-plugin'
import type { FastifyInstance } from 'fastify'
import { PrismaClient } from '@prisma/client'

async function databasePlugin(app: FastifyInstance) {
  const prisma = new PrismaClient()
  await prisma.$connect()

  app.decorate('db', prisma)
  app.addHook('onClose', async () => {
    await prisma.$disconnect()
  })
}

export default fp(databasePlugin, {
  name: 'db',
  fastify: '5.x'
})

La fonction fp du paquet fastify-plugin enveloppe un plugin de façon que son contenu échappe au contexte et devienne disponible pour ses frères. Les métadonnées qu'elle accepte sont concrètes : name définit le nom visible dans l'arbre des plugins et dans les messages d'erreur, fastify déclare une plage de versions du framework prise en charge, dependencies liste les noms des plugins qui doivent se charger d'abord, decorators indique les décorateurs requis dans l'environnement, et encapsulate permet d'inverser le comportement et de conserver l'encapsulation malgré l'usage de fp.

La règle pratique est simple. Un plugin qui fournit une ressource partagée, c'est-à-dire une connexion de base de données, un client de cache ou un vérificateur de tokens, passe par fp. Un plugin qui contient des routes et des hooks propres à un domaine n'a pas besoin de fp et vaut mieux rester fermé.

TypeScript
async function invoiceRoutes(app: FastifyInstance) {
  app.decorateRequest('actor', null)

  app.addHook('preHandler', async (request) => {
    request.actor = await resolveActor(request.headers.authorization)
  })

  app.get('/invoices', async (request) => app.db.invoice.findMany())
}

app.register(databasePlugin)
app.register(invoiceRoutes, { prefix: '/api/v1' })
app.register(publicRoutes, { prefix: '/public' })

await app.ready()
console.log(app.printRoutes())
console.log(app.printPlugins())

Le hook preHandler enregistré dans invoiceRoutes ne s'applique que dans ce contexte. Les routes de publicRoutes ne le verront jamais, même si les deux plugins sont accrochés au même parent. Le même principe régit l'authentification, et c'est la façon la plus sensée de séparer la partie protégée de la partie publique : pas de tableau de chemins exemptés, pas de vérification de préfixe dans un middleware.

Venons-en au coût, car l'encapsulation est autant un inconvénient qu'un avantage. Le message sur un décorateur manquant n'arrive qu'à l'exécution et dit seulement qu'une propriété est indéfinie, pas que vous avez oublié fp. L'ordre d'enregistrement compte, donc un plugin qui lit un décorateur ajouté par un autre plugin doit le déclarer via dependencies, sinon le résultat dépend de l'ordre dans le fichier. Les méthodes printRoutes et printPlugins appelées après await app.ready() sont ici les principaux outils de diagnostic et montrent respectivement l'arbre des routes et l'arbre des contextes. Quelqu'un qui rencontre ce modèle pour la première fois y perdra un jour ou deux, et aucune lecture de la documentation ne raccourcit cela.

Le second coût est l'écosystème. La liste des plugins officiels @fastify est honnête et couvre l'authentification, la limitation de débit, la gestion de fichiers, les sessions, les fichiers statiques et les en-têtes de sécurité, mais elle reste d'un ordre de grandeur plus petite que l'ensemble des middlewares écrits pour Express au fil des années. Pour un besoin inhabituel, par exemple l'intégration avec un fournisseur d'identité vieillissant, les chances de trouver un paquet prêt à l'emploi sont plus faibles. Des passerelles existent, @fastify/middie en version 9.3.3 pour les middlewares simples et @fastify/express en version 4.0.7 pour une couche de compatibilité complète, mais chacune restitue une partie du gain de performance et introduit des objets de requête et de réponse façonnés comme ceux d'Express.

Le cycle de vie d'une requête et les hooks

Les hooks sont des points d'attache dans le traitement d'une requête et leur ordre est fixe. Une fois la route trouvée, Fastify exécute tour à tour onRequest, preParsing, preValidation et preHandler, puis la fonction handler, et après elle preSerialization, onSend et onResponse. En dehors de ce chemin se trouvent onError, onTimeout et onRequestAbort, ce dernier se déclenchant quand un client ferme la connexion avant d'avoir reçu une réponse.

TypeScript
app.addHook('onRequest', async (request) => {
  request.startedAt = process.hrtime.bigint()
})

app.addHook('onSend', async (request, reply, payload) => {
  const elapsed = Number(process.hrtime.bigint() - request.startedAt) / 1e6
  reply.header('server-timing', `app;dur=${elapsed.toFixed(1)}`)
  return payload
})

app.setErrorHandler((error, request, reply) => {
  if (error.code === 'FST_ERR_VALIDATION') {
    return reply.code(422).send({ error: 'validation_failed', detail: error.message })
  }
  request.log.error({ err: error }, 'unhandled error')
  return reply.code(500).send({ error: 'internal' })
})

app.setNotFoundHandler(async (request, reply) => {
  return reply.code(404).send({ error: 'not_found', path: request.url })
})

Le choix d'un hook découle de ce qui est déjà disponible. Dans onRequest, le corps n'a pas encore été lu, donc vérifier un token d'en-tête y convient parfaitement, et rejeter la requête épargne un peu de travail au parseur. Dans preValidation, le corps existe mais n'a pas passé la validation, ce qui en fait l'endroit pour normaliser des données venant d'un système externe. Dans preHandler, vous détenez des données validées, et c'est l'emplacement naturel pour les vérifications de permissions.

Les erreurs de validation portent le code FST_ERR_VALIDATION et se terminent par défaut sur une réponse 400. Si vous préférez les traiter dans la route plutôt que dans un handler global, définissez attachValidation: true dans les options de la route et Fastify écrira l'erreur dans request.validationError au lieu de la lever. Les hooks d'application forment un groupe à part et s'exécutent hors du cycle de requête : onReady avant le début de l'écoute, onListen une fois qu'elle a commencé, onRoute pour chaque route enregistrée, onRegister pour chaque nouveau contexte, et preClose plus onClose à l'arrêt du serveur. Les hooks de requête sont eux aussi soumis à l'encapsulation, ce qui signifie que le même code placé un niveau plus haut ou plus bas dans l'arbre des plugins produit une portée différente.

Fastify face aux alternatives

CaractéristiqueFastifyExpressHonoElysiaNestJS
Validation intégréeoui, schéma JSONnon, via des middlewaresvia un paquet de validationoui, système de types propreoui, via décorateurs et class-validator
Sérialisation à partir du schémaoui, fonction compiléenonnonpartiellenon
Documentation OpenAPIà partir du même schémaà partir d'un fichier séparéà partir d'un paquet supplémentairemodule intégréà partir de décorateurs
Modèle d'extensionplugins avec encapsulationmiddlewares globauxmiddlewares chaînéspluginsmodules et injection
Runtimeserveur HTTP Nodeserveur HTTP Nodenombreux, basé sur l'API Fetchprincipalement BunNode, transport interchangeable
Version actuelle5.12.15.2.14.13.31.4.2911.2.1
LicenceMITMITMITMITMIT

Le choix se ramène à quelques questions. Si vous construisez une API dont le contrat doit être appliqué par la machine et publié en OpenAPI, Fastify le fait avec le moins d'effort. Si la cible est une fonction edge ou un worker dans un environnement d'API Fetch, tournez-vous vers Hono, car Fastify repose sur le module HTTP de Node et n'y fonctionnera pas. Si vous travaillez avec Bun et voulez de l'inférence de types sans provider séparé, envisagez Elysia, en gardant à l'esprit que sa communauté est nettement plus petite. Si le seul client de l'API est votre propre front end TypeScript, tRPC supprime entièrement le problème du contrat, mais vous enferme dans un seul langage des deux côtés. Et si l'équipe est nombreuse et a besoin d'une structure imposée, NestJS la fournit directement et peut tourner sur un adaptateur Fastify, combinant les deux approches.

Express reste un choix raisonnable dans deux situations : quand le projet repose déjà dessus sans problème de performance, et quand vous dépendez d'un middleware sans équivalent dans l'écosystème Fastify. Migrer depuis Express exige en pratique toujours de réécrire la couche de middlewares, car les interfaces de requête et de réponse diffèrent.

Erreurs courantes

La première est la surprise devant des champs qui disparaissent. Un schéma response ne vérifie pas la réponse, il la construit, donc un champ absent du schéma n'atteint jamais le résultat et aucun avertissement n'apparaît. Chaque fois que vous ajoutez un champ au modèle, ajoutez-le aussi au schéma.

La deuxième est un décorateur défini dans un plugin ordinaire plutôt que dans un plugin enveloppé par fp. Une connexion de base de données attachée via app.decorate dans une fonction ordinaire n'existe que dans ce contexte, et les frères verront une valeur indéfinie. Le symptôme ressemble à un bug d'ordre de chargement alors que la cause est l'encapsulation.

La troisième est d'utiliser ensemble return et reply.send dans une fonction async. Retourner une valeur depuis une fonction async envoie la réponse tout seul, donc un reply.send antérieur produit une tentative d'envoi en double. Choisissez une convention et tenez-vous-y dans tout le projet.

La quatrième est celle des nombres qui arrivent de la query string sous forme de chaînes. Sans schéma querystring ou sans coerceTypes dans les options d'AJV, le paramètre ?page=2 reste une chaîne et une comparaison avec un nombre donne faux. C'est la cause la plus fréquente d'une pagination étrange.

La cinquième est d'enregistrer des routes après l'appel à listen. Fastify scelle l'arbre des plugins au démarrage, donc une route ajoutée plus tard est rejetée. Toute la configuration doit s'exécuter avant, et si vous avez besoin d'une préparation asynchrone, utilisez await app.ready().

La sixième est trustProxy activé sans proxy devant le serveur. Dans cette configuration, un client peut mettre n'importe quelle adresse dans l'en-tête x-forwarded-for et contourner une limitation de débit fondée sur l'adresse source.

La septième est de compter sur le gestionnaire de paquets pour la version de Node. Le paquet fastify en version 5.12.1 ne déclare aucun champ engines, donc l'installation sur un vieil environnement passe sans un mot et le serveur ne plante qu'au démarrage.

FAQ

Fastify est-il vraiment plus rapide qu'Express ?

La différence vient de trois mécanismes précis plutôt que d'une optimisation générale. Le routage parcourt un arbre de préfixes au lieu d'une liste de correspondances. La validation et la sérialisation sont compilées une fois au démarrage en fonctions spécialisées, donc il n'y a pas de réflexion sur le schéma pendant une requête. L'ampleur du gain dépend de la forme de la réponse et du temps que prend la base de données. Mesurez sous votre propre charge avant de déclarer que le framework est le goulot d'étranglement.

Dois-je écrire les schémas JSON à la main ?

Non. Un type provider remplace les compilateurs de validation et de sérialisation, ce qui vous permet d'écrire des schémas en Zod pendant que Fastify les consomme exactement comme des schémas JSON. Le paquet fastify-type-provider-zod en version 7.0.0 exige Zod 4.1.5 ou plus récent et Fastify à partir de la ligne 5.5. Le coût est une dépendance supplémentaire et le fait que le schéma OpenAPI provient d'une conversion plutôt que directement.

Fastify fonctionnera-t-il à l'edge ou sur Bun ?

Fastify repose sur le module HTTP de Node plutôt que sur l'API Web Fetch, donc les environnements edge fondés sur le standard Fetch ne sont pas son terrain et Hono est l'outil qu'on y utilise. Bun offre une couche de compatibilité avec l'API de Node, mais c'est un scénario différent d'un framework écrit dès le départ pour ce runtime, comme Elysia.

Peut-on reprendre des middlewares d'Express ?

En partie. Le plugin @fastify/middie en version 9.3.3 permet d'utiliser des fonctions middleware avec la signature à trois arguments, et @fastify/express en version 4.0.7 fournit une couche de compatibilité plus large. Les deux ajoutent un surcoût et introduisent des objets façonnés comme ceux d'Express, donc traitez-les comme une étape de migration plutôt que comme un état final.

Fastify est-il payant ?

Non. Tout le projet est sous licence MIT, confirmée par le fichier LICENSE du dépôt, par le champ license du registre npm et par le fichier de licence contenu dans l'archive publiée. Il n'existe ni variante commerciale ni support payant, et le développement est financé par les sponsors listés dans SPONSORS.md.

La documentation se trouve sur le site de Fastify, la liste des plugins officiels dans la section écosystème, et le code source dans le dépôt GitHub.

À lire aussi