Quel framework Go choisir quand aucun ne s’impose ?

Une application backend a une mission principale : recevoir des requêtes, les traiter, et répondre. Ces requêtes arrivent presque toujours en HTTP, le protocole du web : c’est le cas d’une API REST, appelée par un navigateur ou une application mobile.

Prenons un exemple qui nous suivra tout l’article : Carnet, un petit service fictif écrit en Go, qui gère des carnets de notes. Un client lui demande le carnet n° 42. Suivons sa requête, de son arrivée à la réponse :

Les étapes 1 à 3 se ressemblent d’une application à l’autre, et personne n’a envie de les réécrire à chaque fois. C’est le rôle du framework :

Dans le schéma, pourtant, un seul bloc porte la couleur du framework, et il est en pointillé. C’est qu’en Go la bibliothèque standard, livrée avec le langage, assure déjà l’essentiel de la plomberie. Comparons avec Java, où c’est le framework qui fait tout :

L’absence d’un grand framework en Go n’est ni un retard ni un accident. Elle découle de choix faits dès la conception du langage : une culture qui se méfie de la magie, et une bibliothèque standard à qui l’on confie l’essentiel. Deux événements récents les ont renforcés.

Une culture qui se méfie de la magie

Go a été conçu chez Google pour de grandes bases de code maintenues par beaucoup de monde, avec une obsession : que le code se lise sans surprise.

Un peu de copie vaut mieux qu’un peu de dépendance.

Tout ce qui fait la puissance de Spring, la configuration par convention, les annotations, l’injection automatique, est précisément ce que cette culture regarde avec méfiance. Un framework Go doit justifier chaque ligne qu’il ajoute.

Tout miser sur la bibliothèque standard

Cette culture a une conséquence directe : plutôt que de laisser l’écosystème fournir l’essentiel, Go le livre avec le langage. Ailleurs, la bibliothèque standard sait parler HTTP, mais on ne lui confie pas la production : la documentation de Python le dit en toutes lettres de son module http.server, et en Java le serveur vient historiquement de Tomcat ou de Jetty. En Go, la bibliothèque standard couvre presque tout ce qu’un backend utilise au quotidien :

net/http, sa pièce maîtresse

Pour un backend web, la pièce maîtresse de cette bibliothèque est net/http, le package qui assure les étapes 1 et 2 du trajet. Trois raisons en font le centre de gravité de tout l’écosystème :

Cette prise standard mérite qu’on s’y arrête, car toute la suite en dépend. C’est une interface d’une seule méthode, appelée à l’étape 4 pour faire répondre votre handler :

type Handler interface {
	ServeHTTP(ResponseWriter, *Request)
}

// Un middleware n’est qu’une fonction
// qui enveloppe un Handler dans un autre.
func Journal(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		début := time.Now()
		next.ServeHTTP(w, r)
		slog.Info("requête", "chemin", r.URL.Path, "durée", time.Since(début))
	})
}

Un framework qui garde cette prise hérite de tout cela gratuitement. Un framework qui la remplace doit réécrire ces briques ou fournir des adaptateurs.

Deux événements qui ont changé la donne

Le premier a montré, à grande échelle, ce que vaut la prise standard : comme gorilla/mux la garde, les équipes concernées ont pu changer de routeur en ne réécrivant que la déclaration des routes. Le second a retiré aux routeurs tiers leur argument le plus simple. Depuis, « la bibliothèque standard suffit » n’est plus une posture de puriste, mais une option raisonnable pour beaucoup de services.

En Go, un framework est un assemblage

Dernière différence, celle qui déroute le plus en venant de Java : Spring Boot couvre toute la pile, alors qu’un framework web Go ne couvre presque toujours que la couche HTTP. Le reste se choisit pièce par pièce, quel que soit le framework.

La colonne du milieu est presque pleine. En Go, « choisir un framework » veut donc dire choisir la couche qui transforme une requête HTTP en appel à votre code, et décider à quelle distance de la bibliothèque standard on la place. Seules exceptions : quelques plateformes complètes, comme Encore, qui prennent en charge une grande partie du tableau.

Pour comparer des outils aussi différents, il faut une grille. Huit critères la composent. Le premier domine tous les autres, parce qu’il découle directement de la philosophie du langage. Et celui qu’on cite toujours en premier, la vitesse, n’en fait presque pas partie.

1. 1La distance à la bibliothèque standard
2. 2La gestion des erreurs
3. 3La lecture des entrées
4. 4Le contrat et la documentation
5. 5L’observabilité
6. 6La maintenance
7. 7Les protocoles
8. 8L’équipe
9. ✕La vitesse brute

1La distance à la bibliothèque standard, le critère par excellence

Go mise tout sur sa bibliothèque standard, et pour le web sur net/http. Un framework Go se juge donc d’abord à ce qu’il met entre votre code et elle :

Cette distance a un prix, qu’on ne paie qu’au moment de partir :

Ce jour arrive plus souvent qu’on ne le croit :

Comment la mesurer : la signature

