Claude Code pour le scaffolding d'API Go : handlers et services cohérents

Pourquoi les API Go deviennent en désordre quand les patterns ne sont pas fixés tôt

Les API Go commencent généralement propres : quelques endpoints, une ou deux personnes, et tout vit dans la tête de chacun. Puis l'API grandit, les fonctionnalités sont livrées sous pression, et de petites différences s'insinuent. Chacune semble inoffensive, mais ensemble elles ralentissent chaque changement futur.

Un exemple fréquent : un handler décode du JSON dans une struct et renvoie 400 avec un message utile, un autre renvoie 422 avec une forme différente, et un troisième journalise les erreurs dans un format différent. Rien de tout cela ne casse la compilation. Ça crée juste des décisions constantes et de petites réécritures à chaque ajout.

Vous sentez le désordre dans des endroits comme :

• Différents corps d'erreur entre endpoints, donc les clients ont des cas spéciaux.
• Des services qui retournent parfois des erreurs brutes de la base et parfois des erreurs « conviviales ».
• Dérive de noms (CreateUser, AddUser, RegisterUser) qui complique la recherche.
• Validation qui se balade, si bien que les mêmes bugs reviennent.

Par « scaffolding » ici, on entend un modèle répétable pour le nouveau travail : où le code va, ce que fait chaque couche, et à quoi ressemblent les réponses. Il s'agit moins de générer beaucoup de code que de verrouiller une forme cohérente.

Des outils comme Claude peuvent vous aider à scaffolder rapidement de nouveaux endpoints, mais ils restent utiles seulement si vous traitez le pattern comme une règle. Vous définissez les règles, vous révisez chaque diff, et vous exécutez des tests. Le modèle complète les parties standard ; il n'a pas le droit de redéfinir votre architecture.

Choisissez une séparation de couches : handler, service et accès aux données

Une API Go reste facile à faire évoluer quand chaque requête suit le même chemin. Avant de commencer à générer des endpoints, choisissez une séparation de couches et tenez-vous-y.

Responsabilités, gardées simples

Le job du handler est uniquement HTTP : lire la requête, appeler le service et écrire la réponse. Il ne doit pas contenir des règles métier, du SQL, ou de la logique « juste ce cas spécial ».

Le service possède le cas d'utilisation : règles métier, décisions et orchestration entre repositories ou appels externes. Il ne doit pas connaître les préoccupations HTTP comme les codes de statut, les en-têtes ou la manière dont les erreurs sont rendues.

L'accès aux données (repository/store) possède les détails de persistance. Il traduit l'intention du service en SQL/queries/transactions. Il ne doit pas appliquer des règles métier au-delà de l'intégrité des données et ne doit pas façonner les réponses API.

Une checklist de séparation pratique :

