Backend Modulaire
Réalisez le comportement demandé avec la plus petite modification lisible. Appliquez ces conventions aux nouveaux backends et au code affecté dans les projets existants. Ne transformez pas une correction ciblée en une migration complète du projet.
Charger les références pertinentes
| Tâche | Lire |
|---|---|
| Nouveau module, refactorisation structurelle, DTO, injection de dépendances | Architecture |
| Contrats d'erreur, échecs de validation, filtres globaux, i18n | Erreurs et i18n |
| Requêtes, index, transactions, Redis, comportement cache/stockage | Données et Redis |
| Packages utilisateur, authentification, sessions, OAuth, appareils, empreintes, hachage de mot de passe/IP | Identité |
| Gardes d'en-tête et JWT, middleware, décorateurs de route et de paramètres | Frontière de requête |
| Bootstrap, configuration, limites de débit, journaux, santé, vérification | Opérations |
| Files d'attente, travailleurs, plannings, idempotence des webhooks, limites de ressources | Travail en arrière-plan |
| Dockerfile, Compose local, scripts Bash start/stop, commandes API/worker | Docker |
| Vérifications CI, conteneurs, migrations, versions, rollback | CI/CD |
Pour un nouveau backend, une refonte fondamentale ou une demande de correction de composants de base manquants, lisez Architecture, Opérations, Erreurs et i18n, Frontière de requête, Docker, et Données et Redis avant d'éditer. Lisez les autres références selon les besoins de la tâche. Adaptez les exemples aux versions installées et au domaine réel. Utilisez du Markdown portable et des outils de projet standard. Suivez le modèle de permissions de l'agent hôte.
Établir le périmètre avant d'éditer
Lisez les instructions du dépôt, le manifeste du package, le bootstrap, les modules affectés et leurs appelants, les schémas pertinents, l'utilisation de Redis et les tests. Utilisez les définitions de configuration et les noms de variables d'exemple pour la découverte.
Nouveau backend. Appliquez directement les règles de fondation et d'architecture. Implémentez la base connectée et utilisez les références pertinentes pour les flux de produits demandés. Demandez les décisions produit manquantes qui affectent le comportement ou la propriété des données. La compétence définit déjà les choix d'ingénierie de base.
Backend existant. Commencez par une évaluation d'architecture en lecture seule. Présentez l'architecture actuelle, la cible proposée, et les composants à conserver, modifier, ajouter ou différer. « Réviser ce backend selon backend-modulaire » couvre l'ensemble du backend. Lorsqu'une demande spécifie la norme sans sélectionner de changements particuliers, demandez en une question concise quelles propositions appliquer et attendez la décision. Si l'utilisateur a déjà explicitement demandé un changement spécifique, analysez et partagez d'abord l'architecture pertinente, procédez à ce changement, et demandez avant d'entreprendre d'autres changements architecturaux. Une demande d'analyse uniquement se termine par l'évaluation. Après que l'utilisateur a sélectionné le périmètre, implémentez-le et exécutez les contrôles d'acceptation applicables.
Pour une demande nommant une fonctionnalité, un point de terminaison ou un bug, limitez l'évaluation à ce chemin et à ses appelants affectés. Utilisez le module existant le plus proche qui suit ces règles comme modèle pour le nommage, le placement des fichiers, les DTO, les erreurs et le style de transaction.
Nouveau backend, refonte fondamentale ou correction de base
- AppBuilder et Helmet sont obligatoires pour HTTP. Gardez
src/main.tsléger et placez la construction HTTP danssrc/builder/app.builder.ts. Utilisez unFastifyAdapterNest explicite ou dufastifydirect pour Node.js HTTP sans Nest. Enregistrez@fastify/helmetcompatible avant l'initialisation ou l'écoute. Liez le vrai builder dans les tests d'intégration HTTP. Les travailleurs sans HTTP utilisent leur propre point d'entrée. - Localisez les erreurs HTTP dans un filtre global ou un gestionnaire Fastify. Utilisez des définitions d'erreur de module avec
code,statusetmessageKey, un registre typé et une exception partagée. Retournez{ status, code, message }pour les nouveaux contrats HTTP.statuscorrespond au statut HTTP,codereste stable entre les langues, etmessageprovient de l'i18n. Pour les API existantes, préservez les champs publiés jusqu'à ce qu'une migration compatible soit convenue. - L'infrastructure Redis et un chemin de données Redis réel sont obligatoires. Ajoutez une configuration de connexion validée, des fichiers centralisés de clés Redis et de TTL, un fournisseur Redis partagé et une sonde de disponibilité. Assignez à Redis au moins une famille de données utile pour laquelle il est la source de vérité. Implémentez ses lectures et écritures réelles via un dépôt domaine. Une connexion, une sonde de santé ou un cache de réponse SQL seul ne satisfait pas cette règle. Utilisez un flux produit existant approprié tel que la configuration client publiée, le classement/état en direct, ou le throttling partagé. Lorsque le produit a une politique de configuration client ou de version, stockez et servez son document publié depuis Redis. Identifiez une décision produit manquante si aucune famille de données légitime ne peut être choisie dans le périmètre.
- Générez les clés Redis à partir de modèles partagés. Gardez les modèles
[placeholder]dansredis-keys.config.ts, les TTL dansredis-ttl.config.ts, etgenerateRedisKey/generateRedisKeysdanssrc/utils/redis-key.util.ts. Faites en sorte que le fournisseur partagé applique le namespace configuré une fois. Utilisez ce chemin dans les lecteurs, rédacteurs et jobs réels. Préservez le format de clé existant lors des révisions, sauf si l'utilisateur sélectionne une migration planifiée. Voir les exemples de clés Redis. - Les lectures possédées et préparées par Redis restent sur Redis. Définissez le comportement de population, mise à jour, clé manquante, expiration, panne et récupération par famille de clés. Utilisez une absence typée pour une entité réellement manquante et une indisponibilité typée pour une panne ou une projection requise qui n'est pas prête. Une requête n'interroge jamais SQL en solution de repli pour ces rôles. Utilisez une exception explicite de cache-aside uniquement pour un cache jetable convenu. Préservez un contrat de lecture existant lors de révisions non liées.
- Câblez la limitation de débit partagée pour HTTP. Enregistrez la garde ou le hook d'application et configurez un budget par défaut pour les routes externes. Ajoutez des budgets plus stricts basés sur Redis pour l'authentification, la récupération et les actions coûteuses qui existent. Utilisez des compteurs IP et de compte normalisés séparés pour la connexion par mot de passe. Incrémentez et expirez atomiquement, répondez avec 429 et
Retry-After, et retournez un 503 typé lorsque l'application obligatoire est indisponible. Utilisez une politique explicite pour les exemptions de route système. - Paginez chaque collection croissante exposée par HTTP. Utilisez un DTO de requête validé, une limite bornée et un curseur de jeu de clés stable contenant chaque valeur de tri plus un briseur d'égalité unique. Interrogez
limit + 1avec le périmètre et les filtres de l'appelant dans le dépôt. Retournez{ items, nextCursor }pour les nouvelles listes. Calculez les totaux exacts et utilisez le décalage de numéro de page uniquement lorsque le contrat API en a besoin. - Câblez les gardes et décorateurs que l'API utilise. Utilisez une garde d'en-tête typée pour un contrat mobile/appareil, une garde JWT pour les routes JWT protégées, et des gardes de rôle, invité ou spécifiques au fournisseur là où la politique en a besoin. Enregistrez les gardes et consommez leur contexte validé à l'aide de décorateurs de paramètres. Utilisez les hooks de requête Fastify ou le middleware existant pour les préoccupations de transport transverses.
- Fournissez un workflow Docker exécutable. Fournissez ou réutilisez un Dockerfile, Compose pour les dépendances locales, et des commandes Bash start/stop spécifiques au projet. Attendez la disponibilité et utilisez des volumes durables pour les données faisant autorité. Conservez un workflow établi équivalent lors des révisions. Exécutez les plannings de jobs et les consommateurs uniquement lorsque la charge de travail le justifie.
- Implémentez uniquement les modules/fonctionnalités requis. Les workflows d'authentification/utilisateur/appareil sont des conseils réutilisables, pas une permission d'ajouter des fonctionnalités de compte à un service qui n'en a pas besoin.
- Utilisez d'abord les modules intégrés Node.js et les modules NestJS officiels. La base approuvée inclut
@fastify/helmetcompatible, un seul client Redis, etnestjs-i18npour les erreurs HTTP Nest si aucune intégration i18n appropriée n'est installée. Un nouveau flux d'authentification par mot de passe peut utiliserargon2compatible pour Argon2id ; utiliseznode:cryptopour les digests de jetons et les empreintes digitales avec clé. Conservez le client Redis de travail existant ou utilisez par défautredispour un nouveau projet. Utilisezfastifydirectement là où il est importé. Les autres nouveaux packages tiers, pairs optionnels et plugins Fastify nécessitent une approbation explicite. Voir Opérations. - Fournissez un bootstrap connecté, une configuration validée, des fournisseurs, des migrations requises, une configuration locale et les API demandées. Ne vous arrêtez pas à des fichiers de squelette déconnectés.
Backend existant / révision
- Trouvez tous les appelants avant de modifier une fonction partagée ou de déplacer des fichiers : services, contrôleurs, jobs, gardes, exports, mocks, fixtures et consommateurs de réponse.
- Préservez les modifications non liées, les contrats publics, le comportement des jetons/stockage, la validation, les filtres de propriété et le nommage établi. Limitez le nettoyage au chemin de la tâche.
- Lorsque la tâche met en place, remplace ou répare la fondation HTTP, amenez Fastify, AppBuilder et Helmet ensemble dans le périmètre. Préservez l'adaptateur et le bootstrap lors de modifications de fonctionnalités non liées. Lors de la migration vers Fastify, vérifiez les codes de statut, le middleware, les cookies, les téléchargements et les corps de webhook signés le cas échéant.
- Extrayez les requêtes vers des dépôts concrets lors de la modification du service pertinent. Préservez le contexte de transaction, les verrous, la gestion des erreurs, la forme de retour, la suppression logique et les périmètres de locataire.
- Lors de la modification d'une liste ou d'un limiteur, préservez le curseur public existant et le contrat de réponse, et resserrez la validation dans le périmètre. Tracez les métadonnées de limite de débit vers une garde ou un hook en cours d'exécution. Conservez le périmètre de l'acteur et du locataire dans la requête de données. Planifiez explicitement les modifications incompatibles de curseur ou de clé de limiteur.
- Pour une mise en place ou une refactorisation d'infrastructure, appliquez la même politique de package. Préservez les intégrations existantes sauf si la tâche les modifie. Résolvez les dépendances requises pour l'infrastructure demandée avant d'ajouter des packages.
- Ne supprimez pas silencieusement le repli, ne changez pas le stockage de session, ne modifiez pas les durées de vie des jetons ou n'invalidez pas toutes les sessions comme nettoyage. Planifiez les migrations de compatibilité et de données/clés pour les transitions demandées.
- Produisez les migrations nécessaires ; ne supprimez pas de données en direct ou n'exécutez pas de migrations de production par inadvertance.
Règles d'architecture
- Utilisez la mise en page complète pour chaque fonctionnalité sous
src/modules/. Chaque module de fonctionnalité inclutdto/, un contrôleur, un service, un dépôt et<feature>.module.ts. Gardez un seul contrôleur, service ou dépôt à la racine du module. Lorsqu'une couche contient plusieurs fichiers, regroupez-la danscontrollers/,services/ourepositories/. Utilisezerrors/pour les erreurs spécifiques au module si nécessaire. Placez les fournisseurs de support sous infrastructure ou les jobs sous workers lorsqu'ils n'ont pas d'API de fonctionnalité ou d'accès aux données. Lors d'une révision limitée, préservez les chemins existants sauf si un changement de mise en page de module fait partie de la tâche. - Le contrôleur gère HTTP ; le service décide ; le dépôt accède aux données. Pas de logique métier, de requêtes ORM ou de commandes Redis dans les contrôleurs. Les services possèdent les règles et l'orchestration. Les dépôts possèdent les requêtes et les opérations Redis, y compris les écritures conditionnelles qui appliquent des invariants atomiques.
- Composez de manière pratique. Les actions métier inter-modules appellent le service propriétaire. L'utilisation directe d'un dépôt exporté est autorisée pour un travail purement lié aux données ou pour des transactions partagées. Ne créez pas de méthodes de service passe-partout pour l'apparence.
- Gardez la propriété de la transaction proche du travail. Le service peut couvrir plusieurs dépôts avec un seul client de transaction transmis ; le dépôt peut posséder une opération atomique autonome. Chaque participant utilise ce client. Pas d'Unité de Travail ou de framework de transaction générique.
- Écrivez du code petit et lisible. Réutilisez les helpers, les API standard et les dépendances installées. Évitez les options spéculatives, les wrappers, les classes de base, les dépôts génériques et les abstractions à usage unique. Supprimez les validations redondantes et les catch-and-rethrow ; conservez la validation aux frontières, l'autorisation, la concurrence et la protection contre la perte de données.
- Réduisez le travail réel. Minimisez les requêtes, les allers-retours, les champs, les lignes et les allocations intermédiaires. Les requêtes parallèles par élément restent du type N+1. Équilibrez le temps et l'espace pour la charge de travail ; ne promettez pas des minima absolus ou n'affaiblissez pas le hachage de mot de passe pour la vitesse.
- Justifiez les index. Liez chaque index à une requête réelle ou à une contrainte d'intégrité. Inspectez les index primaires, uniques et composites avant d'en ajouter. N'ajoutez pas de doublons spéculatifs et ne supprimez pas d'index basé uniquement sur l'apparence du schéma.
- Assignez un rôle à Redis. Distinguez les données primaires, les modèles de lecture préparés et les caches jetables. Définissez la propriété, la population/mise à jour, le TTL, l'absence, la panne et la récupération. Pas de repli automatique vers la base de données. Les échecs de cache et les échecs de connexion sont distincts ; choisissez la politique à partir de la référence de données.
- Partagez uniquement le code partagé. Les helpers communs appartiennent à utils/common, l'infrastructure à libs, les paramètres partagés à config. Gardez les helpers propres au module en local. Centralisez les clés Redis et les TTL.
- Possédez et typez les erreurs. Définissez les erreurs de domaine sous le répertoire
errors/du module. Lancez l'ErrorCodeenregistré viaAppExceptionet traduisez sonmessageKeyà la frontière HTTP. Gardez les requêtes internes, les traces de pile, les secrets et les détails du fournisseur hors des réponses.
Compléter et vérifier
Mettez à jour les appelants nécessaires, les DTO, les définitions d'erreur, les fournisseurs/exports, la configuration, les schémas/migrations et les tests. Implémentez les échecs importants ainsi que les succès.
Pour le travail de fondation, suivez les contrôles d'acceptation. Tracez le point d'entrée de production à travers le builder et une fonctionnalité réelle à travers son dépôt Redis. Vérifiez Helmet, le contrat d'erreur HTTP localisé, l'initialisation et l'arrêt de Redis, et l'absence versus la panne. Vérifiez 429 et 503 sur les routes limitées réelles, et testez la pagination stable sur chaque nouveau contrat de liste. Signalez tout élément de base manquant ou non vérifié.
Une nouvelle logique non triviale nécessite un petit test de comportement ou une vérification basée sur une assertion. Vérifiez les invariants affectés : propriété, nombre de requêtes, rollback, expiration/réutilisation/concurrence des jetons, absence versus panne Redis, ou mises à jour atomiques. Les déplacements triviaux n'ont pas besoin de tests miroir d'implémentation.
Lorsque vous modifiez des modules existants, mettez à jour les tests existants pour refléter le comportement réel. Corrigez la vérification de type, l'ordre des paramètres et les valeurs d'exemple. N'ajoutez pas de tests qui testent simplement la signature, et ne supprimez pas les tests qui échouent en raison d'un comportement d'assertion incorrect. Exécutez npm test pour les modifications et demandez/intégrez une correction si l'environnement signale un échec.
Pour les nouveaux modules, ajoutez feature.module.ts à l'import racine. Ajoutez les propriétés manquantes aux fichiers .env d'exemple, .env.test et .env.example dans config/. Injectez les dépendances requises. Créez le fournisseur d'usine de la base de données pour la migration s'il n'existe pas. Supprimez le code de test pour les parties non implémentées si le squelette a été généré.