Ajouter des fonctionnalités à un service Go extensible avec des tests qui résistent aux surcharges de configuration

## Trouver le paquet responsable du changement avant de modifier Classez la modification et repérez la source faisant autorité avant de changer le code. - Repérez le point d’entrée de la commande, les modules métier, la couche de configuration, la couche de transport et d’autorisation, l’implémentation du protocole, la couche de sortie, le registre des capacités et les métadonnées de version. - Conservez la logique métier dans les modules sources qui en sont responsables plutôt que dans le câblage des commandes ou les adaptateurs de distribution. - Considérez les répertoires de modules linguistiques et de programmes d’installation comme de simples adaptateurs de distribution binaire ; ne les modifiez que pour les tâches d’empaquetage ou de gestion des versions. - Lisez les définitions de compilation, la configuration des tests, les implémentations voisines et la documentation destinée aux utilisateurs qui régissent la zone concernée. - Avant toute modification, distinguez les sources rédigées manuellement des fichiers générés et des artefacts de compilation. - Répertoriez chaque gestionnaire, type public, point d’enregistrement, chemin de configuration, test, document et interface de module concernés. Utilisez l’organisation et les conventions de nommage établies dans le dépôt au lieu d’introduire une structure parallèle. ## Journaliser via le wrapper de contexte pour garder les logs liés aux traces Utilisez l’adaptateur de journalisation contextuelle du dépôt chaque fois que le code de production émet une entrée de journal. - Propagez le contexte de la requête jusqu’au point où la journalisation a lieu ; ajoutez un paramètre de contexte si la chaîne d’appels n’en transporte pas encore. - N’appelez pas directement le journaliseur contextuel de base du cadre logiciel lorsque l’adaptateur enrichit les entrées pour les corréler à la télémétrie. - Si une fonction démarre un nouveau segment de traçage, récupérez de nouveau le journaliseur contextuel après le démarrage du segment ; un journaliseur capturé auparavant conserve le contexte du segment précédent. - Maintenez les valeurs structurées associées au contexte actif afin que la passerelle de journalisation puisse rattacher les entrées au bon traçage. - Vérifiez et traitez chaque erreur renvoyée dans le code de production au lieu de l’ignorer. - Préservez les limites établies par le dépôt en matière de masquage des données, d’autorisation et d’observabilité lorsque vous ajoutez des diagnostics. Vérifiez la corrélation et le comportement des erreurs à partir de résultats observables, plutôt que de vous fier uniquement à la présence d’une instruction de journalisation. ## Ajouter de nouveaux outils par un handler, un groupe et un enregistrement Concevez une nouvelle capacité avant de l’implémenter : confirmez son nom, son regroupement, son schéma d’entrée, son comportement et la couverture de son évaluation. 1. Implémentez le gestionnaire responsable de la logique de la capacité. 2. Définissez le contrat public de son outil ou de sa commande et reliez-le au gestionnaire. 3. Ajoutez-la au groupe de capacités approprié ou créez un groupe bien délimité si aucun ne convient. 4. Enregistrez un nouveau groupe par le chemin d’initialisation du dépôt. 5. Mettez à jour ensemble les tests de comportement, les références de configuration, les catalogues générés et la documentation utilisateur. Conservez chaque groupe de capacités dans son propre répertoire dédié. Évitez les chemins d’enregistrement en double ou les noms qui exposent des détails internes d’implémentation. ## Utiliser les cibles de build déclarées et ne déployer que sur demande Utilisez les cibles de compilation déclarées par le dépôt au lieu de reconstituer les commandes de mémoire. - Avant l’exécution, sachez quelle cible de compilation formate le code source, organise les modules, compile une plateforme ou produit toutes les plateformes prises en charge. - Examinez les différences obtenues, car une cible de compilation peut réécrire intentionnellement les métadonnées de dépendances ou les fichiers générés. - Gardez les déclarations de dépendances ordonnées après l’ajout d’un module et exécutez la cible d’analyse statique dont la version est fixée par le dépôt. - Préservez les modes d’exécution locale et distante pris en charge, notamment la priorité documentée entre les options explicites, les variables d’environnement, les fichiers par défaut et la configuration interne à la grappe. - Documentez les cibles de test ou d’analyse de style qui téléchargent des outils ou des environnements à la première utilisation ; l’absence d’accès au réseau peut provoquer des échecs de préparation plutôt que des échecs du code. - Gardez les adaptateurs du gestionnaire de modules simples et synchronisés avec le binaire compilé au lieu de dupliquer la logique du service. Traitez les cibles qui téléchargent, publient, envoient ou déploient comme des limites d’opérations externes. Examinez d’abord leurs contrats et ne publiez ni ne déployez jamais, sauf si la tâche comprend explicitement un travail de mise en production. ## Tester le comportement public et les cas limites, pas les fonctions privées Exercez l’API publique comme une boîte noire et privilégiez les implémentations réelles ou les tests d’intégration lorsque cela est possible. - Organisez les tests selon la convention de jeux de tests du dépôt et associez à chaque fichier de test un jeu correspondant. - Utilisez des sous-tests imbriqués pour regrouper les scénarios associés et donnez à chaque cas un nom descriptif fondé sur le comportement. - Dans l’idéal, chaque cas démontre un seul comportement à l’aide d’une assertion ciblée. - Couvrez les parcours réussis, les fonctions de rappel, les changements d’état et les sorties observables sans coupler les tests à des fonctions privées. - Ajoutez des cas limites pour les valeurs nil ou null, les collections vides, les indices non valides, les incompatibilités de types, les entrées mal formées et les chemins d’erreur. - Utilisez des assertions préalables pour les opérations de préparation qui doivent réussir, puis vérifiez explicitement les erreurs ou les valeurs attendues. - N’ignorez jamais une erreur dans le seul but de garder un test concis. Pour un défaut, commencez par un test ciblé qui échoue, exécutez le module ou le jeu concerné après la correction, puis terminez par la cible complète de tests exigée par le dépôt. ## Faire passer les tests de configuration même si valeurs par défaut et noms sont surchargés Les tests de configuration doivent rester valides lorsque des compilations en aval écrasent les valeurs par défaut, les noms de fonctionnalités ou les ensembles de capacités activées. - Démarrez les jeux de tests ordinaires avec une configuration de base sans écrasement, puis superposez-y les réglages propres au test. - Pour une configuration simple, fusionnez les valeurs décodées dans la configuration existante du jeu afin de préserver les champs d’exécution déjà établis par l’infrastructure de test. - Lorsqu’une section stocke des valeurs différées ou primitives, utilisez le lecteur en deux étapes tenant compte des métadonnées qui est requis pour analyser entièrement ces sections. - Après une lecture complète de la configuration, restaurez explicitement les champs réservés à l’exécution, comme les chemins de connexion, les choix de sortie et l’état en lecture seule. - Pour les tests de rechargement, construisez délibérément la configuration candidate à partir des valeurs par défaut sensibles aux écrasements utilisées par le service en cours d’exécution, puis héritez des champs d’exécution actifs. - Ajoutez les capacités requises à la liste existante ; ne remplacez jamais la liste par des valeurs par défaut amont simplement supposées. - Résolvez dynamiquement les noms publics pouvant changer de marque, mais gardez fixe la clé d’enregistrement littérale d’un analyseur lorsque son contrat l’exige. - N’inscrivez jamais en dur dans les assertions les valeurs par défaut, les noms publics ou les ensembles de fonctionnalités susceptibles d’être écrasés. Chaque fois que des changements de configuration franchissent ces limites, testez à la fois le comportement de base et au moins un chemin avec écrasement. ## Regrouper les helpers de test et distinguer les échecs de préparation Placez les utilitaires de test génériques dans la zone interne de tests partagée du dépôt et documentez clairement leur objectif, leurs entrées et des exemples. - Gardez les utilitaires indépendants d’une seule fonctionnalité afin que plusieurs modules puissent les réutiliser. - Préférez des interactions réalistes avec l’utilisateur ou le protocole aux raccourcis de bas niveau qui contournent le comportement de production. - Indiquez explicitement les prérequis des tests, notamment les simulateurs locaux de grappes, les environnements téléchargés, les identifiants ou l’accès réseau nécessaire. - Dans les diagnostics, distinguez un échec de préparation d’un échec du produit. - Visez une couverture élevée de l’API publique, en particulier des conditions limites et des chemins d’échec, sans gonfler les mesures avec des cas de faible valeur. - Maintenez la configuration des tests, les alias et les données de test générées en accord avec l’exécuteur de tests actif. Lorsqu’une personnalisation en aval existe, incluez des tests représentatifs pour les capacités renommées, les valeurs par défaut modifiées et les rechargements de configuration. ## Mettre à jour la doc via le générateur et garder les paquets à la même version Mettez à jour chaque surface faisant autorité qui est touchée par une modification du code ou de la configuration. - Utilisez des noms de fichiers en minuscules pour les nouveaux documents lorsque telle est la convention du dépôt. - Mettez à jour les index, les références de configuration ainsi que les guides sur les instructions d’entrée, la journalisation, l’observabilité, l’authentification et l’intégration selon l’incidence de la fonctionnalité. - Traitez les tableaux générés et les sections de référence comme du contenu généré ; conservez leurs paires de marqueurs et mettez-les à jour avec le générateur approuvé. - Ne modifiez pas directement les sections générées et ne validez pas les artefacts de compilation dans le contrôle de version, sauf si la politique du dépôt l’exige explicitement. - Maintenez les binaires natifs, les images de conteneur et les adaptateurs de modules linguistiques en accord avec le même comportement versionné du service. - Exécutez les contrôles documentés de compilation, de test, d’analyse de style, de génération de documentation et d’empaquetage ciblé qui concernent la modification. Avant de présenter la modification, confirmez que les différences finales ne contiennent que les mises à jour prévues du code source, des tests, de la documentation et des modules. N’exécutez les cibles de mise en production ou de publication que si la tâche les inclut explicitement, et signalez tout contrôle plus large volontairement laissé hors du périmètre.