sk-go-service

Implémenter, étendre ou corriger un handler, un service ou un repository dans un backend Go, en gérant la propagation du contexte, l'encapsulation des erreurs, les limites de transaction, le cloisonnement par locataire et les tests pilotés par tableaux.

Qu'est-ce que sk-go-service ?

Ce skill fournit un ensemble de conventions pour travailler sur un service Go en couches, en garantissant la correction sous concurrence et en environnement multi-locataire. Il couvre la gestion du contexte (passage explicite, pas de stockage dans une structure, pas de fuite vers des goroutines qui survivent à la requête), l'encapsulation des erreurs (utilisation de `%w`, `errors.Is`/`As`, traduction en code de transport uniquement à la frontière du handler), les transactions (ouverture au niveau du service, jamais du repository, commit/rollback sur tous les chemins y compris en cas de panique), le cloisonnement multi-locataire (vérification du prédicat dans chaque requête de repository), les goroutines (chaque goroutine doit avoir une durée de vie et un propriétaire connus, utilisation d'`errgroup` ou `sync.WaitGroup`), et les tests (pilotés par tableaux, nommés par comportement, avec timeout et `-race` pour la détection de courses). Utile pour tout développeur Go impliqué dans la maintenance ou l'extension de services backend, ce skill est agnostique de l'IDE/agent mais s'applique naturellement à Claude Code, Cursor ou Codex. Il est basé sur une lecture préalable du code environnant pour identifier les patterns locaux qui prévalent sur les règles générales.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/vanhuydotcom/sk-skills/tree/HEAD/skills/sk-go-service

Installed? Explore more Développement et programmation skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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 ctx comme 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.Context dans 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 %w et 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.Is et errors.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.ErrNoRows est 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 jamais database/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.

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

sk-api

Design and change API contracts (REST, gRPC, protobuf, events) so existing callers keep working, covering resource and method shape, error models, pagination, versioning and the deploy order a breaking change requires. Use when adding or altering an endpoint, message or event, or when judging whether a proposed change breaks a consumer.

sk-code-review

Shows an agent how to design, debug, or review "sk code review" so the concrete output is a code change with a check. The procedure moves through Code review, Establish the diff first, What to look for, in priority order. Use it when a new assignment calls for this craft.

sk-python

Write and debug Python with attention to the traps that produce silent wrong behaviour — mutable defaults, late-binding closures, shallow copies, swallowed exceptions — plus typing, environment and packaging with uv or venv, and pytest structure. Use when writing a Python script, service or library, setting up a Python project, or debugging behaviour that looks impossible.

sk-react

Build and fix React and TypeScript components, covering state placement, effect dependencies, data fetching, list rendering and the re-render traps that cause stale or looping UI. Use when writing or changing a React component or hook, debugging stale data, an infinite render loop or a lost input, or reviewing frontend code.

sk-system-design

Design or evaluate a distributed system from its constraints — service boundaries, synchronous versus event-driven communication, consistency, failure behaviour and capacity — and state the trade-off each choice buys. Use when splitting or merging services, choosing between a call and an event, deciding where data lives, reviewing an architecture proposal, or answering a system design question.

Skills associés