Mise à niveau vers Go 1.27 : Ce qui casse, ce qu'il faut adopter en premier

Go 1.27 est sorti en août 2026, et pour la plupart des modules, la mise à niveau consiste en une seule ligne dans go.mod suivie d’un passage de go fix — mais quelques changements font mal silencieusement. Voici ce qui casse réellement et ce qu’il faut adopter en premier.

Les changements majeurs sont structurels : encoding/json est désormais basé sur la nouvelle implémentation json/v2 en coulisses, le paquet uuid a rejoint la bibliothèque standard, et les méthodes peuvent enfin déclarer leurs propres paramètres de type. Aucun de ces éléments n’impose une réécriture, et l’équipe Go a maintenu la promesse de compatibilité habituelle — presque tout se compile et s’exécute sans changement.

Tout n’est pas paisible, cependant. Plusieurs paramètres GODEBUG échouent désormais la compilation avec leurs anciennes valeurs, compress/flate produit des octets différents, go test applique une nouvelle vérification stdversion, et les noms de symboles générés par le compilateur ont changé. Si vous avez besoin d’un rappel de syntaxe sur les parties qui n’ont pas bougé, le Aide-mémoire Go reste valide ; ce guide couvre le reste, avec les commandes et les correctifs pour chaque élément.

Le chemin de mise à niveau en un diagramme

L’équipe Go recommande une approche où l’on compile d’abord, puis corrige. go fix réécrit le code pour les nouvelles API et les idiomés, mais seule une compilation propre vous dit si certains des changements au niveau de l’exécution vous touchent.

Commencez par la toolchain elle-même. Si vous gérez les toolchains via la commande go, épinglez la version dans go.mod ou installez-la explicitement :

go install golang.org/dl/go1.27@latest
go1.27 download
go1.27 version

Alternativement, définissez GOTOOLCHAIN=go1.27.0 dans l’environnement, ou ajoutez toolchain go1.27.0 à go.mod et laissez la commande go la récupérer. Le compagnon axé sur les modules sur la Structure du workspace Go explique comment les lignes go et toolchain interagissent entre plusieurs modules ; la version courte pour un module unique est ci-dessous.

Étape 1 : augmenter la ligne go et effacer les paramètres GODEBUG supprimés

go mod edit -go=1.27
go mod tidy
go build ./...

Augmenter la directive go active les nouvelles fonctionnalités du langage (méthodes génériques, clés de champs promus dans les littéraux de struct, inférence de type de fonction plus large) et rend la commande go stricte quant aux paramètres GODEBUG dont le support a été supprimé. Go 1.27 a supprimé définitivement ces éléments :

• asynctimerchan — les canaux de minuteur et de ticker sont désormais toujours non tamponnés
• gotypesalias
• tlsunsafeekm, tlsrsakex, tls3des, tls10server
• x509keypairleaf

