🟩 Go — Guide PRO — Backend • CLI • Concurrency • Cloud

Build standard

go build ./cmd/api
go build ./...
go run ./cmd/api

Build avec métadonnées

go build -ldflags="-X main.version=1.0.0 -X main.commit=abc123 -X main.buildDate=2026-03-19" ./cmd/api

Injecter version, commit et date de build est très utile pour le support, les logs de démarrage, les endpoints de diagnostic et le rollback.

Build reproductible

• Version Go fixée.
• go.mod et go.sum propres.
• Build lancé de manière identique en CI et local si besoin.

Cross-compilation

GOOS=linux GOARCH=amd64 go build -o bin/api-linux-amd64 ./cmd/api
GOOS=linux GOARCH=arm64 go build -o bin/api-linux-arm64 ./cmd/api
GOOS=windows GOARCH=amd64 go build -o bin/api.exe ./cmd/api
GOOS=darwin GOARCH=arm64 go build -o bin/api-darwin-arm64 ./cmd/api

Pourquoi Go est fort ici

• Cross-build très simple.
• Très pratique pour agents, CLI, services edge, builds multi-arch.
• Intégration naturelle dans les pipelines release.

Binaires statiques

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o bin/api ./cmd/api

Avec CGO_ENABLED=0, beaucoup d’applications Go peuvent produire un binaire très autonome, particulièrement pratique pour les images minimales, les déploiements simplifiés et les environnements très verrouillés.

Avantages

• Moins de dépendances runtime système.
• Très bon pour scratch/distroless.
• Déploiement simplifié.
• Surface d’attaque réduite.

Attention

• Certains usages de CGO ou dépendances natives empêchent ou compliquent le full static.
• Les besoins TLS/certificats/CA doivent être pensés côté image.
• Il faut valider le comportement réel en container.

Flags fréquents

-ldflags="-s -w"

Ces flags réduisent la taille en supprimant une partie des symboles et informations de debug. À utiliser selon votre politique de debug et vos besoins.

Docker multi-stage : pattern standard

FROM golang:1.25 AS builder
WORKDIR /app

COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
    go build -ldflags="-s -w" -o /out/api ./cmd/api

Le premier stage sert à compiler. Il contient toolchain, modules et code source. Le runtime final ne garde que l’exécutable et les éléments strictement nécessaires.

Pourquoi c’est le bon pattern

• Image finale plus petite.
• Moins de surface d’attaque.
• Toolchain absente de l’image runtime.
• Build cache mieux exploitable.

Ordre optimal des couches

1. copier go.mod et go.sum
2. télécharger les modules
3. copier le code
4. compiler

Distroless : runtime minimal

FROM gcr.io/distroless/static-debian12
WORKDIR /app
COPY --from=builder /out/api /app/api

USER nonroot:nonroot
EXPOSE 8080
ENTRYPOINT ["/app/api"]

Une image distroless supprime presque tout ce qui n’est pas nécessaire à l’exécution. Cela réduit la taille, la surface d’attaque et la tentation de “bricoler” en prod dans le conteneur.

Distroless vs scratch

Configuration runtime

Une application Go bien déployée lit sa configuration depuis des variables d’environnement ou des fichiers montés, la valide au startup, puis garde un runtime stable et explicite.

type Config struct {
    HTTPPort string
    DatabaseDSN string
    LogLevel string
}

Bonnes pratiques

• Valider tôt.
• Ne pas dépendre d’un état mutable caché.
• Différencier secrets et config non sensible.
• Tracer la version applicative au démarrage.

Secrets

• Ne jamais hardcoder dans l’image.
• Utiliser secrets manager, variables injectées ou mounts sécurisés.
• Ne jamais logguer un secret.
• Limiter les privilèges d’accès.

Pipeline CI/CD typique

go version
go mod tidy
git diff --exit-code go.mod go.sum
go fmt ./...
go vet ./...
golangci-lint run
go test ./...
go test -race ./...
go build ./cmd/api
docker build -t myapp:${GIT_SHA} .
trivy image myapp:${GIT_SHA}

Étapes utiles

• lint et formatage
• tests unitaires
• race detector si compatible timing pipeline
• build
• scan image
• push registry
• deploy staging puis prod

Qualités d’un bon pipeline

• rapide mais fiable
• reproductible
• échec explicite
• trace le commit et la version
• évite les différences cachées entre branches et environnements

Kubernetes : intégration naturelle

Les services Go s’intègrent très bien à Kubernetes grâce à leur démarrage rapide, leur faible overhead runtime et leur capacité à exposer facilement health checks, metrics et shutdown propre.

livenessProbe:
  httpGet:
    path: /healthz
    port: 8080

readinessProbe:
  httpGet:
    path: /readyz
    port: 8080

Ce qu’il faut exposer

• /healthz ou équivalent
• /readyz pour indiquer la disponibilité réelle
• logs structurés stdout/stderr
• métriques si observabilité avancée

Points clés K8s

• gérer SIGTERM et shutdown propre
• ne pas considérer readiness et liveness comme identiques
• prévoir ressources CPU/mémoire réalistes
• utiliser des images non-root

Rollout et exploitation

• rolling update prudent
• readiness avant prise de trafic
• graceful shutdown avant arrêt complet
• rollback simple si la version dégrade

Ce qu’il faut observer après déploiement

• latence
• erreurs HTTP / métiers
• consommation CPU/mémoire
• timeouts / retries
• nombre de goroutines

Logs et métriques indispensables

• version et commit au démarrage
• erreurs critiques structurées
• health/readiness status
• compteurs de requêtes / jobs / erreurs
• temps de réponse et saturation

Hardening minimal recommandé

• image minimale
• utilisateur non-root
• dépendances scannées
• ports et permissions minimaux
• pas d’outils inutiles dans l’image runtime

USER nonroot:nonroot

Supply chain

• verrouiller versions critiques
• scanner dépendances Go
• scanner images
• générer SBOM si votre chaîne l’exige

Outils utiles

govulncheck ./...
trivy image myapp:latest

Éviter

• images builder utilisées en prod
• shells et packages inutiles
• secrets dans l’image
• comptes root par défaut

Ce que montre cet exemple

• multi-stage build
• binaire statique
• runtime distroless
• non-root user
• health/readiness endpoints
• graceful shutdown sur signaux
• version injectée au build

Extensions naturelles

• ajouter métriques Prometheus
• ajouter tracing
• ajouter endpoint version
• ajouter Helm chart / manifests K8s
• ajouter pipeline scan + signature

database/sql : abstraction standard

db, err := sql.Open("postgres", dsn)
if err != nil {
    return err
}
defer db.Close()

sql.Open ne garantit pas qu’une connexion réelle soit immédiatement établie. Il prépare un handle de pool. Pour vérifier rapidement la connectivité, on utilise généralement PingContext.

ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()

if err := db.PingContext(ctx); err != nil {
    return fmt.Errorf("ping db: %w", err)
}

Pourquoi connaître la stdlib même avec ORM

• Comprendre le pool réel.
• Diagnostiquer les saturations et attentes.
• Maîtriser les transactions et le contexte.
• Savoir quoi se passe sous GORM/sqlx.

Objets importants

• *sql.DB : handle de pool, pas connexion unique.
• *sql.Tx : transaction.
• *sql.Rows : jeu de résultats multi-lignes.
• *sql.Row : une ligne logique.
• *sql.Stmt : statement préparé.

Lire une ligne

row := db.QueryRowContext(ctx,
    "select id, email from users where id = $1",
    id,
)

var u User
if err := row.Scan(&u.ID, &u.Email); err != nil {
    return User{}, fmt.Errorf("scan user: %w", err)
}

Lire plusieurs lignes

rows, err := db.QueryContext(ctx,
    "select id, email from users order by id desc limit 100",
)
if err != nil {
    return nil, fmt.Errorf("query users: %w", err)
}
defer rows.Close()

Boucle de scan

var users []User

for rows.Next() {
    var u User
    if err := rows.Scan(&u.ID, &u.Email); err != nil {
        return nil, fmt.Errorf("scan row: %w", err)
    }
    users = append(users, u)
}

if err := rows.Err(); err != nil {
    return nil, fmt.Errorf("rows error: %w", err)
}

Pièges

• Oublier defer rows.Close().
• Oublier rows.Err() après la boucle.
• Scanner dans un mauvais ordre.
• Faire un select * fragile si le schéma bouge.

Transaction propre

tx, err := db.BeginTx(ctx, nil)
if err != nil {
    return err
}
defer tx.Rollback()

_, err = tx.ExecContext(ctx,
    "update accounts set balance = balance - $1 where id = $2",
    amount, fromID,
)
if err != nil {
    return fmt.Errorf("debit source: %w", err)
}

_, err = tx.ExecContext(ctx,
    "update accounts set balance = balance + $1 where id = $2",
    amount, toID,
)
if err != nil {
    return fmt.Errorf("credit target: %w", err)
}

if err := tx.Commit(); err != nil {
    return fmt.Errorf("commit transfer: %w", err)
}

Règles essentielles

• Toujours Rollback() en defer.
• Utiliser le même ctx sur toutes les opérations de la transaction.
• Garder les transactions courtes.
• Éviter d’y mettre des appels réseau externes si possible.

Ce qu’il faut éviter

• Faire des calculs lents dans la transaction.
• Attendre un service HTTP tiers pendant qu’un verrou DB est tenu.
• Oublier qu’une transaction consomme plus longtemps une connexion du pool.

Réglage du pool

db.SetMaxOpenConns(25)
db.SetMaxIdleConns(25)
db.SetConnMaxLifetime(30 * time.Minute)
db.SetConnMaxIdleTime(5 * time.Minute)

Ce que contrôlent ces paramètres

Pourquoi le tuning est critique

• Trop bas : attente, latence et saturation côté app.
• Trop haut : pression excessive sur le SGBD.
• Durées mal réglées : connexions vieillissantes, effets de LB, timeouts réseau, fuites latentes.

Stats du pool

stats := db.Stats()

fmt.Println(stats.OpenConnections)
fmt.Println(stats.InUse)
fmt.Println(stats.Idle)
fmt.Println(stats.WaitCount)
fmt.Println(stats.WaitDuration)

sqlx : confort au-dessus de database/sql

sqlx conserve l’esprit SQL explicite tout en réduisant le code de mapping manuel : scan dans structs, requêtes nommées, helpers pratiques. C’est un excellent compromis pour beaucoup de projets Go.

type User struct {
    ID    int64  `db:"id"`
    Email string `db:"email"`
}

var users []User
err := db.SelectContext(ctx, &users,
    "select id, email from users where active = true",
)

