Intergiciels Mongoose : hooks avant et après

L’intergiciel Mongoose (également appelé hooks) se compose de fonctions exécutées avant ou après certaines opérations telles que save, find, updateOne, deleteOne, et bien d’autres. Il vous permet d’injecter une logique personnalisée dans le cycle de vie des opérations sur les documents et les requêtes sans encombrer les gestionnaires de routes. Parmi les utilisations courantes figurent le hachage des mots de passe avant l’enregistrement, la journalisation de la durée des requêtes, l’application de suppressions logiques et le peuplement des données associées après find.

Mongoose possède deux catégories distinctes d’intergiciel : l’intergiciel de document se rattache aux opérations effectuées sur une instance Document donnée (save, validate, remove, init). L’intergiciel de requête se rattache aux opérations de requête invoquées sur le Model (find, findOne, updateOne, deleteOne, etc.). La différence essentielle concerne la référence de this : dans l’intergiciel de document, this désigne le document ; dans l’intergiciel de requête, this désigne l’objet de requête.

Le hook pre-save est l’intergiciel de document le plus courant. Il s’exécute avant l’enregistrement d’un document dans MongoDB. Son cas d’utilisation classique est le hachage des mots de passe : lorsqu’un document utilisateur est enregistré avec un mot de passe nouveau ou modifié, il faut le hacher avec bcrypt avant de le stocker. La vérification this.isModified('password') empêche de hacher à nouveau un mot de passe déjà haché lors d’enregistrements sans rapport.

L’intergiciel de document a accès à des assistants de suivi : this.isNew vaut true lorsque le document est inséré pour la première fois (et non mis à jour). this.isModified(path) renvoie true si le champ indiqué a été modifié depuis le dernier enregistrement ou la dernière récupération du document. Ces assistants vous permettent d’exécuter des hooks sous certaines conditions — uniquement lors de la création ou uniquement lorsqu’un champ précis change.

Les hooks post-save s’exécutent après la persistance réussie d’un document. Ils reçoivent le document enregistré comme premier argument et, dans les anciennes versions de Mongoose, un rappel next. Les hooks post sont idéaux pour les effets secondaires qui doivent se produire après un enregistrement réussi : envoyer un e-mail de bienvenue, mettre à jour un index de recherche, publier un événement dans une file de messages ou vider un cache. Les erreurs des hooks post n’annulent pas l’enregistrement.

Un modèle classique d’intergiciel de requête consiste à implémenter les suppressions logiques. Au lieu de supprimer les documents, définissez un champ deletedAt. Ajoutez ensuite un hook pre('find') qui ajoute automatiquement { deletedAt: null } à chaque requête find, afin que les documents supprimés ne soient jamais renvoyés par défaut. Cette approche fournit une piste d’audit tout en rendant la logique de suppression logique transparente pour le reste de l’application.

Vous pouvez utiliser l’intergiciel de requête pour peupler automatiquement un champ de référence lors de chaque find. Ainsi, un document référencé est toujours résolu sans obliger les appelants à ajouter .populate() à chaque requête. Cette approche est pratique, mais soyez prudent : le peuplement automatique ajoute une deuxième requête à chaque find et peut dégrader les performances si la référence est volumineuse ou n’est pas toujours nécessaire.

Mongoose n’applique pas automatiquement les suppressions en cascade (la suppression des documents associés lorsqu’un parent est supprimé). Vous pouvez implémenter un comportement en cascade avec l’intergiciel de document. Un hook pre-deleteOne sur un modèle User peut supprimer tous les articles, commentaires et sessions appartenant à cet utilisateur avant de supprimer le document utilisateur lui-même. Cela préserve l’intégrité référentielle sans contraintes de clé étrangère.

Si une fonction de hook pre lève une erreur ou rejette une promesse, l’opération qu’elle précède est interrompue. Vous pouvez ainsi effectuer des vérifications de validation ou d’autorisation dans l’intergiciel et interrompre des enregistrements ou des requêtes en levant une erreur. Par exemple, un hook pre-save qui valide la logique métier (et pas seulement la validation du schéma) peut lever une erreur qui remonte jusqu’au bloc catch de l’appel .save() dans le code de l’application.

Mongoose prend également en charge l’intergiciel pour les chaînes d’agrégation. Un hook pre-aggregate vous donne accès au tableau de la chaîne avant son envoi à MongoDB, ce qui permet d’ajouter des étapes au début (par exemple pour filtrer les documents supprimés logiquement) ou à la fin (par exemple pour injecter une limite par défaut). Accédez à la chaîne via this.pipeline() dans la fonction du hook.

Toutes les opérations d’écriture ne déclenchent pas le middleware des documents. updateMany(), findOneAndUpdate() et replaceOne() appelées sur le modèle (et non sur une instance) contournent les fonctions d’interception save des documents : ce sont des middlewares de requête, qui nécessitent des fonctions d’interception distinctes si vous souhaitez les intercepter. Par exemple, une fonction d’interception de hachage du mot de passe avant l’enregistrement ne s’exécute PAS lorsque vous appelez User.updateOne({}, { $set: { password: plain } }). Hachez toujours le mot de passe dans le code de l’application lors des mises à jour effectuées par requête.

Dans cette leçon, vous avez appris que les fonctions d’interception préalables s’exécutent avant une opération et peuvent l’annuler en levant une erreur ; les fonctions d’interception postérieures s’exécutent après l’opération et reçoivent son résultat comme argument, que le middleware des documents (pré-enregistrement, pré-deleteOne) utilise « this » comme document, tandis que le middleware des requêtes utilise « this » comme objet de requête, et que les méthodes d’écriture au niveau des requêtes (updateOne, updateMany, findOneAndUpdate) contournent le middleware des documents : vérifiez toujours quelles fonctions d’interception s’exécutent pour chaque type d’opération. Vous avez ainsi terminé le parcours de cours MongoDB et bases de données NoSQL !