J’utilise depuis longtemps Zap comme logger. Rapide, facile à utiliser, avec beaucoup d’options, un support correct pour faire des logs structurés…​ ça fait le job.

l’intérêt de Zap est aussi son écosystème. Et bien sûr, il s’intègre avec Gin via la lib gin-contrib/zap.

Je crée ici un logger Zap (qui peut être configuré comme vous le souhaitez). J’en profite pour passer gin en ReleaseMode pour enlever certains logs de debug. je crée ensuite mon router gin que je configure avec ginzap.Ginzap. Toutes mes requêtes seront maintenant logués en utilisant mon logger zap (et donc avec sa configuration).+

J’utilise aussi ginzap.RecoveryWithZap pour log tous les panic potentiels générés par mes handlers.

Les handlers Gin sont par défaut assez légers. Voici par exemple un exemple tiré de la documentation de Gin:

Une fonction prenant un *gin.Context est associé à une méthode HTTP et à une URL (ici GET /ping.

Toute la gestion de la sérialisation des paramètres de la requête (ces paramètres pouvant venir de l’url, être passé en query ou dans le body de la requête) est à gérer à la main.
Par exemple, récupérer une variable depuis l’url de la requête (/user/:id par exemple) se fait via c.Param("id"). Récupérer un paramètre passé en query string (?foo=bar par exemple) se fait avec c.Query("foo"). Sérialiser le body d’une requête en JSON dans une struct Golang demande un appel à c.ShouldBindJSON…​

Constuire des réponses HTTP avec Gin se fait via des appels du type c.JSON(http.StatusOK, repsonse): on passe donc notre code HTTP et response qui est une struct Go qui sera ensuite convertit en JSON.

Tout cela fonctionne mais est assez pénible et répétitif à faire. C''est notamment là qu’intervient la lib Tonic.

Handlers évolués

Tonic fournit des handlers évolués. Là où en Gin classique un handler est comme vu précédemment une fonction ayant comme signature func(c *gin.Context), Tonic permet de créer des handlers prenant une struct en paramètre et en retourtant une autre, avec optionnellement une erreur.

Voici par exemple un handler Tonic:

On remarque ici plusieurs choses:

L’ajout d’un handler Tonic à un router Gin se fait de cette façon:

topic.Handler prend en paramètre mon handler et un code HTTP qui sera le code retourné si le handler ne retourne pas d’erreurs.

Nos handlers Tonic peuvent donc retourner des erreurs. Par défaut ces erreurs passent dans un hook interne à Tonic permettant de convertir l’erreur en réponse HTTP. Tonic permet de personnaliser ce hook (qui n’est pas très intéressant par défaut), et c’est ce que nous allons faire ici.

Mais réfléchissons tout d’abord à notre cahier des charges. Lorsque je fais de la gestion d’erreur sur HTTP je veux notamment:

Type d’erreur

La première chose que je fais ici est de définir un nouveau type d’erreur:

Ce type Error se compose de plusieurs champs:

Voici le reste du code pour créer ces erreurs:

La fonction Error() me convertit mon erreur en string, en concaténant les messages de l’erreur et le message de l’erreur Cause si elle existe.

Les autres fonctions me permettent de construire facilement de nouvelles erreurs, avec ou sans erreurs originelles.

Imaginons par exemple que mon API HTTP vérifie si un utilisateur existe dans une base de données. Je pourrai construire une erreur de cette manière avec Newf:

Cette erreur contient toutes les informations nécessaires pour ensuite être transformée en réponse HTTP: j’ai un message d’erreur clair, son type (not found), je sais qu’elle est exposable à l’utilisateur.

Wrap et Wrapf peuvent s’utiliser de la même manière mais permettent de construire une erreur utilisant mon nouveau type depuis une autre erreur, sans perdre cette dernière. Cela est intéressant: je pourrai comme cela retourner une réponse HTTP correcte à mon utilisateur final mais quand même log par exemple l’erreur originelle qui n’est pas perdue.

Hook Tonic

Le code du hook est assez long et je l’ai donc mis en fin d’article. Il n’est pas très propre et n’est qu’un proof of concept mais il fonctionne à peu près.

La fonction ErrorHook (qui est mon hook) reçoit mon erreur et se charge de retourner une réponse HTTP où le body sera la représentation JSON de ErrorResponse.
Cette fonction (qui retourne une autre fonction, le but étant ici de pouvoir injecter mon logger Zap dans mon hook final) va donc:

La fonction DefaultBindingHookMaxBodyBytes est un peu spéciale. C’est du code que j’ai repris de Tonic et que j’ai légèrement adapté car Tonic a par défaut un gros problème: en cas d’erreur durant la désérialisation de payloads en JSON l’erreur originelle produite par Golang est perdue et il n’est plus possible de retrouver quelle est la cause exacte de l’erreur.

J’utilise ensuite tout ça de cette manière pour intégrer Tonic avec Gin:

RegisterTagNameFunc est également nécessaire pour faire comprendre les tags Golang json ajoutés sur vos structs à Tonic.

Voici par exemple quelques exemples de message d’erreurs sur un endpoint de création d’utilisateurs sur lequel je travaille pour un projet personnel:

Parlons maintenant rapidement de Fizz. Ce projet s’intègre avec Gin et Tonic et permet de générer automatiquement la spec OpenAPI depuis les informations fournies par Tonic.

OpenAPI est un standard très intéressant, permettant de spécifier une API et générer automatiquement de la documentation ou des clients HTTP depuis cette spec. On trouve généralement deux façons de faire de l’OpenAPI aujourd’hui:

Je n’aborde pas ici la solution "j’écris la spec OpenAPI manuellement puis mon code à côté sans génération" car au final on pert complètement l’intérêt d’OpenAPI avec cette approche en plus d’avoir toutes les chances d’avoir une différence entre la spec et l’implémentation finale.
Certaines entreprises ont aussi des solutions custom pour générer de l’OpenAPI mais ce n’est pas non plus le sujet de cet article.

Reparlons de Fizz. Son README est clair donc je ne vais pas m’étendre dessus. En gros Fizz génère automatiquement la spec OpenAPI depuis les types passés aux handlers Tonic, et permet également d’ajouter des informations OpenAPI par endpoint (via fizz.OperationOption) si besoin.

Petite subtilité: par défaut Fizz va préfixer vos types OpenAPI par le nom du package Golang où se trouve les types de vos handlers Tonic. Vous pouvez faire fizzInstance.Generator().OverrideTypeName(reflect.TypeOf(MyType{}), "MyType") pour override le nom d’un type (le type Golang MyType{} s’appellera MyType donc sans préfixe dans OpenAPI).