• Handler : parser l'input, appeler le service, mapper les erreurs en HTTP, écrire du JSON
• Service : appliquer les règles métier, appeler les repos, retourner des résultats domaine ou des erreurs typées
• Accès aux données : exécuter les requêtes, mapper les lignes en structs, retourner des erreurs de stockage
• Partagé : types d'erreur communs et helpers de réponse
• Aucune couche ne saute une autre (le handler n'appelle jamais le repo directement)

Une règle pour la validation

Choisissez une règle et ne la déformez pas.

Une approche simple :

• Les handlers font la « validation de forme » (champs requis, format basique).
• Les services font la « validation de sens » (permissions, invariants, état).

Exemple : le handler vérifie que email est présent et ressemble à un email. Le service vérifie que l'email est autorisé et n'est pas déjà utilisé.

Ce qui circule entre les couches

Décidez tôt si les services retournent des types domaine ou des DTOs.

Un défaut propre : les handlers utilisent des DTOs request/response, les services utilisent des types domaine, et le handler mappe le domaine vers la réponse. Cela garde le service stable même si le contrat HTTP change.

Si le mapping paraît lourd, gardez la cohérence : faites en sorte que le service retourne un type domaine plus une erreur typée, et laissez le shaping JSON au handler.

Définir une réponse d'erreur standard et une table de codes

Si vous voulez que les endpoints générés semblent écrits par la même personne, verrouillez les réponses d'erreur tôt. La génération est la plus efficace quand le format de sortie est non négociable : une seule forme JSON, une seule table de codes, et une règle sur ce qui est exposé.

Commencez par une unique enveloppe d'erreur que chaque endpoint renvoie en cas d'échec. Gardez-la petite et prévisible :

{
  "code": "validation_failed",
  "message": "One or more fields are invalid.",
  "details": {
    "fields": {
      "email": "must be a valid email address",
      "age": "must be greater than 0"
    }
  },
  "request_id": "req_01HR..."
}

Utilisez code pour les machines (stable et prévisible) et message pour les humains (court et sûr). Mettez les données structurées optionnelles dans details. Pour la validation, une simple map details.fields est facile à générer et simple pour les clients à afficher à côté des champs.

Ensuite, rédigez une table de correspondance des codes HTTP et tenez-vous-y. Moins il y a de débat par endpoint, mieux c'est. Si vous voulez à la fois 400 et 422, explicitez la séparation :

• bad_json -> 400 Bad Request (JSON malformé)
• validation_failed -> 422 Unprocessable Content (JSON bien formé, champs invalides)
• not_found -> 404 Not Found
• conflict -> 409 Conflict (clé dupliquée, mismatch de version)
• unauthorized -> 401 Unauthorized
• forbidden -> 403 Forbidden
• internal -> 500 Internal Server Error

Décidez ce que vous loggez vs ce que vous retournez. Une bonne règle : les clients reçoivent un message sûr et un request ID ; les logs contiennent l'erreur complète et le contexte interne (SQL, payloads upstream, IDs utilisateur) que vous ne voudriez jamais divulguer.

Enfin, standardisez request_id. Acceptez un header ID entrant si présent (depuis une gateway), sinon générez-en un au bord (middleware). Attachez-le au context, incluez-le dans les logs et retournez-le dans chaque réponse d'erreur.

Arborescence et noms de fichiers qui rendent la génération prévisible

Si vous voulez que le scaffolding reste cohérent, la structure de dossiers doit être ennuyeuse et répétable. Les générateurs suivent des motifs qu'ils peuvent reconnaître, mais ils dévient quand les fichiers sont éparpillés ou que les noms changent selon la feature.

Choisissez une convention de nommage et ne la déformez pas. Choisissez un mot pour chaque chose et tenez-le : handler, service, repo, request, response. Si la route est POST /users, nommez les fichiers et types autour de users et create (pas parfois register, parfois addUser).

Une disposition simple qui correspond aux couches habituelles :

internal/
  httpapi/
    handlers/
    users_handler.go
  services/
    users_service.go
  data/
    users_repo.go
  apitypes/
    users_types.go

Décidez où vivent les types partagés, car c'est souvent là que les projets deviennent en désordre. Une règle utile :

• Les types request/response API vivent dans internal/apitypes (correspondent au JSON et aux besoins de validation).
• Les types domaine vivent plus près de la couche service (correspondent aux règles métier).

Si un type contient des tags JSON et est conçu pour les clients, traitez-le comme un type API.

Gardez les dépendances des handlers minimales et explicitez cette règle :

• Handlers n'importent que : routing/http, context, apitypes et services
• Services importent : types domaine et accès aux données
• Accès aux données importent : driver DB et helpers de requête
• Aucun handler n'importe directement le package database

Rédigez un petit document de pattern à la racine du repo (un Markdown simple suffit). Incluez l'arbre de dossiers, les règles de nommage et un petit flux d'exemple (handler -> service -> repo, plus quel fichier contient chaque morceau). C'est la référence exacte que vous collez dans votre générateur pour que les nouveaux endpoints respectent la structure à chaque fois.

Créez un endpoint de référence qui fixe le pattern

Avant de générer dix endpoints, créez un endpoint que vous approuvez. C'est la référence : le fichier que vous pouvez pointer et dire « Le nouveau code doit ressembler à ça. » Vous pouvez l'écrire depuis zéro ou refactoriser un existant jusqu'à ce qu'il corresponde.

Gardez le handler mince. Un mouvement qui aide beaucoup : placez une interface entre le handler et le service pour que le handler dépende d'un contrat, pas d'une implémentation concrète.

Ajoutez de petits commentaires dans l'endpoint de référence uniquement là où le code généré pourrait buter. Expliquez des décisions (pourquoi 400 vs 422, pourquoi create renvoie 201, pourquoi vous cachez les erreurs internes derrière un message générique). Évitez les commentaires qui ne font que répéter le code.

Une fois l'endpoint de référence correct, extrayez des helpers pour réduire les chances de dérive sur chaque nouveau endpoint. Les helpers les plus réutilisables sont souvent :

• Binder le JSON et gérer les corps malformés
• Valider l'input et retourner des erreurs de champ
• Écrire les réponses JSON de manière cohérente
• Mapper les erreurs domaine en codes HTTP

Voici à quoi peut ressembler un « handler mince + interface » en pratique :

type UserService interface {
	CreateUser(ctx context.Context, in CreateUserInput) (User, error)
}

func (h *Handler) CreateUser(w http.ResponseWriter, r *http.Request) {
	var in CreateUserRequest
	if err := BindJSON(r, &in); err != nil {
		WriteError(w, ErrBadJSON) // 400: malformed JSON
		return
	}
	if err := Validate(in); err != nil {
		WriteError(w, err) // 422: validation details
		return
	}
	user, err := h.svc.CreateUser(r.Context(), in.ToInput())
	if err != nil {
		WriteError(w, err)
		return
	}
	WriteJSON(w, http.StatusCreated, user)
}

Verrouillez-le avec quelques tests (même un petit table test pour le mapping d'erreurs). La génération est plus fiable quand elle a une cible propre à imiter.

Étape par étape : faire générer par Claude un endpoint qui correspond

La cohérence commence par ce que vous collez et ce que vous interdisez. Pour un nouvel endpoint, fournissez deux choses :

1. Votre endpoint de référence (l'exemple « parfait »)
2. Une courte note de pattern qui nomme les packages, fonctions et helpers qu'il doit suivre

1) Fournir le contexte d'abord (référence + règles)

Incluez le handler, la méthode service, les types request/response et tout helper partagé utilisé par l'endpoint. Puis énoncez le contrat en termes simples :

• Route + méthode (exemple : POST /v1/widgets)
• Champs JSON de la requête (requis vs optionnels)
• Forme JSON de la réponse
• Cas d'erreur et codes HTTP
• Fichiers que vous attendez en sortie (et uniquement ceux-ci)

Soyez explicite sur ce qui doit correspondre : nommage, chemins de package et fonctions helper (WriteJSON, BindJSON, WriteError, votre validator).

2) Demander la sortie dans la forme exacte voulue

Une invite serrée empêche les refactorings « utiles ». Par exemple :

Using the reference endpoint below and the pattern notes, generate a new endpoint.
Contract:
- Route: POST /v1/widgets
- Request: {"name": string, "color": string}
- Response: {"id": string, "name": string, "color": string, "createdAt": string}
- Errors: invalid JSON -> 400; validation -> 422; duplicate name -> 409; unexpected -> 500
Output ONLY these files:
1) internal/http/handlers/widgets_create.go
2) internal/service/widgets.go (add method only)
3) internal/types/widgets.go (add types only)
Do not change: router setup, existing error format, existing helpers, or unrelated files.
Must use: package paths and helper functions exactly as in the reference.

