Travail sur un service Go
Conventions pour maintenir la correction d'un service Go en couches sous concurrence et multi-locataire. Lisez d'abord le package environnant — un pattern local appliqué de manière cohérente prévaut sur tout ce qui est écrit ici.
Avant d'écrire du code
Vérifiez la chaîne d'outils. go.mod détermine les fonctionnalités de la bibliothèque standard et du langage disponibles,
et les services dans le même workspace utilisent souvent des versions différentes. La capture de variable de boucle est un
vrai bogue avant Go 1.22 et un non-événement après ; errors.Join, slices et maps nécessitent Go 1.21.
Lisez la version plutôt que de supposer la plus récente.
Ensuite, trouvez la couche qui possède la décision que vous allez modifier. Les handlers traduisent le transport en domaine et rien d'autre. Les services prennent la décision. Les repositories contiennent la requête. Une validation ajoutée dans le handler est invisible pour tout autre appelant du service.
Contexte
Le contexte appartient à la requête et meurt avec elle.
- Passez
ctxcomme premier paramètre, jusqu'à l'appel à la base de données. Une fonction qui ne prend pas de contexte ne peut pas être annulée ni porter une deadline. - Ne stockez jamais un
context.Contextdans un champ de struct. - Ne transmettez jamais un contexte de requête à une goroutine qui survit au handler. Un travail en arrière-plan détaché a besoin de son propre contexte avec son propre timeout, et les valeurs dont il a besoin doivent être copiées explicitement avant le retour du handler.
- La même chose s'applique à tout handle dérivé de la requête — une transaction, une connexion, un accesseur de base de données lié à la requête. L'utiliser après le retour du handler est une utilisation après libération avec un message d'erreur plus sympathique.
Erreurs
- Encapsulez avec
%wet ajoutez ce que l'appelant ne peut pas déjà savoir : l'identifiant, l'opération.fmt.Errorf("chargement de la commande %d : %w", id, err). N'ajoutez pas le nom de la fonction en préfixe ; une pile de ces préfixes devient du bruit. - Comparez avec
errors.Iseterrors.As. Une comparaison directe==casse dès que quelqu'un encapsule. - Traduisez en code de statut de transport exactement à un endroit, à la frontière du handler. Un repository qui retourne un code HTTP a fuité deux couches.
sql.ErrNoRowsest un résultat du domaine, pas un échec. Mappez-le vers le « non trouvé » du domaine à la frontière du repository pour que le service n'importe jamaisdatabase/sql.- Ne jetez jamais une erreur pour satisfaire le compilateur. Si elle est vraiment ignorable, assignez-la à
_avec un commentaire expliquant pourquoi.
Transactions
Ouvrez la transaction au niveau de la couche qui possède l'invariant — généralement le service, jamais le repository, car un repository qui ouvre sa propre transaction ne peut pas être composé dans une transaction plus grande. Passez le handle de transaction vers le bas.
Faites un commit et un rollback sur tous les chemins, y compris en cas de panique. Le rollback après un commit réussi
doit être inoffensif ; c'est ce qui rend defer tx.Rollback() sûr.
Ne faites pas d'E/S à l'intérieur d'une transaction qui n'a pas besoin d'être atomique avec elle. Un appel HTTP à un fournisseur de paiement à l'intérieur d'une transaction ouverte verrouille la base de données pendant la durée d'une panne de quelqu'un d'autre.
Multilocataire
Si le service est multi-locataire, l'identifiant du locataire est appliqué dans le code, pas par la base de données. Chaque requête de repository — lecture et écriture — porte le prédicat du locataire. Une requête qui filtre uniquement par clé primaire retournera volontiers la ligne d'un autre locataire. Dérivez l'identifiant de l'accesseur de contexte que le code utilise déjà, et vérifiez quel accesseur est correct : un service agissant pour le compte d'un sous-locataire en a généralement deux, et le plus évident est souvent le mauvais.
Goroutines
Chaque goroutine a besoin d'une durée de vie connue et d'un propriétaire connu. Avant d'écrire go, répondez : qui attend
son achèvement, comment s'arrête-t-elle, et où va son erreur ? Une goroutine dont l'erreur est ignorée est un
échec silencieux.
Utilisez errgroup quand l'appelant attend. Utilisez un sync.WaitGroup explicite plus un canal d'erreur collecté
quand cela ne convient pas. Un simple go f() dans le traitement d'une requête est presque toujours un défaut.
Tests
Pilotés par tableaux, un t.Run par cas, nommé pour le comportement plutôt que pour l'entrée. Chaque cas
indique son entrée, son attente, et rien d'autre ; la configuration partagée par tous les cas appartient au-dessus
du tableau.
Passez toujours un timeout lors de leur exécution :
go test -count=1 -timeout 60s ./...
-count=1 désactive le cache de résultats, qui autrement signalerait une réussite pour du code que vous venez de
modifier. Le timeout est plus important qu'il n'y paraît : un test en interblocage sans timeout consomme de la mémoire
jusqu'à ce que la machine plante.
Testez le comportement exporté du package. Un test qui accède à des internes non exportés verrouille l'implémentation et échoue à chaque refactorisation honnête.
Lorsqu'un test est instable, il signale une vraie course la plupart du temps. Exécutez-le avec -race avant
de conclure le contraire, et ne le corrigez jamais en ajoutant une attente.
Avant de déclarer terminé
Exécutez le test le plus étroit qui couvre le changement, puis élargissez si un contrat partagé a bougé.
Exécutez golangci-lint run dans le service plutôt qu'une cible make qui pourrait avaler le code de sortie.
Signalez les échecs avec leur sortie au lieu d'affaiblir le test.