Avantages

• Moins de boilerplate de scan.
• Toujours très proche du SQL réel.
• Bon équilibre entre contrôle et productivité.

Attention

• Il faut toujours comprendre database/sql dessous.
• Le tuning du pool et la gestion du contexte restent inchangés.
• Les erreurs SQL et transactions exigent toujours la même discipline.

GORM : ORM plus haut niveau

GORM apporte migrations partielles, modèles, hooks, query builder, associations et productivité rapide pour certains projets. Il peut être pertinent, mais son usage doit rester conscient et observé.

type User struct {
    ID    uint
    Email string
    Admin bool
}

var user User
if err := db.WithContext(ctx).First(&user, id).Error; err != nil {
    return err
}

Quand GORM peut être utile

• Équipe habituée aux ORMs.
• CRUD applicatif rapide.
• Projet interne avec productivité prioritaire.

Quand rester prudent

• Requêtes complexes ou fortement optimisées.
• Besoin de comprendre précisément le SQL émis.
• Tuning très fin et sensibilité forte aux plans d’exécution.

Migrations

Les migrations doivent être versionnées, idempotentes dans leur logique d’exécution attendue, testées en environnement proche du réel et intégrées à la chaîne CI/CD ou au processus de déploiement.

migrations/
  0001_init.sql
  0002_add_users.sql
  0003_add_index_users_email.sql

Bonnes pratiques

• Une migration = une évolution claire.
• Nommer explicitement les objets créés.
• Séparer schéma et data migrations si besoin.
• Tester les migrations sur copie ou environnement de staging.

Ce qu’il faut surveiller

• Verrous longs sur grosses tables.
• Création d’index coûteuse.
• Ordre de déploiement app / schéma.
• Compatibilité backward/forward lors des déploiements progressifs.

Context sur toutes les opérations

rows, err := db.QueryContext(ctx, query, args...)
if err != nil {
    return nil, fmt.Errorf("query users: %w", err)
}

Erreurs à catégoriser

• not found logique
• contrainte d’unicité
• timeout / cancellation
• connexion / réseau / auth DB
• erreur interne inattendue

Exemple de wrapping sain

u, err := repo.FindByID(ctx, id)
if err != nil {
    return User{}, fmt.Errorf("load user %d: %w", id, err)
}

Mapping utile

• Not found → erreur métier claire ou 404 plus haut.
• Contrainte unique → conflit / validation.
• Timeout → métrique de saturation / 504 éventuel.
• DB down → 500 / alerte / dégradation contrôlée.

Perf : où regarder en premier

• temps d’attente du pool
• requêtes lentes
• nombre de lignes lues
• transactions trop longues
• absence ou mauvaise qualité d’index
• surcoût ORM / mapping inutile

stats := db.Stats()
_ = stats.WaitCount
_ = stats.WaitDuration

Observabilité DB utile

• latence par requête logique
• temps d’attente du pool
• erreurs par type
• compteur de transactions
• requêtes lentes avec seuil

Ce que montre cet exemple

• pool tuning explicite
• QueryRowContext
• wrapping d’erreurs
• transaction courte et propre
• usage cohérent du context

Améliorations possibles

• ajouter instrumentation metrics/traces
• mapper certaines erreurs SQL en erreurs métier
• ajouter statements préparés ciblés
• intégrer sqlx ou un driver plus spécialisé

Architecture idiomatique d’une application Go

/cmd/api/main.go              # entrypoint
                            /internal/
                            app/                        # bootstrap wiring
                            http/                       # handlers, middleware, routing
                            service/                    # business logic
                            domain/                     # entities, interfaces
                            store/                      # db/repositories
                            jobs/                       # async workers
                            config/                     # typed config
                            /pkg/                         # optional shared libraries
                            /migrations/
                            /deploy/
                            /scripts/
                            /testdata/

Règles saines

• main.go minimal : bootstrap seulement.
• Interfaces là où elles sont consommées, pas partout “par principe”.
• Domain logic découplée du transport HTTP/gRPC.
• Context passé en paramètre pour I/O, timeouts, trace propagation.
• Config typée, validée au startup.
• Observabilité native dès le départ.

Flow d’exécution recommandé

Erreurs à éviter

• Mélanger SQL, logique métier et sérialisation JSON dans le même fichier.
• Créer 200 interfaces inutiles sans bénéfice réel.
• Abuser des packages “utils” fourre-tout.
• Masquer les erreurs réelles sous une couche générique trop tôt.
• Lancer des goroutines sans owner, sans contexte ni stratégie d’arrêt.

Interfaces : l’un des super-pouvoirs de Go

type UserStore interface {
                            FindByID(ctx context.Context, id int64) (User, error)
                            Save(ctx context.Context, u User) error
                            }

                            type Service struct {
                            store UserStore
                            }

                            func NewService(store UserStore) Service {
                            return Service{store: store}
                            }

Pourquoi c’est puissant

• Découplage du stockage, du transport, des tests.
• Mocking possible sans framework lourd.
• API lisible si les interfaces sont petites et ciblées.
• Le contrat est comportemental, non hiérarchique.

Concurrence : l’ADN opérationnel de Go

Le modèle de concurrence Go repose sur les goroutines, les channels, le scheduler runtime et le mot-clé select. L’idée n’est pas seulement de “faire du parallèle”, mais d’exprimer des workflows concurrents de manière lisible : fan-out, fan-in, pipelines, workers, cancellation, timeout, backpressure, orchestration de tâches réseau et I/O.

func worker(ctx context.Context, id int, jobs <-chan int, results chan<- int) {
                            for {
                            select {
                            case <-ctx.Done():
                            return
                            case job, ok := <-jobs:
                            if !ok {
                            return
                            }
                            results <- job * 2
                            }
                            }
                            }

Points d’attention critiques

• Chaque goroutine doit avoir un owner et une stratégie de fin de vie.
• Channels : définir clairement qui écrit, qui ferme, qui lit.
• Buffering : utile mais ne doit pas masquer un problème de débit.
• Context : obligatoire pour tout ce qui touche I/O, RPC, DB, HTTP.
• Race conditions : exécuter régulièrement go test -race.
• select default : à utiliser avec prudence pour ne pas créer de busy loop.

Performance : comment penser “Go”

• Mesurer avant d’optimiser.
• Regarder allocations, GC pressure, contention, lock hot spots, blocking I/O.
• Comprendre ce qui échappe au stack et part au heap.
• Réduire copies inutiles, allocations transitoires, transformations JSON superflues.
• Pooler avec parcimonie, seulement quand le profiling justifie.

func BenchmarkParser(b *testing.B) {
                            payload := []byte(`{"name":"alice","email":"a@example.com"}`)
                            for i := 0; i < b.N; i++ {
                            var v map[string]any
                            if err := json.Unmarshal(payload, &v); err != nil {
                            b.Fatal(err)
                            }
                            }
                            }

Toolbox perf

go test -bench=. -benchmem ./...
                            go test -cpuprofile=cpu.out ./...
                            go test -memprofile=mem.out ./...
                            go tool pprof cpu.out
                            go tool pprof mem.out

Variables et répertoires importants

• GOROOT : emplacement de l’installation Go. Souvent géré automatiquement.
• GOPATH : espace de travail historique ; toujours utile pour certains bins et caches, mais plus central pour les projets modernes.
• GOMODCACHE : cache des dépendances téléchargées.
• PATH : doit inclure le dossier des exécutables outils installés.
• GOOS / GOARCH : cross-compilation.

Philosophie recommandée

Modules : la base du monde Go moderne

Le système de modules permet de gérer les dépendances sans dépendre d’une arborescence globale de type ancien GOPATH/src/.... Chaque projet possède son fichier go.mod qui décrit l’identité du module, la version Go visée et les dépendances nécessaires.

module github.com/acme/myapp

                            go 1.25

                            require (
                            github.com/go-chi/chi/v5 v5.2.1
                            github.com/jackc/pgx/v5 v5.7.2
                            )

Rôle des fichiers

• go.mod : identité du module, version Go, dépendances déclarées.
• go.sum : checksums de sécurité et de reproductibilité.
• vendor/ : optionnel selon politique projet ou contraintes d’environnement.

Workspaces et multi-modules

Sur des projets plus gros, ou des monorepos, un go.work peut aider à travailler simultanément sur plusieurs modules locaux sans avoir à publier ou remplacer manuellement chaque dépendance.

go work init ./service-a ./service-b ./shared-lib
                            go work use ./tooling

Bonnes pratiques

• Éviter les dépendances inutiles “juste au cas où”.
• Exécuter go mod tidy régulièrement.
• Réviser les dépendances indirectes lors des mises à jour.
• Ne pas committer un go.mod instable ou “sale”.

Commandes de diagnostic très utiles

go env GOMOD
                            go env GOPATH
                            go env GOMODCACHE
                            go list ./...
                            go test -run TestName ./...
                            go test -cover ./...
                            go clean -cache -testcache -modcache

Lecture opérationnelle

• go env aide énormément quand un poste local “ne se comporte pas comme la CI”.
• go mod tidy doit faire partie de l’hygiène de routine.
• go clean -modcache est précieux si un cache corrompu ou incohérent perturbe le build.
• go test -race est indispensable dès que le code concurrent devient sérieux.

IDE / éditeur

• VS Code + Go extension : très bon compromis, léger, largement adopté.
• GoLand : expérience premium, refactoring et navigation puissants.
• Vim/Neovim : très efficace si l’environnement LSP est bien préparé.

Réglages à activer

• formatage à la sauvegarde
• organisation auto des imports
• exécution rapide des tests
• navigation vers définitions et implémentations
• diagnostics linter visibles dans l’éditeur

Debug avec Delve

# installation
                            go install github.com/go-delve/delve/cmd/dlv@latest

                            # debug d'un package
                            dlv debug ./cmd/api

                            # test en debug
                            dlv test ./internal/service

Build standard

go build ./cmd/api

                            # Build avec variables de version
                            go build -ldflags="-X main.version=1.0.0 -X main.commit=abc123" ./cmd/api

Cross-compilation

# Linux AMD64
                            GOOS=linux GOARCH=amd64 go build -o bin/api-linux-amd64 ./cmd/api

                            # Linux ARM64
                            GOOS=linux GOARCH=arm64 go build -o bin/api-linux-arm64 ./cmd/api

                            # Windows AMD64
                            GOOS=windows GOARCH=amd64 go build -o bin/api.exe ./cmd/api

                            # macOS ARM64
                            GOOS=darwin GOARCH=arm64 go build -o bin/api-darwin-arm64 ./cmd/api

Points importants