Si vous utilisez des tests, demandez-les explicitement (et nommez le fichier de test). Sinon le modèle peut les sauter ou inventer une configuration de test.

Faites un rapide contrôle de diff après génération. Si des helpers partagés, l'enregistrement du router, ou votre réponse d'erreur standard ont été modifiés, rejetez la sortie et réitérez les règles « ne pas changer » plus strictement.

Un modèle d'invite réutilisable pour des scaffolds d'endpoints cohérents

La sortie n'est cohérente que si l'entrée l'est. Le moyen le plus rapide d'éviter du code « presque correct » est de réutiliser une invite unique à chaque fois, avec un petit snapshot de contexte tiré de votre repo.

Modèle d'invite

Collez, remplissez et adaptez les placeholders :

You are editing an existing Go HTTP API.

CONTEXT
- Folder tree (only the relevant parts):
  <paste a small tree: internal/http, internal/service, internal/repo, etc>
- Key types and patterns:
  - Handler signature style: <example>
  - Service interface style: <example>
  - Request/response DTOs live in: <package>
- Standard error response JSON:
  {
    "error": {
      "code": "invalid_argument",
      "message": "...",
      "details": {"field": "reason"}
    }
  }
- Status code map:
  invalid_json -> 400
  invalid_argument -> 422
  not_found -> 404
  conflict -> 409
  internal -> 500