La nouvelle règle : la commande go accepte toujours ces paramètres dans go.mod (entrées godebug) ou dans le code source (commentaires //go:debug) s’ils sont définis sur la valeur par défaut finale qui existait avant la suppression. Une ancienne valeur — celle qui désactivait un changement de comportement — fait échouer la compilation :

//go:debug asynctimerchan=0  // erreur de compilation : ancienne valeur d'un paramètre supprimé
//go:debug asynctimerchan=1  // accepté, mais supprimez la ligne à la place

Si votre compilation échoue ici, le code dépendait des canaux de minuteur tamponnés d’avant Go 1.23. Le correctif est dans le code, pas dans la configuration : vérifiez l’utilisation de Timer.Stop et Timer.Reset par rapport aux modèles de contexte, d’annulation et de délai d’attente qui reposent sur les canaux synchrones. La même recherche s’applique aux paramètres liés à TLS — tout ce qui épinglait tls3des=1 ou tls10server=1 maintenait en vie d’anciennes suites de chiffrement, et Go 1.27 refuse de le compiler.

Étape 2 : exécuter go test — le piège stdversion

go build et go test ne sont plus d’accord. go test de Go 1.27 exécute la vérification vet stdversion par défaut, ce qui signale les symboles de la bibliothèque standard qui sont trop récents par rapport à la version go en vigueur dans le fichier concerné.

// go.mod indique toujours "go 1.26"
func Base(p string) string {
    _, file, ok := strings.CutLast(p, "/") // ajouté dans Go 1.27
    if !ok {
        return p
    }
    return file
}

Avec une toolchain 1.27, go build réussit — le compilateur a strings.CutLast — tandis que go test échoue à l’étape vet parce que go.mod déclare encore 1.26. Avec une toolchain 1.26 réelle, le fichier ne se compilerait tout simplement pas. La leçon est procédurale : ne validez jamais une mise à niveau avec go build seul ; exécutez la suite de tests complète, puis augmentez la ligne go. La suite vet dans go test a également détecté un nouveau problème printf : fmt.Errorf("...: %w", p) où p est un *E et E implémente error avertit désormais, car l’enveloppement d’un pointeur produit des assertions de type et des vérifications errors.Is qui échouent. Ce mode d’échec apparaît dans le code de gestion des erreurs exactement comme décrit dans les modèles d’architecture de gestion des erreurs Go — vérifiez le type de l’opérande, pas seulement le verbe.

encoding/json : le moteur v2 en dessous

Le plus gros changement en coulisses : encoding/json/v2 (expérimental depuis Go 1.25 via GOEXPERIMENT=jsonv2) est promu, et le paquet classique encoding/json est désormais basé sur l’implémentation v2. Pour les appelants v1, le comportement est préservé — les tranches nulles sont toujours encodées comme null, les clés de maps sont toujours triées — avec une seule différence visible : le texte exact de certains messages d’erreur a changé. Si les tests ou la surveillance correspondent sur des chaînes d’erreur, attendez-vous à des différences.

Trois choses peuvent encore mal tourner :

1. Texte des erreurs. Toutes les assertions strings.Contains(err.Error(), ...) basées sur l’ancienne formulation v1 doivent être mises à jour.
2. Les chemins sensibles aux performances peuvent bouger. Le décodage est plus rapide, mais la réécriture change les opérations qui allouent ; les benchmarks signalés dans la CI le montreront.
3. Porte de sortie de compatibilité. GOEXPERIMENT=nojsonv2 restaure l’implémentation v1 originale au moment de la compilation. C’est temporaire — prévoyez de la supprimer, pas de l’expédier.

Un effet de second ordre pour les tests de référence (golden tests) : l’encodeur de compress/flate a changé dans la même version, donc les sorties archive/zip, compress/gzip, compress/zlib et image/png peuvent différer octet par octet par rapport à Go 1.26, même si elles se décodent identiquement. Regénérez les fixtures compressés plutôt que d’épingler les anciens octets.

Migration vers l’API v2 délibérément

L’API v2 est un import distinct (encoding/json/v2) avec Marshal, Unmarshal et un système d’options. Le chemin de migration supporté consiste à faire en sorte que les appels v2 se comportent comme v1 d’abord, puis à resserrer sélectivement :

import (
    "encoding/json/v2"
    "encoding/json/jsontext"
)

// Étape 1 : comportement identique à encoding/json — un changement sûr et mécanique
out, err := jsonv2.Marshal(v, jsonv2.DefaultOptionsV1())

// Étape 2 : opt-in pour une valeur par défaut v2 à la fois
out, err := jsonv2.Marshal(v,
    jsonv2.DefaultOptionsV1(),
    jsonv2.FormatNilSliceAsNull(false)) // les tranches nulles s'encodent désormais comme []

Une fois que vous abandonnez DefaultOptionsV1, les valeurs par défaut v2 s’appliquent, et elles sont plus strictes et plus interopérables que v1 :

Les clés de map non triées sont celles qui surprennent les tests de fichiers de référence : v2 saute le tri car cela coûte du temps. Lorsque vous avez besoin d’une sortie stable — fixtures, tests de snapshot, représentations hachées — passez json.Deterministic(true), ce qui restaure une sortie triée pour les maps et les structs. Les modèles de l’article Comparaison des ORM portent tous des balises json ; ces balises continuent de fonctionner dans v2, mais l’option de balise format a été supprimée pendant l’expérimentation et inline a été renommé en embed, donc faites une recherche dans vos définitions de modèles pour les deux avant de migrer. Pour les besoins bas niveau — flux, traitement jeton par jeton, traitement de syntaxe personnalisé — le paquet compagnon encoding/json/jsontext expose une machine à états Encoder/Decoder sur le texte JSON.

stdlib uuid : abandonner github.com/google/uuid

Go 1.27 ajoute uuid à la bibliothèque standard, implémentant la RFC 9562. La surface API couvre les cas courants :

id := uuid.New()    // actuellement équivalent à NewV4
v7 := uuid.NewV7()  // triable par temps, horodatage 48 bits + aléatoire
u, err := uuid.Parse("550e8400-e29b-41d4-a716-446655440000")

github.com/google/uuid est le deuxième module Go le plus dépendu, donc cette migration est importante à grande échelle. Les deux API sont proches — les types sont des valeurs [16]byte comparables avec == et utilisables comme clés de map, String(), MarshalText/UnmarshalText font des allers-retours — et le projet amont prépare des shim go:fix inline afin que go fix puisse réécrire les appels uuid.NewV4() vers le paquet standard et supprimer la dépendance.

La décision d’adoption intéressante est NewV7. Les UUID de version 7 imbriquent un horodatage en millisecondes dans les bits les plus significatifs, donc les valeurs se trient dans l’ordre de création (sauf si l’horloge système recule). Pour les clés primaires de base de données, cela signifie une meilleure localité d’arbres B que les UUIDv4 aléatoires, et un ordonnancement du type created_at gratuitement dans l’identifiant lui-même — la même propriété qui motive la discussion sur les clés triables par temps dans les modèles de données multi-locataires.

Changements de langage : méthodes génériques et associés

Les méthodes génériques sont la fonctionnalité de langage la plus demandée de cette version : une déclaration de méthode peut désormais déclarer ses propres paramètres de type.

// Go 1.27 : math/rand/v2 a gagné une méthode générique aux côtés de la fonction
func (r *Rand) N[Int intType](n Int) Int

Deux restrictions maintiennent le système de types décidable : les méthodes d’interface ne peuvent pas déclarer de paramètres de type, et les méthodes d’interface ne peuvent pas être implémentées par des méthodes génériques. À leurs côtés, les clés de littéraux de struct peuvent désormais être n’importe quel sélecteur de champ valide (pas seulement les noms de champs de premier niveau), et l’inférence de type de fonction se généralise à tous les contextes où une fonction générique est attribuée à une variable de type de fonction correspondant. Aucun de ces éléments ne casse le code existant ; ils suppriment les contournements — les fonctions auxiliaires génériques au niveau du paquet et les instantiations explicites.

go fix a grandi avec des modernisateurs pour des nettoyages adjacents : atomictypes, embedlit, slicesbackward et unsafefuncs. Une précaution issue des laboratoires de mise à niveau pratiques : exécutez go fix -fix=atomictypes délibérément plutôt qu’en masse sur des bibliothèques, car cela peut changer les types de variables au niveau du paquet que d’autres paquets référencent. Le modernisateur waitgroup a été renommé en waitgroupgo ; notez que sync.WaitGroup.Go (depuis 1.25) couvre déjà la plupart de ce qu’il détecte — voir les modèles de concurrence bornée pour comment il s’intègre à l’arrêt des pools de workers.

Ce qui casse silencieusement

Voici les changements qui se compilent correctement et vous coûtent tout de même une journée de release :

• Noms de symboles de littéraux de fonction. Le compilateur génère désormais des noms plus simples, indépendants de l’inlining, pour les closures, et peut fusionner les littéraux de fonction identiques. Les tests qui affirment des noms de symboles dans les tracebacks ou les profils échoueront ; le code qui compare des pointeurs de code de fonction pour l’égalité est exposé dans plus de cas.
• Alignement gofmt. Un correctif à la logique d’alignement par colonnes (elle variait auparavant selon les architectures CPU) reformate un petit nombre de fichiers déjà formatés. Attendez-vous à des différences de blancheur uniquement dans un commit gofmt ./... après la mise à niveau.
• go mod tidy réécrit go.mod. Pour les modules sur go 1.27, tidy fusionne désormais les blocs require dupliqués en au plus deux blocs (direct, indirect), préservant les commentaires. Faites la différence de votre go.mod et résolvez tout résidu de conflit de fusion avant le commit de release, pas après.
• Étiquettes de traceback. Les tracebacks pour les modules sur go 1.27 incluent les étiquettes de goroutines runtime/pprof dans la ligne d’en-tête ; désactivez avec GODEBUG=tracebacklabels=0 si les étiquettes portent des données sensibles.
• go tool trace se lie à localhost. -http=:6060 n’écoute désormais que sur localhost ; passez -http=0.0.0.0:6060 explicitement si vous avez besoin d’un accès à distance (et faites attention à ce qu’un port de profilage sur une hôte partagée est un risque — voir le flux de travail de profilage en production pour la configuration renforcée).

Expériences à surveiller

Deux paquets expérimentaux sont sortis dans 1.27, tous deux activés avec GOEXPERIMENT=simd au moment de la compilation :

• simd — une API portable, agnostique de la taille de vecteur (Int8s, Float32s, …) qui se mappe sur des instructions matérielles si disponibles. Elle prend en charge AVX/AVX2/AVX-512 sur amd64, NEON sur arm64, et WebAssembly SIMD. La bibliothèque standard utilise déjà ce mécanisme en interne : l’implémentation Swiss Table map de Go en bénéficie.
• simd/archsimd — la couche spécifique à l’architecture pour le code qui doit connaître la largeur du vecteur.

Côté cryptographie, crypto/mldsa implémente le schéma de signature post-quantique ML-DSA de FIPS 204 en trois jeux de paramètres (MLDSA44, MLDSA65, MLDSA87), intégré dans crypto/x509 et offert en tant que schémas de signature TLS 1.3. L’échange de clés post-quantique hybride peut désormais être forcé via Config.CurvePreferences même lorsque les reverts GODEBUG tlsmlkem/tlssecpmlkem sont définis. Aucun n’est un élément de migration aujourd’hui, mais tous deux façonnent la surface de configuration TLS que vos services vont embrasser.

Nouvelles API à adopter immédiatement

Quelques ajouts résolvent les frottements quotidiens et ne coûtent rien à adopter :

// strings.CutLast / bytes.CutLast — la danse LastIndex, remplacée
before, after, found := strings.CutLast("a/b/c.tar.gz", ".")

// httptest.NewTestServer — réseau factice en mémoire, nettoyage auto
srv := httptest.NewTestServer(t, mux) // pas de vrai port, pas de defer srv.Close()

httptest.NewTestServer crée un httptest.Server basé sur un réseau en mémoire au lieu d’un écouteur TCP et enregistre son propre t.Cleanup. Son vrai bénéfice est de s’appairer avec testing/synctest : les allers-retours HTTP s’exécutent dans le temps synthétique, rendant les tests de délai et de tentative rapides et déterministes — la combinaison est démontrée dans l’article tests de concurrence synctest.

Checklist de mise à niveau

L’ordre compte plus que les éléments ; chaque étape suppose que la précédente est verte.

Notes de conclusion

Les cassures de Go 1.27 se regroupent autour des bords que la plupart des programmes ne touchent jamais — reverts GODEBUG supprimés, assertions de noms de symboles, fixtures d’octets compressés — tandis que ses victoires tombent là où vit chaque programme : JSON plus rapide, UUID standards, méthodes génériques. Une mise à niveau propre est surtout une question de discipline : go build, puis go test, puis go fix, dans cet ordre, avec la ligne go augmentée avant l’exécution des tests plutôt qu’après. La porte de sortie nojsonv2 et la règle d’acceptation de asynctimerchan à la valeur par défaut finale achètent du temps, mais les deux sont programmées pour disparaître, donc traitez cette mise à niveau comme la date limite pour les corrections différées héritées de 1.23 à 1.26.