• Documenter la commande de build “officielle”.
• Injecter version, commit, date si utile pour le support.
• Éviter les scripts divergents entre développeurs.
• Vérifier la cohérence des tags de build s’ils existent.

Dockerfile multi-stage recommandé

FROM golang:1.25 AS builder
                            WORKDIR /app

                            COPY go.mod go.sum ./
                            RUN go mod download

                            COPY . .
                            RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
                            go build -ldflags="-s -w" -o /out/api ./cmd/api

                            FROM gcr.io/distroless/static-debian12
                            WORKDIR /app
                            COPY --from=builder /out/api /app/api

                            USER nonroot:nonroot
                            EXPOSE 8080
                            ENTRYPOINT ["/app/api"]

Pipeline CI typique

go version
                            go mod tidy
                            git diff --exit-code go.mod go.sum
                            go fmt ./...
                            go vet ./...
                            golangci-lint run
                            go test ./...
                            go test -race ./...
                            go build ./cmd/api

Bonnes pratiques CI

• Version Go explicite et unique.
• Cache des modules et du build si pertinent.
• Échec immédiat sur formatage/lint/tests.
• Artifact final versionné.
• Scan image container si build Docker.

Commande diagnostic “réflexe”

go version
                            go env
                            go env GOMOD
                            go env GOPATH
                            go env GOMODCACHE
                            go mod tidy
                            go test ./...
                            go test -race ./...

Méthode recommandée

1. Comparer version Go locale et CI.
2. Inspecter l’environnement réel avec go env.
3. Nettoyer dépendances et cache si nécessaire.
4. Repasser fmt/lint/test/build dans le même ordre que la CI.
5. Ne pas patcher au hasard sans comprendre la divergence.

Ce que ce bootstrap vous donne

• un module propre
• une entrée explicite dans cmd/api
• une base prête pour handlers, services, stores
• une commande de build claire

Évolution naturelle

• ajout d’un logger structuré
• config par variables d’environnement
• tests unitaires
• Dockerfile multi-stage
• linting et CI

Variables, constantes et inférence

package main

                            import "fmt"

                            func main() {
                            var name string = "Guillaume"
                            age := 42
                            const pi = 3.14159

                            fmt.Println(name, age, pi)
                            }

Modes de déclaration

• var x int : déclaration explicite avec valeur zéro.
• var x = 10 : type inféré.
• x := 10 : déclaration courte, très idiomatique dans une fonction.
• const : valeur constante connue à la compilation ou utilisable comme constante.

Valeurs zéro importantes

Types numériques, chaînes, booléens

var (
                            a int     = 10
                            b int64   = 20
                            c float64 = 3.14
                            ok bool   = true
                            s string  = "hello"
                            )

Conversions explicites

var a int = 10
                            var b int64 = int64(a)
                            var c float64 = float64(a)

• Go évite les conversions implicites trop permissives.
• Cette discipline réduit les ambiguïtés et rend le code plus sûr.

if, for, switch : le trio central

if x > 10 {
                            fmt.Println("big")
                            } else if x == 10 {
                            fmt.Println("equal")
                            } else {
                            fmt.Println("small")
                            }

for i := 0; i < 5; i++ {
                            fmt.Println(i)
                            }

switch day {
                            case "mon":
                            fmt.Println("start")
                            case "fri":
                            fmt.Println("end")
                            default:
                            fmt.Println("mid")
                            }

Particularités importantes

• Pas de parenthèses autour des conditions.
• for remplace aussi while.
• switch est puissant, lisible et très utilisé.
• Un switch Go n’a pas besoin de break dans chaque case.

Exemples utiles

for x < 100 {
                            x *= 2
                            }

for _, item := range items {
                            fmt.Println(item)
                            }

switch {
                            case err != nil:
                            fmt.Println("error")
                            case count == 0:
                            fmt.Println("empty")
                            default:
                            fmt.Println("ok")
                            }

Fonctions simples

func add(a, b int) int {
                            return a + b
                            }

func split(sum int) (int, int) {
                            x := sum * 4 / 9
                            y := sum - x
                            return x, y
                            }

Spécificités notables

• Types à droite des paramètres.
• Paramètres adjacents de même type groupables.
• Retours multiples très fréquents.
• Les retours multiples sont très utilisés pour résultat + erreur.

Fonctions anonymes et closures

func main() {
                            double := func(n int) int {
                            return n * 2
                            }

                            fmt.Println(double(21))
                            }

func makeCounter() func() int {
                            n := 0
                            return func() int {
                            n++
                            return n
                            }
                            }

Nommer les retours : avec modération

func stats() (count int, ok bool) {
                            count = 42
                            ok = true
                            return
                            }

Structs : la base des modèles de données

type User struct {
                            ID    int64
                            Name  string
                            Email string
                            }

u := User{
                            ID:    1,
                            Name:  "Alice",
                            Email: "alice@example.com",
                            }

Pourquoi les structs sont centrales

• Elles remplacent souvent l’idée intuitive de “classe” pour la donnée.
• Elles peuvent embarquer des tags utiles, par exemple JSON, DB, validation.
• Elles se combinent très bien avec methods et interfaces.

Methods sur types

type User struct {
                            Name string
                            }

                            func (u User) Display() string {
                            return "User: " + u.Name
                            }

type Counter struct {
                            Value int
                            }

                            func (c *Counter) Inc() {
                            c.Value++
                            }

Value receiver vs pointer receiver

Interfaces : contrat comportemental

type Reader interface {
                            Read(p []byte) (n int, err error)
                            }

Une interface décrit un comportement. En Go, un type satisfait une interface implicitement s’il possède les methods requises. Il n’a pas besoin de déclaration formelle “implements”.

type Greeter interface {
                            Greet() string
                            }

                            type Person struct {
                            Name string
                            }

                            func (p Person) Greet() string {
                            return "Hello " + p.Name
                            }

Pourquoi c’est puissant

• Découplage très propre entre implémentation et usage.
• Testabilité améliorée.
• Moins de hiérarchie lourde qu’en programmation orientée objet classique.
• Conduit naturellement à des interfaces petites et ciblées.

Le pattern fondamental : résultat + erreur

func parse(input string) (int, error) {
                            if input == "" {
                            return 0, errors.New("empty input")
                            }
                            return strconv.Atoi(input)
                            }

n, err := parse("42")
                            if err != nil {
                            return err
                            }
                            fmt.Println(n)

Bloc idiomatique central

if err != nil {
                            return err
                            }

• Les erreurs ne sont pas “cachées”.
• Le flux d’échec reste visible et proche de l’appel fautif.
• La lecture du comportement devient très directe.

Wrapping et inspection

if err != nil {
                            return fmt.Errorf("load config: %w", err)
                            }

if errors.Is(err, os.ErrNotExist) {
                            fmt.Println("file missing")
                            }

var pathErr *os.PathError
                            if errors.As(err, &pathErr) {
                            fmt.Println(pathErr.Path)
                            }

defer : fermeture et nettoyage fiables

defer exécute une instruction à la sortie de la fonction courante, quel que soit le chemin normal de sortie. C’est un outil essentiel pour fermer un fichier, relâcher une ressource, débloquer un mutex ou tracer une fin de fonction.

f, err := os.Open("data.txt")
                            if err != nil {
                            return err
                            }
                            defer f.Close()

mu.Lock()
                            defer mu.Unlock()

panic et recover

func safe() {
                            defer func() {
                            if r := recover(); r != nil {
                            fmt.Println("recovered:", r)
                            }
                            }()

                            panic("boom")
                            }

• panic n’est pas le mécanisme normal de gestion d’erreur.
• recover doit être réservé à certains cadres bien maîtrisés, comme un middleware serveur ou un boundary critique.
• Pour les erreurs métier et I/O, on retourne généralement error.

Pointeurs en Go

Les pointeurs existent, mais sans arithmétique de pointeurs classique comme en C. Ils servent principalement à éviter certaines copies, à partager un état mutable, ou à distinguer “absence de valeur” et “valeur zéro” dans certaines API.

x := 10
                            p := &x

                            fmt.Println(*p) // 10
                            *p = 20
                            fmt.Println(x)  // 20

Cas d’usage typiques

• Receivers de methods qui mutent la struct.
• Types lourds à copier.
• Structures optionnelles ou champs “nullable-like”.

À bien comprendre

• Un pointeur peut être nil.
• Go gère la mémoire automatiquement ; on ne fait pas de free() manuel.
• Le choix valeur/pointeur influence les methods satisfaites par une interface.

type Config struct {
                            Port int
                            }

                            func update(c *Config) {
                            c.Port = 9090
                            }

Arrays, slices et maps

arr := [3]int{1, 2, 3}
                            slice := []int{10, 20, 30}
                            m := map[string]int{
                            "alice": 1,
                            "bob":   2,
                            }

Slices : structure fondamentale

• Très utilisées pour les collections ordonnées dynamiques.
• Basées sur un tableau sous-jacent.
• Manipulées avec append, len, cap.

nums := []int{1, 2}
                            nums = append(nums, 3, 4)

Maps : dictionnaires

ages := map[string]int{}
                            ages["alice"] = 30

                            age, ok := ages["alice"]
                            if ok {
                            fmt.Println(age)
                            }

Range sur collections

for i, v := range slice {
                            fmt.Println(i, v)
                            }

                            for k, v := range m {
                            fmt.Println(k, v)
                            }

Ce que montre cet exemple

• struct simple
• method de validation
• retour résultat + erreur
• wrapping d’erreur
• slice + range

Comment l’étendre

• ajouter JSON tags
• ajouter persistence DB
• ajouter HTTP handler
• ajouter tests unitaires
• ajouter context si I/O

Methods : attacher du comportement à un type

type User struct {
                            ID    int64
                            Email string
                            Admin bool
                            }

                            func (u User) IsAdmin() bool {
                            return u.Admin
                            }

Receiver par valeur

func (u User) Domain() string {
                            parts := strings.Split(u.Email, "@")
                            if len(parts) != 2 {
                            return ""
                            }
                            return parts[1]
                            }

Un receiver par valeur copie la valeur du receiver. C’est très bien pour des types petits, des méthodes purement lectrices, ou quand la sémantique de copie est acceptable.

Receiver par pointeur

type Counter struct {
                            Value int
                            }

                            func (c *Counter) Inc() {
                            c.Value++
                            }

Le receiver par pointeur est à privilégier lorsqu’une méthode modifie la struct, ou lorsqu’on veut éviter une copie coûteuse d’un type volumineux.

Choisir valeur ou pointeur

Important : méthode set et interface

type Renamer interface {
                            Rename(string)
                            }

                            type User struct {
                            Name string
                            }

                            func (u *User) Rename(v string) {
                            u.Name = v
                            }

