Conventions Go : ce que la stdlib a absorbé en 2025-2026

Sommaire (11 parties)

Go 1.21, 1.22, 1.23, 1.24, quatre versions en deux ans, chacune ajoutant quelque chose qui change réellement la façon d'écrire du Go. Pas des features syntaxiques spectaculaires, mais des outils et patterns qui éliminent des problèmes récurrents. Le résultat : les codebases sérieuses de 2025 ressemblent nettement moins à celles de 2022.

Cet article passe en revue ce qui s'est stabilisé comme standard, avec des exemples tirés de mon propre projet. Il dit aussi ce que la stdlib permet maintenant de ne plus importer.

Mise à jour d'octobre 2026 : la section « Ce qui a changé depuis l'écriture de cet article » couvre Go 1.25 à 1.27.

slog, le logger que tu n'as pas besoin d'installer

Depuis Go 1.21, slog est dans la stdlib. Logrus est en mode maintenance (son README le dit) et zap reste très actif. Pour un nouveau projet, la stdlib suffit pour la plupart des besoins, et c'est une dépendance de moins.

Le pattern qui s'est imposé dans les codebases sérieuses : un logger enrichi par opération, pas un logger global. Ça donne des logs structurés sans avoir à répéter les mêmes champs à chaque appel :

// Pattern reconnu : logger enrichi par contexte d'opération
func processJob(ctx context.Context, jobID, model string) {
    log := slog.With("job_id", jobID, "model", model)
    log.Info("starting")
    // ... traitement
    log.Error("failed", "error", err)
}

// Dans les librairies : ne jamais appeler slog.SetDefault()
// C'est le rôle de main.go, une lib qui appelle SetDefault() écrase
// la config de l'application qui l'utilise

Caddy expose un logger slog à ses plugins (Context.Slogger()), mais son logging interne reste zap. L'écosystème n'a pas tranché : zap et logrus restent maintenus et se branchent sur slog.

errors, wrapping systématique et sentinels

fmt.Errorf avec %w est le standard depuis Go 1.13 (2019). En 2025, si tu vois encore du code qui retourne une erreur nue sans contexte, c'est une dette technique. errors.Join (Go 1.20) a réglé le problème des multi-erreurs sans librairie externe.

// fmt.Errorf avec %w, wrapping systématique, sans exception
return fmt.Errorf("create job: %w", err)

// errors.Join pour la validation multi-champs
errs := []error{}
errs = append(errs, validatePrompt(r.Prompt))
errs = append(errs, validateModel(r.Model))
return errors.Join(errs...) // nil si tous nil, combiné sinon

Les sentinel errors ont leur importance pour les cas « not found », mais encore faut-il les utiliser :

var ErrJobNotFound = errors.New("job not found")

// ❌ Anti-pattern encore trop répandu en 2024
func (s *Store) Get(id string) (*Job, error) {
    // ...
    return nil, nil // job absent = nil, nil ← ambigu, impossible à tester proprement
}

// ✅ 2025, explicite et testable avec errors.Is
func (s *Store) Get(id string) (*Job, error) {
    // ...
    return nil, ErrJobNotFound
}

// Côté appelant, propre et sans comparaison de strings
if errors.Is(err, ErrJobNotFound) {
    return http.StatusNotFound, nil
}

ClaudeGate a encore quelques cas nil, nil qui devraient être nil, ErrJobNotFound. C'est exactement le genre de dette qui rend les tests fragiles.

context, la discipline des 10 secondes

Le context est non-négociable depuis longtemps. Ce qui a changé avec Go 1.21 : context.WithoutCancel. Un ajout qui règle un problème réel qu'on contournait avec context.Background() : en perdant toutes les valeurs du contexte parent.

// context.WithoutCancel (Go 1.21), pour les opérations fire-and-forget
// Cas d'usage exact : webhooks, notifications, opérations de fond
// WithoutCancel garde les valeurs du contexte (trace ID, user ID) mais retire aussi toute échéance : on en repose une
webhookCtx, cancelWebhook := context.WithTimeout(context.WithoutCancel(ctx), 30*time.Second)
go func() {
    defer cancelWebhook()
    webhook.Send(webhookCtx, url, payload)
}()
// Sans ça : si le contexte HTTP expire, le webhook est annulé avant d'être envoyé
// Avant Go 1.21 : context.Background(), perd les valeurs du contexte (trace ID, user ID, etc.)

// Timeout sur toutes les opérations externes, sans exception
ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
defer cancel()

Dans ClaudeGate, les webhooks utilisent encore le contexte de la requête HTTP d'origine. Si la requête expire à 30 secondes et que le webhook met 35 secondes à répondre, le webhook est silencieusement annulé. context.WithoutCancel corrige ça.