TASK
Add a new endpoint: <METHOD> <PATH>
- Handler name: <Name>
- Service method: <Name>
- Request JSON example:
  {"name":"Acme"}
- Success response JSON example:
  {"id":"123","name":"Acme"}

CONSTRAINTS
- No new dependencies.
- Keep functions small and single-purpose.
- Match existing naming, folder layout, and error style exactly.
- Do not refactor unrelated files.

ACCEPTANCE CHECKS
- Code builds.
- Existing tests pass (add tests only if the repo already uses them for handlers/services).
- Run gofmt on changed files.

FINAL INSTRUCTION
Before writing code, list any assumptions you must make. If an assumption is risky, ask a short question instead.

Ceci fonctionne car cela force trois choses : un bloc de contexte (ce qui existe), un bloc de contraintes (ce qu'il ne faut pas faire), et des exemples JSON concrets (pour que les formes ne dérivent pas). L'instruction finale est votre filet de sécurité : si le modèle est incertain, il doit demander avant d'engager des changements.

Exemple réaliste : ajouter un endpoint Create sans casser le style

Supposons que vous vouliez ajouter un endpoint « Create project ». Le but est simple : accepter un nom, appliquer quelques règles, le stocker et retourner un nouvel ID. La difficulté est de conserver la séparation handler-service-repo et la même forme d'erreur que vous utilisez déjà.

Un flux cohérent ressemble à ceci :

• Handler : binder le JSON, faire une validation basique, appeler le service
• Service : appliquer les règles métier (unicité, etc.), appeler le repo, retourner un résultat domaine
• Repo : écrire dans Postgres, retourner l'ID généré

Voici la requête que le handler accepte :

{ "name": "Roadmap", "owner_id": "u_123" }

En cas de succès, retourner 201 Created. L'ID doit provenir d'un seul endroit à chaque fois. Par exemple, laissez Postgres le générer et faites en sorte que le repo le retourne :

{ "id": "p_456", "name": "Roadmap", "owner_id": "u_123", "created_at": "2026-01-09T12:34:56Z" }

Deux chemins d'échec réalistes :

Si la validation échoue (nom manquant ou trop court), retournez une erreur au niveau des champs en utilisant votre forme standard et le code choisi :

{ "error": { "code": "VALIDATION_ERROR", "message": "Invalid request", "details": { "name": "must be at least 3 characters" } } }

Si le nom doit être unique par owner et que le service trouve déjà un projet, retournez 409 Conflict :

{ "error": { "code": "PROJECT_NAME_TAKEN", "message": "Project name already exists", "details": { "name": "Roadmap" } } }

Une décision qui garde le pattern propre : le handler vérifie « est-ce que la requête a la bonne forme ? » tandis que le service possède « est-ce permis ? ». Cette séparation rend les endpoints générés prévisibles.

Erreurs courantes qui cassent la cohérence (et comment les éviter)

Le moyen le plus rapide de perdre la cohérence est de laisser le générateur improviser.

Une dérive fréquente est une nouvelle forme d'erreur. Un endpoint renvoie {error: "..."}, un autre {message: "..."}, un troisième ajoute un objet imbriqué. Corrigez cela en gardant une seule enveloppe d'erreur et une table de codes en un seul endroit, puis exigez que les nouveaux endpoints les réutilisent via import path et nom de fonction. Si le générateur propose un nouveau champ, traitez-le comme une demande de changement d'API, pas comme une commodité.

Une autre dérive est l'alourdissement des handlers. Ça commence petit : valider, puis vérifier les permissions, puis requêter la DB, puis brancher sur des règles métier. Bientôt chaque handler est différent. Gardez une règle : les handlers traduisent HTTP en inputs/outputs typés ; les services possèdent les décisions ; l'accès aux données possède les requêtes.

Les mismatches de nommage s'accumulent aussi. Si un endpoint utilise CreateUserRequest et un autre NewUserPayload, vous perdrez du temps à chasser les types et écrire des adaptateurs. Choisissez un schéma de nommage et rejetez les nouveaux noms sauf raison forte.

Ne renvoyez jamais d'erreurs brutes de la base aux clients. En plus de divulguer des détails, cela crée des messages et des codes incohérents. Enveloppez les erreurs internes, loggez la cause et retournez un code public stable.

Évitez d'ajouter des bibliothèques "juste pour la commodité". Chaque validateur, helper de router ou package d'erreurs devient un style à maintenir.

Garde-fous qui empêchent la plupart des cassures :

• Exiger que les nouveaux endpoints réutilisent les types d'erreur et helpers existants.
• Garder les handlers sans règles métier ni accès DB direct.
• Imposer une convention de nommage pour les structs request/response.
• Mapper les erreurs internes vers des codes publics, jamais les erreurs brutes.
• Ajouter des dépendances seulement avec une raison écrite et claire.

Si vous ne pouvez pas diff deux endpoints et voir la même forme (imports, flux, gestion d'erreur), resserrez l'invite et régénérez avant de merger.

Checklist rapide avant de merger un endpoint généré

Avant de merger quoi que ce soit de généré, vérifiez d'abord la structure. Si la forme est correcte, les bugs logiques sont plus faciles à repérer.

Checks de structure :

• Le flux du handler est cohérent : bind input, validate, appeler le service, mapper les erreurs domaine en HTTP, écrire la réponse.
• Le code service contient uniquement des règles métier : pas de HTTP ou JSON.
• Les réponses de succès correspondent au style maison (enveloppe partagée partout ou JSON direct partout).
• Les réponses d'erreur sont uniformes : mêmes champs JSON, mêmes codes, même comportement request_id.
• Le nommage et le placement sont ennuyeux : noms de fichiers, fonctions et routes correspondent aux endpoints existants, et tout est gofmt-formatté.

Checks de comportement :

• Exécutez les tests et ajoutez au moins un petit test pour une nouvelle branche du handler/service.
• Confirmez que les échecs de validation retournent le même code et statut que des endpoints similaires.
• Déclenchez une erreur service connue (par ex. not found ou conflict) et confirmez le statut HTTP et la forme JSON.
• Cherchez des restes de copier-coller : mauvaise route, mauvais message de log, noms DTOs mismatched.
• Build et lancez le serveur localement une fois pour valider le wiring et les imports.

Étapes suivantes : standardisez le pattern, puis montez la génération en sécurité

Traitez votre pattern comme un contrat partagé, pas une préférence. Gardez le doc « comment on build les endpoints » proche du code, et maintenez un endpoint de référence qui montre l'approche de bout en bout.

Montez la génération par petits lots. Générez 2 à 3 endpoints qui couvrent différents cas (une lecture simple, une création avec validation, une mise à jour avec un cas not-found). Puis arrêtez-vous et affinez. Si les revues détectent sans cesse la même dérive de style, mettez à jour le doc baseline et l'endpoint de référence avant de générer davantage.

Une boucle à répéter :

• Écrivez la baseline : noms de fichiers, noms de fonctions, structs request/response, codes d'erreur et où la validation se passe.
• Gardez un endpoint « golden » et mettez-le à jour en premier quand le pattern change.
• Génèrez en batch quelques endpoints, révisez la cohérence, puis ajustez l'invite et le doc de pattern.
• Refactorez les endpoints anciens par lots et gardez un plan de rollback si le comportement change.
• Suivez une métrique pendant une semaine : temps pour ajouter un endpoint, taux de bugs après merge, ou temps de revue.

Si vous voulez une boucle build-review plus serrée, une plateforme vibe-coding comme Koder.ai peut vous aider à scaffolder et itérer rapidement dans un workflow chat-driven, puis exporter le code une fois qu'il correspond à votre standard. L'outil importe moins que la règle : votre baseline doit rester maîtresse.