Ici, c’est *User qui satisfait l’interface, pas User. Le choix du receiver influence donc la satisfaction des interfaces et doit être bien compris.

Interfaces : contrat comportemental minimal

Les interfaces sont satisfaites implicitement. C’est une force énorme pour le découplage, les tests et la modularité. Un type n’a pas besoin de déclarer explicitement qu’il “implémente” une interface ; il lui suffit de fournir les methods attendues.

type Mailer interface {
                            Send(to, body string) error
                            }

type SMTPMailer struct{}

                            func (m SMTPMailer) Send(to, body string) error {
                            fmt.Println("sending mail to", to)
                            return nil
                            }

func NotifyWelcome(m Mailer, email string) error {
                            return m.Send(email, "welcome")
                            }

Pourquoi ce modèle est si puissant

• Il découple le code consommateur de l’implémentation concrète.
• Il favorise les tests sans framework lourd.
• Il encourage des contrats petits, lisibles et ciblés.
• Il évite les hiérarchies de types excessives.

Petites interfaces > grosses interfaces

type Reader interface {
                            Read(p []byte) (n int, err error)
                            }

                            type Writer interface {
                            Write(p []byte) (n int, err error)
                            }

Les petites interfaces composables sont un trait fort de Go. Une interface trop grosse devient rigide, difficile à satisfaire, difficile à tester et révèle souvent un design flou.

Composition plutôt qu’héritage

Go préfère la composition à l’héritage. Au lieu de construire des arbres de classes, on assemble des types plus simples et spécialisés. Cela réduit le couplage, rend les relations plus explicites et simplifie les évolutions.

type Address struct {
                            City    string
                            Country string
                            }

                            type User struct {
                            ID      int64
                            Email   string
                            Address Address
                            }

Ici, User compose une Address. Il n’y a pas de sous-classe ni d’arbre d’héritage ; juste un type qui en contient un autre.

Pourquoi la composition est saine

• Les dépendances structurelles restent visibles.
• Les effets de bord liés à l’héritage profond sont évités.
• Le code devient plus modulaire et plus testable.
• Le refactoring est souvent plus simple.

Embedding : composition avec promotion de champs/methods

L’embedding permet d’inclure un type dans une struct sans lui donner explicitement un nom de champ. Les fields et methods du type embarqué deviennent alors “promus” sur la struct englobante, ce qui facilite certaines formes de réutilisation.

type Audit struct {
                            CreatedAt time.Time
                            UpdatedAt time.Time
                            }

                            type User struct {
                            ID    int64
                            Email string
                            Audit
                            }

u := User{}
                            u.CreatedAt = time.Now()

Ce que l’embedding n’est pas

• Ce n’est pas un héritage classique.
• Ce n’est pas une hiérarchie polymorphique lourde.
• Ce n’est pas un prétexte pour cacher trop d’état partagé.

Bon usage

• Mutualiser des champs transverses : audit, timestamps, metadata.
• Réutiliser un petit comportement commun.
• Conserver une API lisible.

Exemple de service orienté interface

type UserStore interface {
                            Save(ctx context.Context, u User) error
                            }

                            type Service struct {
                            store UserStore
                            }

                            func NewService(store UserStore) Service {
                            return Service{store: store}
                            }

                            func (s Service) Register(ctx context.Context, u User) error {
                            if u.Email == "" {
                            return errors.New("email required")
                            }
                            return s.store.Save(ctx, u)
                            }

Pourquoi ce pattern fonctionne bien en Go

• Il garde le domaine lisible.
• Il permet des tests faciles.
• Il ne nécessite aucun framework invasif.
• Il reste compatible avec une architecture simple ou plus ambitieuse.

Tester via petites interfaces

type Mailer interface {
                            Send(to, body string) error
                            }

                            type FakeMailer struct {
                            Calls []string
                            }

                            func (f *FakeMailer) Send(to, body string) error {
                            f.Calls = append(f.Calls, to+"|"+body)
                            return nil
                            }

func TestWelcome(t *testing.T) {
                            fake := &FakeMailer{}
                            err := NotifyWelcome(fake, "alice@example.com")
                            if err != nil {
                            t.Fatal(err)
                            }
                            if len(fake.Calls) != 1 {
                            t.Fatalf("expected 1 call, got %d", len(fake.Calls))
                            }
                            }

Pourquoi Go simplifie le mocking

• Pas besoin de framework complexe pour de nombreux cas.
• Une petite interface suffit.
• Les fakes en mémoire sont souvent plus lisibles qu’un mock DSL sophistiqué.
• Les tests deviennent plus proches du comportement métier réel.

Zero values utiles

Une bonne pratique Go consiste, quand c’est possible, à rendre les zero values immédiatement utilisables. Cela réduit le besoin d’initialisations complexes et simplifie l’usage des types.

type Counter struct {
                            Value int
                            }

                            func (c *Counter) Inc() {
                            c.Value++
                            }

Ici, la zero value de Counter est déjà valide : var c Counter peut être utilisé directement.

Pourquoi c’est précieux

• API plus simples.
• Moins de constructeurs obligatoires.
• Moins de risques d’oublier une initialisation.
• Meilleure ergonomie générale.

var c Counter
                            c.Inc()
                            fmt.Println(c.Value) // 1

Architecture applicative typique

Dans une application Go propre, les structs modélisent les entités et objets utiles, les services orchestrent la logique, et les interfaces marquent les frontières avec les dépendances externes.

Répartition saine des responsabilités

• Struct métier : état cohérent + methods proches du métier.
• Service : orchestration, validation, workflow.
• Interface : frontière entre domaine et infrastructure.
• Implémentation concrète : DB, SMTP, Redis, HTTP client, etc.

Ce que montre cet exemple

• struct métier simple
• methods de validation et lecture
• interfaces petites et ciblées
• service injecté par dépendances
• implémentations concrètes interchangeables

Extensions possibles

• ajouter une implémentation Postgres
• ajouter un fake mailer pour tests
• ajouter des JSON tags
• ajouter du context timeout
• ajouter métriques et logs

Wrapping avec %w

Utiliser %w permet de conserver la chaîne causale et d’exploiter ensuite errors.Is et errors.As. On enrichit donc l’erreur sans perdre sa nature profonde.

func load(path string) ([]byte, error) {
                            data, err := os.ReadFile(path)
                            if err != nil {
                            return nil, fmt.Errorf("load file %s: %w", path, err)
                            }
                            return data, nil
                            }

Pourquoi c’est supérieur à une simple concaténation

• Le message devient plus utile pour l’humain.
• La cause sous-jacente reste inspectable.
• Les tests peuvent continuer à reconnaître certains cas particuliers.
• Les couches supérieures peuvent encore prendre des décisions intelligentes.

Bon wrapping vs mauvais wrapping

// bon
                            return fmt.Errorf("read config %s: %w", path, err)

                            // moins bon : perd la causalité structurée
                            return fmt.Errorf("read config %s: %v", path, err)

                            // encore pire : transforme en simple texte
                            return errors.New("read config failed")

Règles pratiques

• Ajouter un contexte utile, pas décoratif.
• Ne pas re-wrapper 7 fois sans information nouvelle.
• Conserver l’erreur originale quand la couche supérieure doit l’identifier.
• Choisir un message orienté action ou diagnostic.

errors.Is : reconnaître un cas

if errors.Is(err, os.ErrNotExist) {
                            fmt.Println("file not found")
                            }

errors.Is permet de dire : “dans cette chaîne d’erreurs wrapées, y a-t-il cette erreur cible ?”. C’est idéal pour les erreurs sentinelles ou certains cas standards du runtime / OS / I/O.

errors.As : extraire un type d’erreur

var pathErr *os.PathError
                            if errors.As(err, &pathErr) {
                            fmt.Println("path:", pathErr.Path)
                            }

errors.As sert lorsque l’on veut récupérer un type précis d’erreur pour accéder à ses champs ou à son comportement.

Quand utiliser l’un ou l’autre

Exemple réaliste

func readUserConfig(path string) error {
                            _, err := os.ReadFile(path)
                            if err != nil {
                            return fmt.Errorf("user config loading failed: %w", err)
                            }
                            return nil
                            }

                            err := readUserConfig("/tmp/missing.json")
                            if errors.Is(err, os.ErrNotExist) {
                            fmt.Println("create a default config")
                            }

Sentinel errors

var ErrInvalidEmail = errors.New("invalid email")
                            var ErrUserNotFound = errors.New("user not found")

Une sentinel error représente un cas connu et identifiable. Elle est simple, lisible, mais ne transporte pas de métadonnées détaillées.

Custom error type

type ValidationError struct {
                            Field string
                            Msg   string
                            }

                            func (e ValidationError) Error() string {
                            return e.Field + ": " + e.Msg
                            }

Un type personnalisé est utile lorsque l’erreur doit transporter des informations structurées : champ en cause, code, ressource, statut, catégorie, etc.

Quand choisir quoi

Exemple combiné

var ErrUnauthorized = errors.New("unauthorized")

                            type HTTPError struct {
                            Status int
                            Op     string
                            Err    error
                            }

                            func (e HTTPError) Error() string {
                            return fmt.Sprintf("%s: %v", e.Op, e.Err)
                            }

                            func (e HTTPError) Unwrap() error {
                            return e.Err
                            }

Erreurs liées au context

ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
                            defer cancel()

                            err := doWork(ctx)
                            if err != nil {
                            if errors.Is(err, context.DeadlineExceeded) {
                            fmt.Println("timeout")
                            }
                            }

Les timeouts et annulations sont essentiels dans les applications I/O, HTTP, DB, gRPC et traitement asynchrone. Le context fournit des erreurs standards que vos couches supérieures doivent souvent reconnaître.

I/O : toujours contextualiser

rows, err := db.QueryContext(ctx, query)
                            if err != nil {
                            return fmt.Errorf("query users: %w", err)
                            }

Pourquoi c’est critique en production

• Un timeout n’a pas la même signification qu’une erreur métier.
• Une annulation volontaire ne doit pas toujours déclencher une alerte.
• Les retries automatiques doivent distinguer timeout, 4xx, 5xx, réseau, validation.
• Le diagnostic opérationnel dépend fortement de cette catégorisation.

Service layer : enrichir, pas exposer

func (s Service) GetUser(ctx context.Context, id int64) (User, error) {
                            u, err := s.store.FindByID(ctx, id)
                            if err != nil {
                            return User{}, fmt.Errorf("get user %d: %w", id, err)
                            }
                            return u, nil
                            }

