Modifier un framework web à typage sûr et séparer le code de base de données en trois couches

## Entrer dans l’environnement de développement figé du dépôt et trouver le paquet responsable Accédez à l’environnement de développement par l’intermédiaire du gestionnaire d’environnement déclaré par le dépôt, plutôt que de dépendre d’outils installés globalement. ### Configuration de l’environnement - Partez de la racine du dépôt et activez l’interpréteur de commandes de développement approuvé. - Utilisez le chemin d’exécution mis en cache par l’environnement lorsqu’il est disponible afin d’accélérer les commandes répétées. - Vérifiez que le compilateur, le gestionnaire de paquets, les outils de base de données et les outils de documentation proviennent de l’environnement aux versions verrouillées. - Utilisez la version de l’environnement d’exécution déclarée par le paquet concerné ou la configuration de la documentation. - Activez la journalisation de débogage uniquement lorsqu’elle est nécessaire au diagnostic local et ne considérez pas le mode de débogage comme la valeur par défaut en production. ### Contexte de travail Dans un dépôt multipaquet, identifiez le paquet responsable de la modification avant d’exécuter des commandes. Repérez son répertoire source, son point d’entrée de test, ses artefacts générés, ses modules publics et ses instructions locales, au lieu de supposer que tous les paquets partagent le même flux de travail. ## Vérifier d’abord les types rapidement, puis lancer tous les tests Utilisez la boucle de retour fiable la plus rapide pendant les itérations, puis exécutez la validation officielle plus large requise pour la transmission. ### Itération ciblée - Préférez un compilateur interactif, un vérificateur de types ou un chargeur de modules pour obtenir rapidement un retour sur les types lorsque la construction de l’environnement complet est coûteuse. - Ne chargez que le module modifié ou le point d’entrée du test ciblé pendant les premières itérations. - Les outils interactifs qui lisent l’entrée standard doivent recevoir des commandes et un chemin de sortie explicite ; sinon, ils risquent d’attendre indéfiniment. - Lorsqu’une session interactive prend en charge le rechargement, réutilisez-la après les modifications au lieu de reconstruire plusieurs fois l’environnement entier. ### Enregistrement des tests - Ajoutez les nouveaux tests à l’agrégateur de tests canonique du paquet ou à sa configuration de découverte. - Vérifiez que le test ciblé s’exécute réellement par l’intermédiaire de ce point d’entrée. - Exécutez la validation complète du dépôt lorsque la modification est prête ou lorsque le comportement partagé, la configuration de construction ou les limites des paquets sont concernés. - Ne présentez pas une vérification de compilation ciblée comme la preuve que la suite de tests complète réussit. ### Serveur de développement Démarrez les services locaux uniquement depuis l’environnement approuvé et le bon répertoire de travail. Lorsque le serveur de développement dépend d’une application hôte ou d’un répertoire parent, établissez explicitement ce contexte avant d’appeler son point d’entrée. ## Donner à chaque paquet son propre rôle et n’exposer que des modules publics réduits Cartographiez les responsabilités avant de modifier le code, en particulier dans un dépôt qui réunit l’environnement d’exécution, les outils de développement, les modèles, les migrations, la synchronisation, les interfaces de programmation d’applications, les tests et les intégrations facultatives. ### Carte des responsabilités - Séparez le démarrage du serveur et les intergiciels de la configuration du framework. - Maintenez le routage et la génération des localisateurs uniformes de ressources avec un typage sûr et isolés du traitement des requêtes. - Séparez par responsabilité les modèles, la validation, l’authentification, les tâches en arrière-plan, le stockage, le courrier et les mises à jour en temps réel. - Lorsque l’architecture les définit comme des outils, maintenez la génération de code, la conception de schémas et le comportement du serveur de développement en dehors du paquet principal de l’environnement d’exécution. - Traitez les intégrations facultatives et les composants côté serveur comme des paquets distincts au lieu de laisser leurs dépendances se propager dans le cœur. ### Interface publique Exposez la plus petite surface stable de modules nécessaire aux utilisateurs. Gardez privés les instructions brutes, la composition interne, les préambules auxiliaires et les modules d’implémentation afin qu’ils puissent évoluer sans rompre les appelants. Ajoutez aux modules et fonctions publics la documentation d’API standard du projet. ### Conventions du langage Suivez les usages établis de la base de code pour les valeurs pures, les paramètres contextuels, l’accès aux champs, les modèles, le routage au niveau des types et les types de modèles. Préférez la convention déjà employée par le projet à une forme équivalente qui accentue les incohérences. ## Ne jamais insérer de valeurs dans le texte de la requête et n’exposer que la couche session Organisez l’accès à la base de données en couches d’instructions, de transactions et de sessions, avec une attribution explicite de la responsabilité de l’encodage, de l’atomicité et des connexions. ### Couche d’instructions - Conservez les requêtes paramétrées brutes avec leurs encodeurs d’entrée et leurs décodeurs de résultats. - Utilisez des paramètres fictifs pour chaque valeur d’exécution au lieu d’interpoler les valeurs dans le texte de la requête. - Encodez explicitement la possibilité de valeur nulle et les types de la base de données. - Choisissez un décodeur correspondant à la cardinalité attendue : une ligne facultative, une ligne obligatoire ou plusieurs lignes. - Conservez les décisions de mise en cache des instructions avec la définition de l’instruction. ### Couche de transactions - Composez les instructions en opérations métier qui exigent l’atomicité. - Maintenez les règles de branchement, les vérifications d’existence et les décisions de création à l’intérieur de la transaction lorsqu’elles doivent observer un seul état cohérent. - Rendez les résultats idempotents explicites afin que les appelants puissent distinguer un enregistrement existant d’un enregistrement nouvellement créé. - N’utilisez une composition indépendante ou sélective que lorsque les opérations sont réellement indépendantes et préservent la sémantique de transaction recherchée. ### Couche de sessions - Présentez la couche de sessions comme l’interface publique de la base de données. - Laissez les sessions prendre en charge l’exécution des connexions et les limites des transactions tout en masquant les instructions brutes et les transactions internes. - Utilisez une transaction explicite pour les opérations comportant plusieurs instructions et l’exécution directe d’une instruction pour une requête unique et indépendante. ## Adapter le niveau d’isolation et le type de résultat à chaque opération de base de données Adaptez l’isolation, la cardinalité et les types de résultats à la sémantique de l’opération au lieu d’appliquer un modèle unique partout. ### Choix d’isolation - Utilisez une transaction d’écriture forte pour les opérations critiques dont l’exactitude dépend de la sérialisation. - Utilisez un niveau d’isolation de lecture approprié pour les requêtes où la simultanéité est importante et où une isolation plus faible est acceptable. - Documentez toute opération dont l’exactitude dépend d’un mode d’isolation particulier. ### Conventions des résultats - Représentez les résultats de zéro ou une ligne par une valeur facultative. - Représentez les résultats de plusieurs lignes avec le type de séquence standard du projet. - Utilisez des tuples pour les petits résultats internes à plusieurs colonnes lorsque des enveloppes nommées n’ajouteraient aucune limite utile. - Renvoyez un indicateur de réussite explicite lorsqu’une mise à jour ou une suppression risque de ne toucher aucune ligne. - Pour les opérations idempotentes, renvoyez à la fois si le travail a été effectué et la valeur obtenue. ### Composition des codecs Lorsqu’une bibliothèque d’encodeurs compose des paires imbriquées, adaptez délibérément les tuples d’entrée plats et conservez la correspondance à proximité de l’instruction. Composez les décodeurs de manière à préserver l’ordre des colonnes, la possibilité de valeur nulle et la cardinalité des lignes. Ajoutez des tests ciblés pour les incompatibilités qui pourraient associer silencieusement des valeurs au mauvais champ. ## N’ajouter des dépendances que là où elles servent et ne jamais faire de force-push Maintenez les modifications compatibles, faciles à examiner et récupérables. ### Code et dépendances - Utilisez les formes de langage privilégiées par le projet lorsqu’elles améliorent la clarté pour les personnes qui contribuent. - Documentez les interfaces publiques avec le système de documentation standard du dépôt. - Respectez les extensions de langage activées dans la base de code et n’introduisez pas de nouvelles extensions sans besoin concret. - Ajoutez les dépendances uniquement au paquet qui les utilise. - Déclarez des limites de compatibilité inférieures et supérieures adaptées à l’écosystème pris en charge. - Considérez les dépendances expérimentales comme un risque explicite et isolez-les derrière des interfaces étroites. ### Sécurité de Git - Ne faites jamais de force-push, y compris de force-with-lease. - Si la branche distante a progressé, récupérez les changements et effectuez un rebase ou une fusion sur l’historique mis à jour, résolvez les conflits, validez, puis poussez normalement. - Ne masquez pas un push rejeté en réécrivant l’historique partagé. - Excluez du commit les fichiers générés sans rapport, les modifications du fichier de verrouillage et les paramètres de performances locaux. ## Garder les surcharges locales hors des commits et publier la documentation par le processus de publication Utilisez des surcharges locales de performances et de dépendances pour le développement sans les laisser se propager dans le contrôle de code source partagé. ### Surcharges locales de performances - Des indicateurs temporaires de construction rapide peuvent être activés pour les itérations locales lorsque le projet les prend en charge. - Ne validez pas une modification de performances réservée à l’environnement local. - Avant la transmission, examinez la différence réelle au lieu de vous fier uniquement à des indicateurs d’index susceptibles de masquer des modifications. ### Développement avec des dépendances locales Lors du développement simultané d’un framework et d’une application qui l’utilise : 1. Placez l’extraction locale du framework dans un emplacement de développement choisi délibérément. 2. Faites pointer la dépendance de l’application vers ce chemin local au moyen du mécanisme de surcharge pris en charge. 3. Activez l’environnement requis et actualisez l’état des dépendances. 4. Testez l’application avec le framework local. 5. Supprimez ou documentez intentionnellement la surcharge avant de préparer les modifications partagées. ### Documentation et publication - Prévisualisez la documentation localement depuis l’environnement qui lui est réservé. - Lorsque la documentation publiée est maintenue séparément, mettez à jour sa dépendance au framework ou à la documentation au moyen du flux de travail approuvé du dépôt. - Ne validez que les modifications du fichier de verrouillage ou des sources requises par cette mise à jour. - Déployez la documentation ou l’infrastructure uniquement au moyen du processus de publication désigné, en respectant l’ordre requis entre la mise à jour des dépendances, l’état validé et le déploiement. - Lorsqu’une publication du framework exige la synchronisation de la documentation en aval, ajoutez cette étape à la liste de contrôle de publication au lieu de vous fier à la mémoire.