La distance se lit en une ligne, à l’étape 4 du trajet : la signature des handlers, c’est-à-dire ce qu’ils reçoivent et ce qu’ils renvoient. Plus elle s’éloigne de la prise standard, http.Handler, plus la distance est grande. Voici la signature d’un handler dans cinq outils :

Voici ce que cela change pour deux projets identiques, l’un écrit avec Chi, l’autre avec Gin, au moment de les quitter :

Ce n’est pas un défaut : c’est un échange, confort contre liberté. Mais il se décide le premier jour, pas le jour du départ.

Les sept autres critères

Une fois la distance mesurée, reste à savoir ce que le framework vous donne en échange. Sept critères le disent.

Et la vitesse ?

Ouvrez n’importe quel comparatif de frameworks Go : il commence par un graphique de requêtes par seconde. C’est le critère le plus visible et, pour la plupart des projets, le moins pertinent. Le banc d’essai de routeurs le plus cité, go-http-routing-benchmark, n’est plus mis à jour depuis 2020, et les résultats publiés dans son README ont été mesurés avec Go 1.3, en 2014. On y voit qu’un routeur rapide trouve une route en une centaine de nanosecondes, et un routeur lent en quelques microsecondes. La différence est réelle, mais il faut la remettre à sa place.

Le moteur HTTP, en revanche, peut compter, dans un cas précis : un serveur qui reçoit un très grand nombre de petites requêtes et ne fait presque rien de chacune (un proxy, une passerelle, un collecteur d’événements). La seule façon de le savoir, c’est de profiler votre service, avec pprof, sous votre charge. Si le serveur HTTP n’apparaît pas en haut du profil, le framework n’est pas votre problème de performance.

Avec ces critères en main, on peut reformuler la question de départ. Celle qu’on pose partout n’a pas de réponse ; celle qu’il faut se poser en a une, différente pour chaque projet.

La première question n’a pas de réponse : les classements qui prétendent y répondre comparent surtout des microbenchmarks. La seconde en a une, différente pour chaque projet. Je dirai aussi lequel j’aime le plus, et pourquoi.

Chaque moitié de la bonne question se pèse avec les critères de la partie 3 :

Pour l’appliquer, sept questions concrètes, à poser en équipe avant d’écrire la première route. Les réponses désignent presque toujours le bon candidat :

1. Qu’est-ce que la bibliothèque standard ne me donne pas ?critères 2 à 8Faites-en la liste, par écrit. Si elle est courte, la bibliothèque standard et vingt lignes d’adaptateur suffisent peut-être.
2. Qui consomme cette API ?critère 4Vos propres applications, ou des partenaires ? Si un contrat publié est un livrable, les outils « contrat d’abord » passent devant tous les autres.
3. Quels protocoles dans deux ans ?critère 7HTTP/2, gRPC, flux, WebSocket : tout ce qui s’ajoute plus tard est plus simple près de la bibliothèque standard.
4. Qui maintiendra ce code ?critère 8Pas l’équipe d’aujourd’hui : celle de dans trois ans. Ce qu’elle connaît déjà, et ce qu’elle trouvera facilement en ligne.
5. Qui maintient l’outil, et à quel rythme casse-t-il ?critère 6Date de la dernière version, nombre de mainteneurs actifs, historique des versions majeures.
6. Que faudrait-il réécrire pour partir ?critère 1Regardez la signature des handlers. C’est la réponse la plus honnête que vous obtiendrez.
7. Mon code métier importe-t-il le framework ?critère 1La réponse doit être non, quel que soit l’outil choisi. C’est la seule règle qui vaut pour tous les candidats.

Sept candidats, rangés du plus proche de la bibliothèque standard au plus lointain. Pour chacun : une présentation, sa position sur les huit critères, les situations où il est le plus à sa place, ses défis et ses risques, et mon verdict.

mux := http.NewServeMux()
mux.HandleFunc("GET /carnets/{id}",
	func(w http.ResponseWriter, r *http.Request) {
		c, err := store.Carnet(r.Context(), r.PathValue("id"))
		if errors.Is(err, ErrIntrouvable) {
			http.Error(w, "carnet introuvable", http.StatusNotFound)
			return
		}
		if err != nil {
			http.Error(w, "erreur interne", http.StatusInternalServerError)
			return
		}
		w.Header().Set("Content-Type", "application/json")
		json.NewEncoder(w).Encode(c)
	})

mux := http.NewServeMux()
mux.HandleFunc("GET /healthz", healthz)

admin := http.NewServeMux()
admin.HandleFunc("GET /admin/utilisateurs", lister)
admin.HandleFunc("POST /admin/utilisateurs/{id}/suspendre", suspendre)
mux.Handle("/admin/", exigerAdmin(admin))

// Les middlewares globaux s’empilent à la main,
// du plus intérieur au plus extérieur.
var h http.Handler = mux
h = journal(h)
h = récupérer(h)
http.ListenAndServe(":8080", h)

r := chi.NewRouter()
r.Use(middleware.RequestID, middleware.Recoverer)
r.Use(journal)

r.Get("/healthz", healthz)

r.Route("/admin", func(r chi.Router) {
	r.Use(exigerAdmin)
	r.Get("/utilisateurs", lister)
	r.Post("/utilisateurs/{id}/suspendre", suspendre)
})