La couche service donne du sens fonctionnel ou métier à l’erreur. Elle ne doit pas forcément décider du code HTTP ou du message client final, mais elle doit rendre l’échec intelligible.

HTTP handler : mapper vers une réponse sûre

u, err := svc.GetUser(r.Context(), id)
                            if err != nil {
                            switch {
                            case errors.Is(err, ErrUserNotFound):
                            http.Error(w, "user not found", http.StatusNotFound)
                            default:
                            http.Error(w, "internal error", http.StatusInternalServerError)
                            }
                            return
                            }

Règle essentielle

• Ne pas exposer directement l’erreur brute au client.
• Conserver le détail pour les logs / traces, pas pour la surface publique.
• Utiliser une table mentale de mapping : validation → 400, not found → 404, auth → 401/403, panne interne → 500.

panic n’est pas le flux normal

panic ne doit pas être une stratégie normale de contrôle de flux. Réserver cela aux erreurs réellement irréparables, aux violations d’invariants critiques, ou à des couches très basses avec garde globale maîtrisée.

func mustParseConfig(raw []byte) Config {
                            var cfg Config
                            if err := json.Unmarshal(raw, &cfg); err != nil {
                            panic(err)
                            }
                            return cfg
                            }

Ce genre de pattern peut se justifier dans certains bootstrap très contrôlés, mais il doit rester rare et explicite.

recover à la frontière

func recoverMiddleware(next http.Handler) http.Handler {
                            return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
                            defer func() {
                            if rec := recover(); rec != nil {
                            http.Error(w, "internal error", http.StatusInternalServerError)
                            }
                            }()
                            next.ServeHTTP(w, r)
                            })
                            }

• Le bon usage de recover se situe souvent au boundary : middleware HTTP, worker supervisor, top-level command.
• Le but n’est pas de normaliser la panic, mais d’éviter l’effondrement brutal d’une requête ou d’un worker.
• La panic doit être loggée avec contexte et stack si nécessaire.

Logguer une erreur : où et quand ?

Une règle très utile en Go backend : logguer l’erreur à la frontière qui la consomme réellement, pas à chaque niveau. Sinon, on obtient des doublons, du bruit, et une observabilité polluée.

u, err := svc.GetUser(ctx, id)
                            if err != nil {
                            logger.Error("get user failed", "user_id", id, "err", err)
                            http.Error(w, "internal error", http.StatusInternalServerError)
                            return
                            }

Pourquoi éviter le “log then return err” partout

• Duplication de logs sur une même erreur.
• Volumes inutiles.
• Difficulté à distinguer la source réelle.
• Coût cognitif en incident.

Bonne pratique de structure

• Ajouter l’opération ou le contexte utile.
• Ajouter les identifiants techniques pertinents : request ID, user ID, job ID.
• Ne pas exposer de secrets.
• Laisser la chaîne causale intacte.

logger.Error(
                            "payment processing failed",
                            "order_id", orderID,
                            "customer_id", customerID,
                            "err", err,
                            )

Guide de design par couches

Questions à se poser

• Cette erreur doit-elle être identifiable plus haut ?
• Faut-il un sentinel error, un type custom, ou juste du wrapping ?
• Qui a la responsabilité du logging final ?
• Quel message est sûr pour l’utilisateur final ?
• Faut-il déclencher retry, métrique, alerte ou circuit breaker ?

Taxonomie simple et efficace

Ce que montre cet exemple

• sentinel error métier
• wrapping avec contexte d’opération
• prise en compte du context timeout
• mapping HTTP sécurisé
• logging unique au boundary

Évolutions possibles

• ajouter un custom error type avec code métier
• intégrer traces OpenTelemetry
• ajouter métriques par catégorie d’erreur
• différencier retryable / non-retryable
• normaliser le mapping d’erreurs avec une table centrale

go.mod : le cœur du module

go.mod définit le module racine, la version Go cible et les dépendances. C’est la source de vérité du projet pour la résolution des imports, la reproductibilité et la cohérence de build.

module github.com/acme/myapp

                            go 1.25

                            require (
                            github.com/go-chi/chi/v5 v5.2.1
                            github.com/jackc/pgx/v5 v5.7.2
                            )

Rôle des lignes clés

• module : identité du module.
• go : version cible de langage/toolchain.
• require : dépendances directes.
• Les dépendances indirectes peuvent aussi apparaître.

go.sum : intégrité et reproductibilité

go.sum conserve les checksums des dépendances et contribue à la sécurité et à la reproductibilité. Il ne faut pas l’ignorer ni le traiter comme un simple bruit de build.

go mod tidy
                            go mod download
                            go list -m all

Hygiène minimale

• go mod tidy doit rester propre et reproductible.
• Ne pas committer un go.mod instable ou incohérent.
• Relire les changements de dépendances dans les PRs.
• Éviter les ajouts opportunistes non justifiés.

internal/ : code privé au module

Le dossier internal/ a une signification spéciale en Go : les packages qu’il contient ne peuvent être importés que depuis le module parent autorisé. C’est un excellent outil pour signaler clairement : “ce code n’est pas une API publique”.

internal/
                            app/
                            config/
                            domain/
                            service/
                            transport/httpapi/
                            storage/postgres/

Pourquoi c’est précieux

• Évite l’exposition accidentelle d’APIs internes.
• Permet un refactoring plus libre.
• Aide à garder une frontière nette entre stable et privé.
• Réduit le couplage externe.

pkg/ : à utiliser avec discipline

pkg/ est souvent employé pour du code partagé potentiellement importable par d’autres modules ou par plusieurs sous-parties du dépôt. Mais il ne faut pas en faire un fourre-tout.

pkg/
                            httpx/
                            retry/
                            validation/
                            observability/

Règle simple

• Si le code est strictement privé au module : internal/.
• Si le code est vraiment stable, générique et réutilisable : pkg/.
• Si vous hésitez : souvent internal/ d’abord.

cmd/ : les exécutables

Le répertoire cmd/ accueille les points d’entrée. Chaque sous-dossier correspond généralement à un exécutable distinct : API HTTP, worker, CLI, migrator, scheduler, importer, etc.

cmd/
                            api/
                            main.go
                            worker/
                            main.go
                            migrate/
                            main.go

Règle idiomatique

• main.go doit rester mince.
• Le wiring et le bootstrap peuvent vivre dans internal/app ou équivalent.
• Le domaine ne doit pas dépendre de main.

Pourquoi c’est sain

• On identifie immédiatement ce qui peut être compilé/exécuté.
• Les services partageant du code gardent des entrées séparées.
• Les responsabilités restent propres entre bootstrap et logique métier.

go build ./cmd/api
                            go build ./cmd/worker
                            go run ./cmd/migrate

Exemple d’arborescence plus détaillée

internal/
                            domain/
                            user.go
                            order.go
                            errors.go
                            service/
                            user_service.go
                            order_service.go
                            transport/
                            httpapi/
                            handlers.go
                            middleware.go
                            routes.go
                            storage/
                            postgres/
                            user_repo.go
                            order_repo.go
                            redis/
                            cache.go
                            app/
                            bootstrap.go
                            wiring.go

But architectural

• Le transport ne contient pas la logique métier profonde.
• Le domaine reste indépendant de HTTP/SQL quand c’est pertinent.
• Les adapters peuvent être remplacés plus facilement.
• Les tests ciblent plus simplement chaque couche.

Versioning des modules

Pour les librairies publiques, respecter le semantic versioning. Pour les services internes, verrouiller les versions critiques et éviter les upgrades massifs non testés.

Cas des modules v2+

module github.com/acme/tool/v2

En Go, un module majeur supérieur à v1 apparaît généralement dans le chemin d’import. Ce point est fondamental pour les bibliothèques publiques.

Politique réaliste

• Lib publique : semver strict, changelog, tags propres.
• Service interne : upgrades maîtrisés, tests de non-régression, dépendances critiques gelées si besoin.
• Éviter les “big bang upgrades” sur 40 dépendances à la fois.

git tag v1.4.2
                            git tag v2.0.0

Gestion des dépendances

• Préférer peu de dépendances, bien choisies.
• Éviter d’introduire une lib pour un besoin minime déjà couvert par la stdlib.
• Réviser régulièrement les dépendances directes.
• Vérifier les implications des dépendances indirectes volumineuses.

go list -m all
                            go mod graph
                            go mod tidy

Questions avant d’ajouter une dépendance

1. La stdlib suffit-elle déjà ?
2. Le package est-il maintenu et stable ?
3. Ajoute-t-il un vrai gain ou juste une abstraction de confort ?
4. Le coût de long terme est-il acceptable ?

Monorepo : quand et pourquoi

Un monorepo Go peut être très efficace quand plusieurs services, librairies internes, outils de build ou agents doivent évoluer ensemble. Il offre visibilité, coordination et refactorings transverses plus simples.

repo/
                            services/
                            billing/
                            auth/
                            libs/
                            observability/
                            retry/
                            tools/
                            migrator/
                            codegen/

Avantages

• Vue globale cohérente.
• Refactorings multi-composants facilités.
• Partage d’outils et de conventions.
• CI centralisée possible.

Risques

• Couplage implicite entre composants.
• Frontières floues si les modules sont mal gérés.
• Temps de build et CI qui grossissent.
• Tentation de dépendances internes trop faciles.

go work : workspace multi-modules

Les workspaces (go work) sont utiles pour développer plusieurs modules ensemble sans hacks locaux. Ils permettent d’indiquer à la toolchain quels modules locaux doivent être utilisés conjointement pendant le développement.

go work init ./service-a ./service-b ./shared-lib
                            go work use ./tooling

go.work
                            go.work.sum

Quand c’est utile

• Monorepo multi-modules.
• Développement simultané d’une lib et d’un service qui l’utilise.
• Éviter des replace locaux multiples et fragiles.

Attention

• go work aide le développement local, pas la politique de versioning.
• Il ne faut pas oublier le comportement réel hors workspace.
• Les CI doivent refléter la stratégie voulue : mono-module, multi-module ou workspace contrôlé.

Règle de fond

Le meilleur layout n’est pas le plus “théorique”, mais celui qui révèle clairement comment le projet fonctionne, où vivent les décisions métier et comment les composants communiquent.

Signaux d’une mauvaise architecture

• Packages aux noms flous : common, utils, helpers, misc.
• Transport et SQL mélangés partout.
• Dépendances circulaires ou quasi-circulaires.
• Points d’entrée invisibles ou confus.
• Réutilisation non maîtrisée entre services.

Pourquoi ce squelette fonctionne bien

• cmd/api identifie clairement l’exécutable.
• internal/app centralise le wiring/bootstrap.
• domain et service restent lisibles.
• storage peut évoluer sans polluer le domaine.