iter.Seq2, itérateurs natifs, enfin

Go 1.23 a introduit le package iter et le « range over functions ». C'est probablement le changement le plus sous-estimé des versions récentes. Il permet d'exposer un parcours paresseux d'une collection ou d'un curseur de base de données.

// Avant Go 1.23, verbeux et error-prone
rows, err := s.db.QueryContext(ctx, `SELECT id, status, prompt FROM jobs`)
if err != nil {
    return fmt.Errorf("query jobs: %w", err)
}
defer rows.Close()
for rows.Next() {
    var j Job
    if err := rows.Scan(&j.ID, &j.Status, &j.Prompt); err != nil {
        return fmt.Errorf("scan job: %w", err)
    }
    jobs = append(jobs, j)
}

// Go 1.23+, pattern propre, lazy, composable
func (s *Store) Jobs(ctx context.Context) iter.Seq2[*Job, error] {
    return func(yield func(*Job, error) bool) {
        rows, err := s.db.QueryContext(ctx, `SELECT id, status, prompt FROM jobs`)
        if err != nil {
            yield(nil, err)
            return
        }
        defer rows.Close()
        for rows.Next() {
            j := &Job{}
            if err := rows.Scan(&j.ID, &j.Status, &j.Prompt); err != nil {
                yield(nil, err)
                return
            }
            if !yield(j, nil) {
                return // l'appelant a fait break, stop propre
            }
        }
        if err := rows.Err(); err != nil {
            yield(nil, err) // erreur survenue en cours de lecture
        }
    }
}

// Usage, lisible, gestion d'erreur explicite
for j, err := range store.Jobs(ctx) {
    if err != nil {
        return fmt.Errorf("list jobs: %w", err)
    }
    // traiter j
}

L'intérêt ne se limite pas aux requêtes SQL. Tout ce qui était un slice chargé en mémoire d'un coup peut devenir un itérateur lazy. Pour les grandes collections, la mémoire reste celle d'un élément au lieu de croître avec la taille du résultat.

testing, synctest et la fin des time.Sleep

Tu as déjà écrit un test avec time.Sleep(100 * time.Millisecond) pour « laisser le temps à la goroutine » ? C'est du cargo-culting. Le test devient instable sur une machine lente, et inutilement long sur une machine rapide. testing/synctest règle ça. Il est stable depuis Go 1.25 (août 2025). En Go 1.24 il fallait GOEXPERIMENT=synctest, et son ancienne fonction synctest.Run n'existe plus en Go 1.26.

// ❌ Avant, sleep hacky, flaky par nature
go worker.processJob(ctx, "job-1")
time.Sleep(100 * time.Millisecond)
assert.Equal(t, "completed", store.GetStatus("job-1"))

// ✅ Go 1.25+, synctest fait tourner le test dans une « bulle » au temps virtuel
func TestWorker(t *testing.T) {
    synctest.Test(t, func(t *testing.T) {
        go worker.processJob(ctx, "job-1")
        synctest.Wait() // attend que les goroutines de la bulle soient durablement bloquées
        // les assertions sont maintenant déterministes
        assert.Equal(t, "completed", store.GetStatus("job-1"))
    })
}

Les deux autres patterns qui se sont imposés en 2025 :

// Sous-tests parallèles, systématique sur les table-driven tests
func TestValidate(t *testing.T) {
    t.Parallel()
    tests := []struct {
        name    string
        input   string
        wantErr bool
    }{
        {"valid", "claude-3-5-sonnet", false},
        {"empty", "", true},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            t.Parallel()
            err := validateModel(tt.input)
            if (err != nil) != tt.wantErr {
                t.Errorf("got %v, want err=%v", err, tt.wantErr)
            }
        })
    }
}

// t.Cleanup systématique, plus propre que defer dans TestXxx
store := newTestStore(t)
t.Cleanup(func() { store.Close() })

ClaudeGate n'a pas encore t.Parallel() sur ses tests unitaires. C'est rapide à ajouter et ça révèle souvent des races conditions qu'on n'aurait pas vus autrement.

mockery, des mocks générés plutôt qu'écrits à la main

mockery v3 génère les mocks de tes interfaces. Attention : il ne se pilote plus avec des flags dans un //go:generate. Il lit un fichier .mockery.yml, et ses mocks utilisent testify/mock. Le débat testify vs stdlib testing est moins tranché, les nouveaux projets partent souvent sur la stdlib. C'est un argument pour ne générer que les mocks dont tu as vraiment besoin.

