Modifier un service d’autorisation fondé sur des graphes en écrivant d’abord les tests
À utiliser pour modifier un service d’autorisation fondé sur des graphes. Suit le trajet de chaque requête, utilise les cibles de build et les règles de lint du dépôt, écrit d’abord un test qui échoue et ne retouche pas les fichiers générés.
Pour utiliser ces règles d'IA
## Placer la correction en premier et utiliser les cibles de build du dépôt
Appliquez les priorités du projet dans cet ordre :
1. Correction : chaque décision d’autorisation doit être exacte.
2. Fiabilité : le service doit rester disponible et se rétablir de manière prévisible.
3. Performances : ne réduisez la latence et les allocations qu’après avoir garanti la correction et la fiabilité.
Considérez les cibles de compilation définies dans le dépôt comme la source de vérité. Préférez-les aux commandes ad hoc, car elles intègrent la génération requise, les indicateurs, la détection des accès concurrents, la couverture, le linting et la configuration de l’environnement.
Les groupes de cibles habituels doivent couvrir :
- les compilations de production ;
- la suite de tests complète ;
- les tests filtrés pour un cas nommé ;
- les benchmarks avec des métriques de mémoire ;
- les tests d’intégration nécessitant des conteneurs ;
- le linting avec la version de l’outil configurée dans le dépôt ;
- les doublures de test générées ;
- le développement local avec un datastore en mémoire ou reposant sur un conteneur.
Avant d’exécuter une cible, lisez sa définition et les variables d’environnement requises. Si la cible canonique est indisponible ou peu claire, résolvez ce problème au lieu de lui substituer silencieusement une commande moins rigoureuse.
## Avant de modifier, suivre le trajet d’une requête dans la chaîne de résolveurs
Retracez une requête sur l’ensemble du chemin d’exécution avant de modifier le comportement. Suivez cette séquence :
1. recevoir la requête HTTP ou RPC ;
2. appliquer le middleware ;
3. entrer dans le gestionnaire de transport ;
4. appeler la commande ou le service applicatif ;
5. résoudre le graphe d’autorisation ;
6. accéder au stockage ;
7. renvoyer la réponse.
Repérez les modules responsables du démarrage et de l’arrêt, des gestionnaires, des commandes métier, de l’évaluation du graphe, de la planification, des interfaces et implémentations de stockage, de l’analyse des modèles, de la validation des tuples, de l’authentification et de l’autorisation de l’API.
Pour les vérifications fondées sur un graphe, examinez ensemble le constructeur de résolveurs et l’interface de résolveur. Un pipeline de résolveurs peut ajouter une mise en cache, une limitation du débit de répartition ou une comparaison fantôme uniquement lorsque la configuration les active.
Ne supposez pas que la chaîne est linéaire. Certains systèmes de résolveurs forment une chaîne de délégation circulaire dans laquelle le dernier résolveur revient au premier. Vérifiez l’ordre de construction, les conditions de terminaison et la différence entre les enveloppes facultatives et le vérificateur local central avant de modifier le comportement de répartition.
Considérez le câblage à l’exécution comme un élément de preuve plus solide que les noms de répertoires ou les hypothèses de conception.
## Respecter les règles de nommage du lint et garder les erreurs enveloppées identifiables
Lisez la configuration de linting active avant de modifier les imports ou les noms. Préservez :
- les alias requis pour les API générées et les parseurs ;
- les groupes d’imports configurés et leur ordre ;
- les noms d’interfaces sans préfixes redondants ;
- les constructeurs nommés selon le modèle `NewTypeName` ;
- les options fonctionnelles nommées selon le modèle `WithPropertyName` ;
- les types d’options ayant la forme `TypeNameOption func(*TypeName)` ;
- les constantes exportées conformément au style de nommage des éléments exportés du projet ;
- les constantes non exportées et les clés de contexte conformément au style de nommage local du projet.
Définissez les erreurs de domaine stables comme des valeurs sentinelles. Ajoutez du contexte sans détruire l’identité de l’erreur :
- déclarez une sentinelle telle que `var ErrNotFound = errors.New("not found")` ;
- enveloppez-la avec du contexte, par exemple `fmt.Errorf("load relationship: %w", ErrNotFound)`.
Utilisez `errors.Is` ou `errors.As` pour les correspondances. Ne comparez pas directement les erreurs enveloppées et ne formatez pas une erreur enveloppée avec un verbe qui fait perdre la chaîne.
Maintenez la conversion du domaine vers le transport à une frontière explicite. La logique de commande doit renvoyer des erreurs de domaine ; un convertisseur dédié doit les mapper vers des réponses HTTP ou RPC.
## Écrire d’abord un test qui échoue et tenir à jour les tests en matrice de l’autorisation
Utilisez le développement piloté par les tests pour les modifications de comportement :
1. Ajoutez un test ciblé qui exprime le comportement manquant ou incorrect.
2. Exécutez-le et confirmez qu’il échoue pour la raison attendue.
3. Implémentez la plus petite modification permettant de le faire réussir.
4. Exécutez le test ciblé, puis la suite directement affectée.
5. Ne remaniez le code qu’une fois les tests au vert.
Pour les algorithmes d’autorisation, maintenez des tests matriciels qui définissent les modèles, les tuples de relations et les résultats attendus pour les API de vérification, de listage des objets et de listage des utilisateurs. Une étape de la matrice doit rendre le modèle et les assertions lisibles ensemble.
Un cas matriciel minimal doit préserver cet ordre et ce sens :
1. nommez le test, par exemple `viewer_can_read_document` ;
2. définissez les types `user` et `document` dans le modèle de l’étape ;
3. définissez une relation `viewer` qui accepte un utilisateur ;
4. ajoutez le tuple `document:1`, `viewer`, `user:alice` ;
5. affirmez que la vérification des mêmes objet, relation et utilisateur renvoie `true`.
Maintenez les ressources de test intégrées enregistrées auprès de leurs exécuteurs. Lorsqu’une API possède plusieurs surfaces de listage ou de vérification, vérifiez chaque exécuteur pertinent au lieu de supposer qu’une surface couvre les autres.
Utilisez des benchmarks lorsque vous modifiez des chemins critiques du graphe, la sélection des résolveurs, l’accès au stockage ou du code sensible aux allocations. Utilisez des tests reposant sur des conteneurs pour les comportements propres au datastore.
## Ne pas modifier à la main les fichiers générés ni les schémas d’un autre dépôt
Ne modifiez pas directement les mocks générés, les liaisons de protocole générées ni les autres artefacts générés. Modifiez la source ou le générateur, puis régénérez-les au moyen de la cible canonique.
Ne modifiez pas les définitions de schéma détenues à l’extérieur dans le dépôt d’un service en aval. Effectuez la modification du schéma dans le dépôt qui en est propriétaire, faites-la réviser à cet endroit, puis mettez à jour la dépendance en aval.
Tenez compte des pièges opérationnels suivants :
- une cible de test complète peut régénérer automatiquement les mocks, contrairement à une commande de test exécutée directement au niveau du langage ;
- les tests d’intégration pour les datastores SQL peuvent nécessiter un environnement d’exécution de conteneurs ;
- la récursivité du résolveur peut être intentionnelle parce que la chaîne est circulaire ;
- la syntaxe de la configuration de linting dépend de la version ;
- la modification d’une interface de stockage exige de faire évoluer ensemble chaque backend et ses tests de contrat partagés.
Si un générateur requis, un environnement d’exécution de conteneurs ou un schéma en amont est indisponible, signalez le prérequis manquant. Ne modifiez pas manuellement une sortie dérivée pour simuler l’achèvement.
## Suivre toutes les étapes pour un nouvel endpoint d’API ou un changement de stockage
Pour un nouveau endpoint d’API :
1. mettez à jour le schéma d’API détenu par le projet ;
2. ajoutez le gestionnaire de transport ;
3. ajoutez la logique de commande ou de service applicatif ;
4. mappez les erreurs de domaine à la frontière du transport ;
5. ajoutez des tests ciblés et matriciels.
Pour une modification d’interface de stockage :
1. mettez à jour l’interface ;
2. mettez à jour les tests de contrat de stockage partagés ;
3. implémentez la modification pour chaque backend pris en charge ;
4. exécutez les suites affectées en mémoire et reposant sur des conteneurs.
Pour une modification d’un résolveur de graphe :
1. implémentez l’interface du résolveur ;
2. ajoutez ou mettez à jour les options du constructeur ;
3. vérifiez la composition conditionnelle et la délégation circulaire ;
4. testez la correction, les interactions avec la limitation du débit ou la mise en cache, ainsi que la terminaison ;
5. exécutez un benchmark si le chemin critique peut changer.
Pour une modification du système de types, mettez à jour l’analyse, la validation, la logique de graphe pondérée ou optimisée et les tests de validation associés comme une seule modification cohérente.
Avant de déclarer l’achèvement, examinez le diff pour repérer toute modification accidentelle de fichiers générés, confirmez que l’échec du test ciblé s’est transformé en réussite, exécutez les cibles canoniques directement affectées et consignez toute catégorie de tests qui n’a pas pu être exécutée avec son prérequis exact.