Évolution naturelle

• ajouter un worker dans cmd/worker
• ajouter config, logger, metrics dans internal/app
• ajouter adapters Postgres / Redis
• ajouter tests et testdata/
• ajouter Docker / CI / migrations

Goroutines : exécution concurrente légère

go func() {
                            fmt.Println("running concurrently")
                            }()

Une goroutine est une unité d’exécution gérée par le runtime Go. Elle est beaucoup plus légère qu’un thread OS classique, mais elle consomme tout de même mémoire, scheduling et ressources indirectes. Multiplier les goroutines sans contrôle peut donc devenir coûteux.

Caractéristiques importantes

• Démarrage très simple via le mot-clé go.
• Stack initiale légère et extensible.
• Ordonnancement assuré par le runtime Go.
• Parfait pour I/O, attente, orchestration et travail parallèle borné.

Mais “légère” ne veut pas dire “gratuite”

• Chaque goroutine garde une stack, un état, des références mémoire.
• Une goroutine bloquée peut retenir des ressources ou empêcher la libération de données.
• Une fuite de goroutines est une vraie fuite de système, pas un détail théorique.

for _, url := range urls {
                            url := url
                            go func() {
                            _ = fetch(url)
                            }()
                            }

Le code ci-dessus est simple, mais il peut devenir dangereux si urls contient des milliers d’entrées ou si fetch ne respecte ni timeout ni annulation.

Channels : communication explicite

ch := make(chan int)

                            go func() {
                            ch <- 42
                            }()

                            v := <-ch
                            fmt.Println(v)

Un channel permet d’échanger des valeurs entre goroutines de manière synchronisée. Il peut être non bufferisé (communication rendez-vous) ou bufferisé (petite file en mémoire).

Canal non bufferisé

• L’envoi bloque jusqu’à ce qu’un receveur soit prêt.
• Très utile pour exprimer une synchronisation stricte.

Canal bufferisé

jobs := make(chan int, 10)

• Permet un petit découplage entre producteur et consommateur.
• Utile pour absorber des pics ou structurer une file bornée.

Règles critiques de design

• Décider clairement qui écrit, qui lit, qui ferme.
• Ne fermer un channel que du côté producteur propriétaire.
• Utiliser for range ch quand le flux se termine naturellement par fermeture.

for job := range jobs {
                            fmt.Println(job)
                            }

Types directionnels utiles

func producer(out chan<- int) { out <- 1 }
                            func consumer(in <-chan int) { fmt.Println(<-in) }

Les channels directionnels rendent les contrats plus explicites et aident le compilateur à protéger certains usages.

select : multiplexage d’attente

select {
                            case msg := <-ch:
                            _ = msg
                            case <-time.After(2 * time.Second):
                            return errors.New("timeout")
                            case <-ctx.Done():
                            return ctx.Err()
                            }

select permet d’attendre plusieurs opérations de communication à la fois. C’est un outil fondamental pour gérer timeouts, annulations, fan-in, supervision et comportement non bloquant.

Cas d’usage typiques

• Attendre un résultat ou un timeout.
• Prioriser une annulation de context.
• Consommer plusieurs flux concurrents.
• Construire des boucles de supervision propres.

default : avec prudence

select {
                            case msg := <-ch:
                            fmt.Println(msg)
                            default:
                            fmt.Println("nothing available")
                            }

Ajouter un default rend le select non bloquant. Cela peut être utile, mais un mauvais usage peut produire des busy loops agressives qui consomment du CPU sans travail utile.

Boucle supervisée typique

for {
                            select {
                            case item, ok := <-jobs:
                            if !ok {
                            return
                            }
                            process(item)
                            case <-ctx.Done():
                            return
                            }
                            }

Worker pool : parallélisme borné

Le worker pool est l’un des patterns les plus utiles en Go : on limite explicitement le nombre de goroutines qui traitent une file de jobs. Cela évite le fan-out infini et stabilise l’usage CPU/mémoire/réseau.

jobs := make(chan int)
                            results := make(chan int)

                            for w := 0; w < 4; w++ {
                            go func() {
                            for j := range jobs {
                            results <- j * 2
                            }
                            }()
                            }

Pourquoi c’est un bon pattern

• Le nombre de workers est contrôlé.
• Le débit est plus prévisible.
• La mémoire ne dépend pas d’un nombre infini de goroutines.
• Le pattern est simple à superviser et monitorer.

Ce qu’il faut encore ajouter pour le rendre robuste

• un context de cancellation
• un WaitGroup ou un errgroup
• la fermeture coordonnée des channels
• une gestion explicite des erreurs

Pipelines : stages concurrents

Un pipeline découpe le traitement en étapes successives, chacune pouvant tourner dans une ou plusieurs goroutines. Chaque étape lit depuis un channel d’entrée, transforme, puis pousse vers un channel de sortie.

func stage(in <-chan int) <-chan int {
                            out := make(chan int)
                            go func() {
                            defer close(out)
                            for v := range in {
                            out <- v * 2
                            }
                            }()
                            return out
                            }

Atouts et risques

• Atouts : découpage clair, parallélisation par étape, bonne composabilité.
• Risques : channels non drainés, fuite si un stage aval s’arrête, absence de cancel global.

Règles de survie

• Toujours prévoir comment le pipeline s’arrête.
• Ajouter un context pour permettre une interruption coordonnée.
• Éviter les buffers gigantesques qui masquent les problèmes de débit.

context : annuler, borner, propager

ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
                            defer cancel()

Le context est central dès qu’un travail concurrent peut être abandonné, qu’un timeout doit être appliqué, ou qu’une requête utilisateur s’arrête avant la fin du traitement.

Ce qu’il faut annuler

• appels réseau
• requêtes base de données
• travaux workers dépendants d’une requête
• pipelines dont le résultat n’est plus utile

Boucle worker annulable

for {
                            select {
                            case <-ctx.Done():
                            return
                            case job, ok := <-jobs:
                            if !ok {
                            return
                            }
                            process(job)
                            }
                            }

Pourquoi c’est indispensable

• Évite les goroutines zombies.
• Réduit le gaspillage après abandon du client ou arrêt du service.
• Rend les shutdowns plus propres.
• Permet un meilleur contrôle de saturation.

Channels ne suffisent pas toujours

Les channels expriment magnifiquement des flux, mais pour certains besoins de synchronisation ou de protection mémoire, les primitives du package sync restent essentielles : WaitGroup, Mutex, RWMutex, Once, Cond, etc.

var wg sync.WaitGroup

                            for i := 0; i < 4; i++ {
                            wg.Add(1)
                            go func() {
                            defer wg.Done()
                            work()
                            }()
                            }

                            wg.Wait()

Protection d’état partagé

type Counter struct {
                            mu sync.Mutex
                            n  int
                            }

                            func (c *Counter) Inc() {
                            c.mu.Lock()
                            defer c.mu.Unlock()
                            c.n++
                            }

Idée clé

• Channels pour flux et coordination.
• Mutex pour protéger un état partagé mutable.
• WaitGroup pour attendre une collection de travaux.

Autres pièges subtils

• Capturer des variables de boucle sans les réassigner proprement.
• Attendre un résultat d’une goroutine qui ne pourra jamais être envoyé.
• Ne pas drainer certains channels d’erreurs ou de résultats.
• Buffer trop petit ou trop grand, masquant le comportement réel.

Commande indispensable

go test -race ./...

Le race detector ne remplace pas une architecture correcte, mais il attrape une classe de bugs concurrents extrêmement précieux à détecter tôt.

Performance et coût réel

Une architecture concurrente n’est pas automatiquement plus rapide. Elle peut au contraire ajouter contention, scheduling, allocations, synchronisations inutiles et pressions mémoire.

Questions à se poser

• Ce travail est-il CPU-bound ou I/O-bound ?
• Le parallélisme améliore-t-il réellement le throughput ou seulement la complexité ?
• Quel est le niveau de concurrence optimal ?
• Où sont les files, les goulots et les points de blocage ?

Ce qu’il faut mesurer

• latence p50 / p95 / p99
• taille des queues
• nombre de goroutines actives
• taux d’échec / timeout / cancellation
• CPU, mémoire, blocages, contention

Ce que montre cet exemple

• nombre de workers borné
• propagation du context
• fermeture propre des jobs
• attente structurée via WaitGroup
• fermeture coordonnée de results

Améliorations possibles

• utiliser errgroup pour gérer erreurs + cancel
• ajouter métriques par worker
• instrumenter temps de traitement
• ajouter backpressure plus explicite
• séparer erreurs et résultats

Pattern central : boundary → service → repository

HTTP handler
                            |
                            v
                            Service
                            |
                            v
                            Repository / Adapter

C’est probablement l’un des patterns les plus rentables en Go. Le handler ou boundary décode la requête, gère le transport et mappe la réponse. Le service porte le workflow métier. Le repository ou l’adapter encapsule l’accès à la DB, au cache, à une API externe ou à un message bus.

Pourquoi ce pattern est durable

• Chaque couche a un rôle lisible.
• Les tests deviennent plus simples à écrire.
• Les dépendances sont injectables via interfaces ciblées.
• Le domaine ne se retrouve pas pollué par HTTP/SQL partout.

Exemple idiomatique

type UserStore interface {
                            FindByID(ctx context.Context, id int64) (User, error)
                            }

                            type Service struct {
                            store UserStore
                            }

                            func (s Service) GetUser(ctx context.Context, id int64) (User, error) {
                            return s.store.FindByID(ctx, id)
                            }

Règles de découpage

• Le handler ne doit pas contenir la logique métier profonde.
• Le service ne doit pas connaître les détails de transport HTTP.
• Le repository ne doit pas décider du statut HTTP final.

Patterns de concurrence utiles

• Worker pool borné.
• Fan-out / fan-in avec limite de parallélisme.
• Pipeline par étapes bien définies.
• errgroup pour supervision + cancellation.
• context propagé systématiquement dans l’I/O.

g, ctx := errgroup.WithContext(ctx)

                            for _, item := range items {
                            item := item
                            g.Go(func() error {
                            return process(ctx, item)
                            })
                            }

                            if err := g.Wait(); err != nil {
                            return err
                            }

Pourquoi ces patterns sont bons

• Ils bornent le travail concurrent.
• Ils rendent l’annulation explicite.
• Ils évitent les goroutines “orphelines”.
• Ils restent compatibles avec l’observabilité et le shutdown propre.

Pattern de configuration explicite

Une configuration Go saine est chargée au startup, validée une fois, transformée en struct typée, puis transmise explicitement aux composants concernés. Elle ne doit pas devenir un état global malléable pendant l’exécution.