type JobStore interface {
    Get(ctx context.Context, id string) (*Job, error)
    Save(ctx context.Context, job *Job) error
}
# .mockery.yml (mockery v3)
packages:
  example.com/jobs:
    interfaces:
      JobStore:
mockery

Le vrai intérêt : les mocks sont versionnés avec le code. Pas de script externe à maintenir, pas de « j'ai oublié de régénérer ». En CI, relancer mockery puis git diff --exit-code vérifie que les mocks sont à jour.

go tool, dépendances de tooling dans go.mod

Go 1.24 a officialisé quelque chose qu'on bricolait depuis des années avec des fichiers tools.go vides. La directive tool de go.mod déclare les outils de dev du projet, et leur version se fige dans les lignes require. On l'ajoute avec une commande, pas à la main :

go get -tool golang.org/x/vuln/cmd/govulncheck@v1.9.0
// go.mod, après la commande
tool golang.org/x/vuln/cmd/govulncheck

require golang.org/x/vuln v1.9.0 // indirect
// Plus de curl | sh dans les Makefiles
go tool govulncheck ./...

Le bénéfice concret : tout le monde utilise la même version de govulncheck. Plus de « ça passe chez moi » parce que quelqu'un a une version plus ancienne que la CI. Les gros outils sont de moins bons candidats. Le projet golangci-lint déconseille go tool (ses dépendances se mélangent aux tiennes) et recommande son binaire officiel.

Ce que la stdlib permet de ne plus importer

Un bon réflexe en 2025 : compter les dépendances directes de ton go.mod et justifier chacune. Il n'y a pas de chiffre magique. Au 28 octobre 2026, le go.mod de Caddy en déclare 55 et celui de Tailscale 165. La vraie question est de savoir si la stdlib fait déjà le travail.

Dépendance ou habitude courante Alternative plus légère
github.com/pkg/errors stdlib errors + fmt.Errorf("%w")
testify/assert dans les nouveaux projets stdlib testing
logrus, zap slog
gorilla/mux net/http routing stdlib (Go 1.22)
cobra pour les petits CLIs flag + sous-commandes manuelles
Docker multi-stage complexes ko pour Go ou docker buildx

La tendance de fond : Go a rattrapé son retard sur le routing HTTP (Go 1.22), le logging (Go 1.21), les itérateurs (Go 1.23). Ce qui était une excuse légitime pour les dépendances tierces il y a 3 ans ne l'est plus.

Ce qui a changé depuis l'écriture de cet article

Trois versions sont sorties depuis août 2025. Voici ce qui touche les conventions ci-dessus.

  • Go 1.25 (août 2025). testing/synctest devient stable avec synctest.Test. sync.WaitGroup.Go simplifie le motif Add, go, Done. Sous Linux, GOMAXPROCS suit la limite CPU du conteneur.
  • Go 1.26 (février 2026). errors.AsType est la version générique et typée de errors.As. go fix est refait : il applique les idiomes récents à ton code.
  • Go 1.27 (août 2026). encoding/json repose sur la nouvelle implémentation v2 (même comportement, messages d'erreur pouvant changer) et le package encoding/json/v2 est disponible. Les méthodes peuvent déclarer leurs propres paramètres de type.

Bilan ClaudeGate

À titre d'exemple concret, voici où en est ClaudeGate par rapport à ces conventions :

Bien aligné :

  • slog utilisé partout
  • Routing stdlib Go 1.22, pas de gorilla/mux
  • modernc.org/sqlite zero-CGO
  • Interface-based design sur les stores
  • errors.Is pour les sentinels
  • Context propagé sur toutes les opérations I/O

Points à améliorer :

  • nil, nil pour « not found » dans le store → devrait être nil, ErrJobNotFound
  • Tests non parallèles : t.Parallel() absent partout
  • govulncheck absent du CI/Makefile
  • context.WithoutCancel pour les webhooks fire-and-forget
  • Version de golangci-lint non épinglée dans la CI

Ce qu'il faut retenir

La vraie tendance 2025 : la stdlib couvre plus de cas qu'avant. La philosophie stdlib-first est revenue en force. Go 1.21 a donné slog, Go 1.22 le routing HTTP, Go 1.23 les itérateurs. Ce n'est pas un hasard, c'est le signal que la stdlib Go est enfin mature pour la plupart des cas d'usage.

Pour les projets existants : pas besoin de tout migrer d'un coup. Commencer par slog (une journée de travail sur une codebase moyenne), ajouter govulncheck en CI (30 minutes), et introduire t.Parallel() sur les nouveaux tests. Le reste suit naturellement.

📄 CLAUDE.md associé

Dans le grand livre du développeur

Un livre gratuit où chaque idée est racontée une seule fois, à sa place, du silicium au jugement humain.

Commentaires (0)