http.ListenAndServe(":8080", r)

// Handler est un http.Handler qui renvoie une erreur.
type Handler func(w http.ResponseWriter, r *http.Request) error

func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
	if err := h(w, r); err != nil {
		écrireErreur(w, r, err) // un seul endroit pour les codes, le format JSON et les journaux
	}
}

// L’erreur métier devient une réponse HTTP ici, et nulle part ailleurs.
func écrireErreur(w http.ResponseWriter, r *http.Request, err error) {
	statut, message := http.StatusInternalServerError, "erreur interne"
	switch {
	case errors.Is(err, carnet.ErrIntrouvable):
		statut, message = http.StatusNotFound, "carnet introuvable"
	case errors.Is(err, carnet.ErrInvalide):
		statut, message = http.StatusBadRequest, err.Error()
	default:
		slog.ErrorContext(r.Context(), "requête en échec", "err", err, "chemin", r.URL.Path)
	}
	écrireJSON(w, statut, map[string]string{"erreur": message})
}

func (a *API) obtenirCarnet(w http.ResponseWriter, r *http.Request) error {
	c, err := a.carnets.Obtenir(r.Context(), r.PathValue("id"))
	if err != nil {
		return err
	}
	return écrireJSON(w, http.StatusOK, c)
}

func (a *API) Routes() http.Handler {
	r := chi.NewRouter()
	r.Use(middleware.RequestID, middleware.Recoverer)
	r.Method("GET", "/carnets/{id}", Handler(a.obtenirCarnet))
	return r
}

type CarnetEntrée struct {
	ID string `path:"id" maxLength:"36" doc:"Identifiant du carnet"`
}
type CarnetSortie struct {
	Body Carnet
}

r := chi.NewRouter()
r.Get("/healthz", healthz) // les routes internes restent en Chi pur

// L’API publique passe par Huma, qui génère /openapi.json et la documentation
api := humachi.New(r, huma.DefaultConfig("Carnet", "1.0.0"))
huma.Get(api, "/carnets/{id}",
	func(ctx context.Context, in *CarnetEntrée) (*CarnetSortie, error) {
		c, err := store.Carnet(ctx, in.ID)
		if errors.Is(err, ErrIntrouvable) {
			return nil, huma.Error404NotFound("carnet introuvable")
		}
		if err != nil {
			return nil, err
		}
		return &CarnetSortie{Body: c}, nil
	})

r := gin.New()
r.Use(gin.Recovery())
r.GET("/carnets/:id", func(c *gin.Context) {
	carnet, err := store.Carnet(c.Request.Context(), c.Param("id"))
	if errors.Is(err, ErrIntrouvable) {
		c.JSON(http.StatusNotFound, gin.H{"erreur": "carnet introuvable"})
		return
	}
	if err != nil {
		c.AbortWithStatus(http.StatusInternalServerError)
		return
	}
	c.JSON(http.StatusOK, carnet)
})

e := echo.New()
e.Use(middleware.Recover())
e.GET("/carnets/:id", func(c *echo.Context) error {
	carnet, err := store.Carnet(c.Request().Context(), c.Param("id"))
	if errors.Is(err, ErrIntrouvable) {
		return echo.NewHTTPError(http.StatusNotFound, "carnet introuvable")
	}
	if err != nil {
		return err // le gestionnaire central répondra 500
	}
	return c.JSON(http.StatusOK, carnet)
})

app := fiber.New()
app.Get("/carnets/:id", func(c fiber.Ctx) error {
	carnet, err := store.Carnet(c.Context(), c.Params("id"))
	if errors.Is(err, ErrIntrouvable) {
		return fiber.NewError(fiber.StatusNotFound, "carnet introuvable")
	}
	if err != nil {
		return err
	}
	return c.JSON(carnet)
})

//encore:api public method=GET path=/carnets/:id
func Obtenir(ctx context.Context, id string) (*Carnet, error) {
	c, err := store.Carnet(ctx, id)
	if errors.Is(err, ErrIntrouvable) {
		return nil, &errs.Error{Code: errs.NotFound, Message: "carnet introuvable"}
	}
	return c, err
}

Les fiches partent des candidats ; la boussole fait le chemin inverse. Elle part de votre projet, pose quatre questions et vous indique par quel candidat commencer. Elle ne remplace pas le raisonnement des parties précédentes : elle le résume.

Si vous ne deviez garder qu’une page de cet article, ce serait celle-ci.

1. En Go, la bibliothèque standard fait déjà l’essentiel

   Le serveur HTTP, le routeur, les tests : un framework n’y fournit pas le socle, seulement du confort par-dessus.

2. Le critère par excellence : la distance

   Plus un outil s’éloigne de la bibliothèque standard, plus il en fait pour vous, et plus la sortie coûte. La signature de ses handlers le dit en une ligne.

3. La plus petite distance qui vous suffit

   Listez ce que la bibliothèque standard ne vous donne pas, prenez l’outil le plus proche qui le couvre, et gardez le métier à l’abri du framework.

À vous de jouer

Je n’ai donné que ma lecture, et mes préférences. J’aimerais beaucoup connaître les vôtres.