type Config struct {
                            HTTPPort     int
                            DatabaseDSN  string
                            ReadTimeout  time.Duration
                            WriteTimeout time.Duration
                            }

Bootstrap propre

• charger
• valider
• assembler les dépendances
• exposer des composants prêts à l’emploi

Pourquoi ce pattern est excellent

• Le comportement du système est prévisible.
• Le startup échoue tôt si la config est invalide.
• Les tests peuvent injecter facilement une config de test.
• On évite la dérive d’un état global implicite.

cfg, err := LoadConfig()
                            if err != nil {
                            return fmt.Errorf("load config: %w", err)
                            }

                            app := NewApp(cfg)

Pattern d’observabilité

• Logs structurés.
• Metrics par flux métier et technique.
• Tracing des opérations distribuées.
• Health/readiness endpoints.
• Profiling activable en environnement maîtrisé.

logger.Error(
                            "payment failed",
                            "order_id", orderID,
                            "user_id", userID,
                            "err", err,
                            )

Pourquoi c’est un pattern et pas juste de l’ops

En Go, un bon design se voit aussi à sa capacité à être observé. Un service qui compile et répond, mais que l’on ne peut ni comprendre en incident, ni profiler, ni diagnostiquer, est un service incomplet.

Style guide idiomatique

• Noms courts, mais sémantiquement évidents.
• Fonctions courtes, sans imbrications excessives.
• Variables d’erreur nommées err sauf contexte spécial.
• Packages cohérents, pas de “helpers”, “misc”, “common” sans borne claire.
• Commentaires utiles, pas décoratifs.

Ce que le style Go privilégie

• Le code doit être facile à scanner visuellement.
• Le flux d’échec doit être visible.
• Le formatage automatique met tous les développeurs d’accord.
• Les fonctions doivent être compréhensibles sans gymnastique mentale.

func (s Service) CreateUser(ctx context.Context, in Input) (User, error) {
                            if err := in.Validate(); err != nil {
                            return User{}, fmt.Errorf("validate input: %w", err)
                            }

                            u, err := s.store.Save(ctx, in.ToUser())
                            if err != nil {
                            return User{}, fmt.Errorf("save user: %w", err)
                            }

                            return u, nil
                            }

Heuristiques de code review

1. Comprend-on en 30 secondes le rôle du package ?
2. La fonction a-t-elle une responsabilité claire ?
3. Le contexte est-il propagé dans les appels I/O ?
4. Les erreurs sont-elles contextualisées sans bruit ?
5. La concurrence est-elle bornée et annulable ?
6. Les dépendances sont-elles injectées proprement ?
7. Le logging se situe-t-il au bon niveau ?

Signaux faibles de dérive

• beaucoup de fichiers “manager”, “factory”, “builder”, “provider” sans vraie valeur
• couches vides qui ne font que passer l’appel
• mélange transport / métier / DB dans le même handler
• abstractions génériques avant tout besoin concret
• packages utilitaires devenus fourre-tout

Playbook de refactoring idiomatique

1. Identifier les packages flous et les responsabilités mélangées.
2. Déplacer les interfaces au point de consommation.
3. Couper les “god structs” en types cohérents.
4. Introduire le context là où l’I/O est longue ou critique.
5. Remplacer le fan-out sauvage par un worker pool borné.
6. Réduire les helpers globaux au profit de composants explicites.

Ordre conseillé

Roadmap expert

1. Maîtriser net/http et database/sql.
2. Devenir solide en concurrence et contexte.
3. Savoir profiler avec pprof.
4. Construire une API complète et observable.
5. Industrialiser avec Docker + CI/CD + sécurité.

Lecture “maturité”

• Junior Go : écrit du code qui marche.
• Intermédiaire : écrit du code maintenable.
• Senior : écrit du code qui reste clair sous croissance.
• Expert : écrit des systèmes opérables, testables, stables sous charge et simples à faire évoluer.

Pourquoi c’est bon

• interfaces petites
• service lisible
• erreurs contextualisées
• dépendances explicites
• testabilité naturelle

Ce qu’il faut éviter à la place

• service qui connaît SQL, SMTP, HTTP et logs détaillés en même temps
• factory inutile pour fabriquer une seule struct simple
• grosse interface “AppManager” qui fait tout
• variables globales partagées partout

Socle officiel indispensable

• Documentation officielle Go.
• Language specification.
• Effective Go.
• Package documentation standard library.
• Release notes et évolution de la toolchain.

Pourquoi commencer ici

• Vous obtenez les conventions voulues par le langage lui-même.
• Vous évitez les surcouches communautaires parfois trop subjectives.
• Vous construisez des réflexes idiomatiques durables.

Ordre de lecture conseillé

1. Tour of Go ou rappel syntaxique rapide.
2. Effective Go.
3. Spec par sections selon les besoins.
4. Documentation détaillée des packages utilisés quotidiennement.

Références concurrence à étudier

• Go Proverbs / talks de Rob Pike.
• Docs sur context.
• Docs sur sync.
• Exemples officiels de goroutines, channels et select.
• Guides sur worker pools, cancellation et supervision.

Objectifs d’apprentissage

• comprendre la différence entre parallélisme et concurrence
• maîtriser la fermeture de channels
• gérer les timeouts et annulations
• éviter les goroutine leaks

Ce qu’il faut vraiment retenir

Références HTTP / API

• Documentation net/http.
• Documentation httptest.
• Docs context appliquées à HTTP.
• Guides sur middlewares, timeouts, graceful shutdown.
• Références sur JSON, validation, error mapping.

À étudier concrètement

• serveur HTTP natif
• client HTTP avec timeout
• handlers testables
• codes de retour et sécurité des messages d’erreur

Pourquoi c’est prioritaire

Une grande partie de l’écosystème Go tourne autour des services réseau. Maîtriser le package HTTP standard offre une base incroyablement solide, y compris lorsque l’on utilise ensuite des routeurs ou middlewares complémentaires.

Références base de données

• Documentation database/sql.
• Docs driver spécifiques selon votre SGBD.
• Guides sur pool de connexions, transactions, context deadlines.
• Lectures sur requêtes lentes, contention et stratégie d’indexation.

Sujets à creuser

• pool tuning
• gestion des rows et du scan
• transactions propres
• timeouts DB
• mapping d’erreurs de storage

Pourquoi cette lecture est décisive

Beaucoup de problèmes attribués à “Go” viennent en réalité d’une mauvaise maîtrise de la persistence : pools mal réglés, queries mal gérées, rows non fermées, erreurs SQL mal propagées ou manque d’observabilité DB.

Références tests à prioriser

• Documentation testing.
• httptest pour les handlers.
• Benchmarks et -benchmem.
• Race detector.
• Fuzz testing quand pertinent.

Compétences attendues

• tests unitaires simples
• tests de services avec fakes
• tests HTTP
• benchmarks de hot paths
• lecture des résultats race

Le bon état d’esprit

Références performance et profiling

• Documentation pprof.
• CPU profiles, memory profiles, goroutine profiles.
• Benchmarks natifs Go.
• Docs sur allocations, GC pressure et contention.

Questions de lecture utiles

• où sont les allocations ?
• où est le temps CPU ?
• combien de goroutines vivent réellement ?
• où le programme bloque-t-il ?

Règle clé

go test -bench=. -benchmem ./...
go test -cpuprofile=cpu.out ./...
go test -memprofile=mem.out ./...
go tool pprof cpu.out
go tool pprof mem.out

Références sécurité à étudier

• Guides de sécurité applicative Go.
• govulncheck et hygiène des dépendances.
• Bonnes pratiques TLS / HTTP timeouts.
• Sécurité des containers et images minimales.
• Gestion des secrets et configuration runtime.

Réflexes à développer

• ne jamais exposer les erreurs internes brutes
• utiliser des timeouts réseau
• scanner les dépendances
• durcir la surface container

Zone souvent sous-estimée

Beaucoup de développeurs apprennent très bien la syntaxe Go mais trop tardivement les aspects sécurité et supply chain. Or, dans un service moderne, ces sujets doivent être étudiés en parallèle de l’architecture applicative.

Références cloud-native et déploiement

• Guides Docker multi-stage.
• Graceful shutdown et signaux système.
• Health checks, readiness, liveness.
• Logging structuré, metrics, tracing.
• Guides d’industrialisation CI/CD et images minimales.

Objectif

• passer du “ça marche en local” à “ça vit proprement en prod”
• penser déploiement, restart, rollback, saturation, shutdown

Ce qu’il faut savoir construire

Go service
  ->
Docker multi-stage
  ->
non-root runtime
  ->
health endpoints
  ->
metrics / logs
  ->
CI/CD
  ->
safe deployment

Routine de progression idéale

1. lire une ressource courte mais fondamentale
2. implémenter un mini cas concret
3. écrire tests et logs
4. ajouter timeout / context / erreurs propres
5. benchmarker ou profiler si besoin

Indicateur de maturité

Vous progressez vraiment lorsque vous commencez à relire les docs officielles non plus comme un débutant en syntaxe, mais comme quelqu’un qui cherche à clarifier des décisions d’architecture, de perf ou d’exploitation.

Créer un timeout

ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()

WithTimeout crée un contexte enfant qui sera annulé automatiquement après une durée donnée. C’est très utile pour borner un appel externe ou un bloc de travail précis.

Créer une deadline absolue

deadline := time.Now().Add(2 * time.Second)
ctx, cancel := context.WithDeadline(context.Background(), deadline)
defer cancel()

Choisir timeout ou deadline

• Timeout : durée relative, le plus fréquent.
• Deadline : échéance absolue, pratique quand elle est déjà connue plus haut.

Lecture des erreurs associées

err := doWork(ctx)
if err != nil {
    if errors.Is(err, context.DeadlineExceeded) {
        // timeout
    }
    if errors.Is(err, context.Canceled) {
        // cancellation
    }
}

Bonne pratique

• Définir des timeouts réalistes par type d’opération.
• Éviter les timeouts globaux arbitrairement trop courts ou trop longs.
• Documenter les budgets de temps critiques : HTTP, DB, appels sortants.

Propagation correcte

func (s Service) GetUser(ctx context.Context, id int64) (User, error) {
    return s.store.FindByID(ctx, id)
}

Le contexte doit être propagé sans être recréé inutilement à chaque couche. Si un handler reçoit r.Context(), le service, le repository et les appels HTTP/DB descendants doivent recevoir ce même contexte, ou un dérivé plus strict si nécessaire.

Convention de signature

func DoSomething(ctx context.Context, arg string) error

• ctx premier argument.
• Nom court standard ctx.
• Ne jamais stocker un contexte dans une struct pour un usage permanent.

Quand dériver un contexte

• Ajouter un timeout spécifique plus court.
• Créer un sous-travail annulable séparément.
• Associer une valeur request-scoped pertinente.

childCtx, cancel := context.WithTimeout(ctx, 500*time.Millisecond)
defer cancel()

err := callExternal(childCtx)

Request-scoped values : usage légitime

Les valeurs de contexte sont utiles pour quelques informations transverses et légères, liées à une requête ou à une exécution : request ID, trace ID, identité authentifiée, tenant, corrélation technique.

type ctxKey string

const requestIDKey ctxKey = "request_id"

ctx = context.WithValue(ctx, requestIDKey, "req-123")

Lecture

if v := ctx.Value(requestIDKey); v != nil {
    requestID, _ := v.(string)
    _ = requestID
}

À ne pas faire

• Y stocker une config globale.
• Y stocker un logger unique central si d’autres approches plus explicites sont possibles.
• Y placer des objets lourds ou métiers arbitraires.
• Transformer le contexte en sac universel pour éviter de passer des paramètres normaux.

Règle de discipline

HTTP entrant : le contexte de la requête

func handler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()
    _ = ctx
}

Le contexte porté par *http.Request est la base naturelle à propager. Il est annulé lorsque le client se déconnecte, lorsque le serveur annule le traitement ou lorsque le handler termine dans certains scénarios supervisés.

HTTP sortant avec contexte

req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
if err != nil {
    return err
}

resp, err := httpClient.Do(req)

Pourquoi c’est si important

• Un appel downstream ne doit pas survivre indéfiniment à la requête amont.
• Les budgets de temps doivent se propager entre services.
• Les annulations client doivent interrompre les appels réseau inutiles.

Base de données avec contexte

row := db.QueryRowContext(ctx,
    "select email from users where id = $1",
    id,
)

rows, err := db.QueryContext(ctx, query)
if err != nil {
    return fmt.Errorf("query users: %w", err)
}
defer rows.Close()

Pourquoi

• Les requêtes longues peuvent être stoppées si la requête amont est annulée.
• Le pool de connexions est moins exposé à des travaux devenus inutiles.
• Les budgets de temps deviennent cohérents entre HTTP, service et DB.

Autres opérations I/O

• Clients RPC.
• Queues et consumers.
• Caches réseau.
• Appels à APIs externes.
• Opérations de fichiers longues si votre abstraction le permet.

Goroutines annulables

go func() {
    for {
        select {
        case <-ctx.Done():
            return
        case job := <-jobs:
            _ = job
        }
    }
}()

Une goroutine qui dépend d’une requête, d’un batch, d’un worker supervisor ou d’un shutdown doit écouter ctx.Done(). Sinon, elle risque de continuer à travailler alors que son résultat n’est plus attendu.

Pattern recommandé

Règle utile

• Chaque goroutine doit avoir un owner.
• Chaque worker doit savoir quand s’arrêter.
• L’arrêt doit drainer ou fermer proprement les flux concernés.

Shutdown propre

ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
defer stop()

shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

if err := srv.Shutdown(shutdownCtx); err != nil {
    return err
}

Le shutdown propre consiste à annoncer l’arrêt, arrêter d’accepter de nouveaux travaux, laisser les requêtes/traitements en vol se terminer ou s’annuler proprement, puis fermer les ressources.

Ordre logique de fermeture

1. capturer le signal
2. bloquer les nouvelles entrées
3. annuler ou laisser finir les traitements en cours
4. fermer serveurs, workers, DB, queues selon politique

Erreurs liées au contexte

if errors.Is(err, context.DeadlineExceeded) {
    // timeout
}

if errors.Is(err, context.Canceled) {
    // cancellation
}

Lecture métier / opérationnelle

• DeadlineExceeded signifie généralement que le budget de temps a été consommé.
• Canceled signifie qu’un parent a demandé l’arrêt : client parti, shutdown, parent annulé, etc.

Mapping fréquent

Ce que montre cet exemple

• propagation du contexte HTTP entrant
• timeout plus strict au niveau service
• Query DB avec QueryRowContext
• mapping des erreurs de contexte
• shutdown propre au signal système

Améliorations possibles

• ajouter request ID en value
• ajouter logs structurés et traces
• gérer un worker pool annulable
• ajouter retries sélectifs sur certains appels sortants

net/http : socle natif très puissant

mux := http.NewServeMux()

mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
    w.WriteHeader(http.StatusOK)
    _, _ = w.Write([]byte("ok"))
})

La standard library suffit largement pour beaucoup d’APIs. Elle fournit serveur, client, handlers, middleware chainables, tests HTTP et propagation de contexte.

Serveur typique

srv := &http.Server{
    Addr:              ":8080",
    Handler:           mux,
    ReadHeaderTimeout: 5 * time.Second,
    ReadTimeout:       10 * time.Second,
    WriteTimeout:      15 * time.Second,
    IdleTimeout:       60 * time.Second,
}

Pourquoi commencer par la stdlib

• Compréhension profonde du modèle HTTP Go.
• Moins de magie cachée.
• Interopérabilité élevée avec les middlewares.
• Base très stable et très bien documentée.

Quand ajouter un routeur externe

• Si vous voulez un routing plus avancé.
• Si les path params complexes deviennent nombreux.
• Si votre équipe a standardisé un composant précis.

Handlers : courts, explicites, testables

func (a App) createUser(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()
    _ = ctx
}

Responsabilités saines d’un handler

• Lire les paramètres de route, query et body.
• Valider l’entrée ou déclencher la validation.
• Appeler un service.
• Mapper le résultat en JSON + status code.
• Ne pas contenir la logique métier profonde.

Exemple simple

func (a App) healthz(w http.ResponseWriter, r *http.Request) {
    if r.Method != http.MethodGet {
        http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
        return
    }

    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusOK)
    _, _ = w.Write([]byte(`{"status":"ok"}`))
}

Convention utile

• Un handler par responsabilité claire.
• Pas de fonction de 300 lignes.
• Décoder, valider, appeler, répondre.

Décoder JSON

var in struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

if err := json.NewDecoder(r.Body).Decode(&in); err != nil {
    http.Error(w, "invalid json", http.StatusBadRequest)
    return
}

Encoder JSON

w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusCreated)
_ = json.NewEncoder(w).Encode(out)

Bonnes pratiques JSON

• Définir des DTOs clairs.
• Éviter de mélanger directement modèles DB et payloads publics quand les contraintes divergent.
• Valider après décodage.
• Contrôler les champs exposés.

type UserResponse struct {
    ID    int64  `json:"id"`
    Email string `json:"email"`
}

Validation d’entrée

if strings.TrimSpace(in.Name) == "" {
    http.Error(w, "name is required", http.StatusBadRequest)
    return
}
if !strings.Contains(in.Email, "@") {
    http.Error(w, "invalid email", http.StatusBadRequest)
    return
}

La validation peut rester simple pour de nombreux cas. L’essentiel est qu’elle soit cohérente, centralisée à un niveau clair et qu’elle différencie bien les erreurs de client des erreurs serveur.

Stratégies possibles

• Validation légère dans le handler.
• Validation portée par le DTO ou le service.
• Agrégation d’erreurs de champ pour les payloads plus riches.

Principe important

Middlewares utiles

• logging de requête
• recovery
• authentification
• rate limiting
• request ID / correlation ID
• CORS si nécessaire

func logging(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        next.ServeHTTP(w, r)
        _ = start
    })
}

Ordre important

L’ordre de la chaîne middleware change le comportement réel. Par exemple, le recovery doit souvent entourer l’ensemble, et le request ID doit être disponible avant les logs.

Auth : séparation claire

L’authentification et l’autorisation doivent être visibles, compréhensibles et testables. Une bonne pratique est de faire l’authentification en middleware, puis de laisser le handler ou le service appliquer les règles métier d’autorisation fines.

func authMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        token := r.Header.Get("Authorization")
        if token == "" {
            http.Error(w, "unauthorized", http.StatusUnauthorized)
            return
        }
        next.ServeHTTP(w, r)
    })
}

Règles saines

• 401 pour absence/échec d’authentification.
• 403 pour utilisateur authentifié mais non autorisé.
• Ne pas fuiter trop d’informations sur la raison exacte.
• Propager une identité proprement au service si nécessaire.

Timeouts serveur

srv := &http.Server{
    Addr:              ":8080",
    Handler:           mux,
    ReadHeaderTimeout: 5 * time.Second,
    ReadTimeout:       10 * time.Second,
    WriteTimeout:      15 * time.Second,
    IdleTimeout:       60 * time.Second,
}

Contexte de requête

ctx := r.Context()

Toute requête descendante — DB, HTTP externe, queue, cache — doit idéalement être branchée sur ce contexte, ou sur un enfant plus strict si besoin.

Pourquoi c’est critique

• Protège contre les connexions lentes.
• Réduit le travail inutile après déconnexion client.
• Évite les blocages infinis côté downstream.
• Facilite le shutdown propre.

req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)

Mapper proprement les erreurs

switch {
case errors.Is(err, ErrValidation):
    http.Error(w, "invalid input", http.StatusBadRequest)
case errors.Is(err, ErrNotFound):
    http.Error(w, "not found", http.StatusNotFound)
default:
    http.Error(w, "internal error", http.StatusInternalServerError)
}

Table mentale utile

Règle essentielle

• Ne jamais exposer les détails internes complets au client.
• Garder les détails riches pour logs, traces et metrics.
• Répondre avec un message simple, stable et sûr.

Tester les handlers avec httptest

req := httptest.NewRequest(http.MethodGet, "/healthz", nil)
rr := httptest.NewRecorder()

handler(rr, req)

if rr.Code != http.StatusOK {
    t.Fatalf("expected 200, got %d", rr.Code)
}

Ce qu’il faut observer en production

• latence p50 / p95 / p99
• codes de retour
• taux d’erreur
• timeouts et cancellations
• trafic par route

Logging structuré HTTP

logger.Info(
    "http request",
    "method", r.Method,
    "path", r.URL.Path,
    "status", status,
    "duration_ms", duration.Milliseconds(),
)

Observabilité minimale

• request ID
• logs structurés
• metrics par route et code HTTP
• tracing sur opérations critiques

Ce que montre cet exemple

• handler court
• validation explicite
• service séparé
• storage injecté
• JSON propre
• timeouts + context
• logging + recovery middleware

Améliorations possibles

• ajouter auth middleware
• ajouter request ID
• ajouter tests httptest
• ajouter métriques Prometheus
• ajouter graceful shutdown