albertsko/go-skill

1. Périmètre

Ces pratiques supposent la sémantique du langage Go 1.27, les valeurs par défaut de l’environnement d’exécution et la configuration par défaut des expérimentations.

2. Chemins vers les fichiers de concepts

Naviguez en fonction du code et de la tâche concernés, en vous concentrant sur le code modifié pour une modification ou un diff. L’index combine les sujets et les modèles de code illustratifs. X, T, x et v représentent n’importe quel nom. Ouvrez chaque référence correspondante, y compris les chemins supplémentaires ci-dessous.

Trouvez une pratique par le préfixe d’ID dans son en-tête et citez son ID complet. Suivez Pratique, utilisez Exemple comme idiome, et consultez Pourquoi, Exceptions et Compromis pour les mécanismes, l’applicabilité et les coûts. Les Signaux identifient les pratiques potentiellement manquantes.

Ouvrez également ces références pour les protections ou symptômes manquants :

• Incompatibilités de version de langage de module ou de fichier, contraintes de compilation ou remplacements de comportement d’exécution : MOD.
• Code qui vérifie ou ignore une error : ERH.
• Goroutines ou canaux : CTX, GOR et SHR.
• Entrées/sorties bloquantes (réseau, base de données, HTTP, fichiers) ou un gestionnaire HTTP : CTX.
• Tests de code concurrent : TBA et TST.
• Mémoire ou nombre de goroutines qui augmente : PRO et MRT.
• CPU GC élevé ou programme dans un conteneur : BRT, PRO et TRC.
• Chemin chaud ou demande d’accélération du code : PRO, ALO et BEN.

2.1 Langage

• CST code-structure.md : masquage, noms de paquets/intégrés (url, len, new, max), retours anticipés (else après return), func init().
• STD struct-design.md : accesseurs (GetX/SetX), incorporation (sync.Mutex), littéraux de champs promus, options fonctionnelles (NewXWithY, arguments Config), new(expr) et helpers de pointeurs (ptr[T], intPtr).
• INT interfaces.md : création/propriété d’interface, interfaces à implémentation unique, résultats concrets vs interfaces, any/interface{}, interfaces/erreurs typées nil.
• GEN generics.md : paramètres de type ([T any]), contraintes (comparable, ~int, ~string, cmp.Ordered, golang.org/x/exp/constraints), inférence, méthodes génériques, contraintes auto-référentielles.
• FNM functions-and-methods.md : récepteurs valeur/pointeur ou mixtes, récepteurs de valeur portant un mutex, résultats nommés (n int, err error), retours nus.
• LOP loops.md : copies de range (v.field =), évaluation d’expression, variables par itération (v := v, &v, fermetures de goroutine), range n, for i := 0; i <, slices.Backward, breaks étiquetés, break dans switch/select.
• ITR iterators.md : consommation/création d’itérateur, iter.Seq/iter.Seq2 (y compris les paramètres), yield, iter.Pull, Next()/Value(), méthodes retournant tous les éléments sous forme de slices, slices.Collect.
• DEF defer-and-cleanup.md : defer dans les boucles, évaluation différée des arguments/récepteurs, nettoyage io.Closer (defer f.Close(), resp.Body, rows.Close()), erreurs Close/Sync, os.Create.

2.2 Données

• NUM numbers.md : octal (0644), débordement d’entiers (int32(, math.MaxInt), float ==, NaN/Inf, math.FMA.
• SLC slices.md : longueur/capacité, aliasing d’append, préallocation (make([]), nil/vide ([]T{}, s == nil), vérifications len, copy/slices.Clone, [low:high:max], conversion slice vers tableau.
• COL collection-helpers.md : min/max, slices insert/delete/sort/search, maps, cmp, clear. Formes anciennes : sort.Slice, math.Min/math.Max, append(s[:i], s[i+1:]...), boucles de suppression de map delete.
• MAP maps.md : dimensionnement de map (make(map, map[K]V{}), clés triées (maps.Keys, sort.Strings), écritures pendant l’itération de map.
• MRT memory-retention.md : caches/maps longue durée (map à côté d’un mutex, suppression, taille après pic), sous-chaînes/sous-slices retenues, mise à zéro des pointeurs abandonnés, strings.Clone/bytes.Clone, runtime.AddCleanup/runtime.SetFinalizer, unique.*, weak.*.
• CMP comparison.md : types comparables (== sur les interfaces/structs, [T comparable]), slices.Equal/maps.Equal, reflect.DeepEqual, valeurs de fonction (runtime.FuncForPC).
• STX strings-text.md : octets/runes (len(s) comme nombre de caractères, []rune), validation UTF-8 (utf8), string(int), range de chaîne, tables unicode.
• SPR strings-processing.md : Trim*/Cut*, SplitSeq/FieldsSeq/Lines, strings.Split/strings.Index, strings.Builder, boucles += sur chaîne, bytes/bytes.Buffer, fmt.Append*/strconv.Append*, []byte(fmt.Sprintf(.

2.3 Erreurs

• PAN panics.md : panic vs error, recover, Must, panic(nil)/panicnil, debug.SetCrashOutput.
• ERC errors-creating.md : encapsulation (%w/%v, fmt.Errorf, return err/return nil, err sans contexte), errors.New, sentinelles (var Err) vs types d’erreur (Error() string), errors.Join, ErrUnsupported.
• ERH errors-handling.md : errors.Is/errors.AsType, err ==, err.(type), errors.As, comparaisons de messages, sentinelles de timeout/annulation (net.Error, os.ErrDeadlineExceeded, context.DeadlineExceeded), vérification de err avant les résultats, erreurs ignorées (_ =, x, _ :=).
• LOG logging.md : configuration de log/slog et journalisation d’erreurs, log.Printf/log.Println, journalisation et retour de la même erreur.

2.4 Concurrence

• CND concurrency-design.md : concurrence vs parallélisme, seuils de lancement (goroutine par élément), dimensionnement du pool de workers, runtime.NumCPU(), GOMAXPROCS.
• SHR shared-state.md : courses de données, relation « se produit avant », conditions de course, mutex vs canal, écritures de goroutine, sync.Mutex/RLock, formatage sous verrous (fmt.Sprintf), append/maps partagés.
• SYN sync-primitives.md : atomiques typés (sync/atomic, atomic.Pointer, atomic.AddInt64/atomic.Value, n++ de goroutine), sync.Map, sync.Once/sync.OnceValue, sync.Cond, valeurs sync copiées.
• GOR goroutine-lifecycle.md : fuites de goroutines, plan d’arrêt/propriétaire, expéditeurs bloqués après retour anticipé, canaux de résultats non tamponnés, go func(), sync.WaitGroup, wg.Add/wg.Go, errgroup (g.Go, SetLimit).
• CHA channels.md : canaux de notification et dimensionnement (make(chan, chan bool, chan struct{}), priorité select, canaux nil, close.
• CTX context.md : passage de context.Context, defer cancel()/context.WithTimeout, ctx.Done() autour des opérations bloquantes, clés de valeur (context.WithValue, ctx.Value), context.Background() en dehors de main.
• CXC context-cancellation.md : causes d’annulation (ctx.Err(), <-ctx.Done(), context.Canceled/context.DeadlineExceeded/context.Cause, WithCancelCause), context.AfterFunc, tâches de fond (WithoutCancel, r.Context() de goroutine), signal.Notify/signal.NotifyContext.

2.5 Bibliothèque standard

• TIM time.md : unités de time.Duration/nombres nus, comparaison de time.Time (==), minuteries dans les boucles (time.After), time.NewTimer, time.Tick.
• JSN json.md : encoding/json, encoding/json/v2, balises JSON (omitzero, omitempty), marshaleurs incorporés, décodage de nombres (json.Unmarshal dans map[string]any).
• SQL database-sql.md : database/sql, sql.Open, PingContext, taille du pool, arguments de requête/instructions préparées (db.Query, .Exec, QueryRow, ExecContext, SQL via fmt.Sprintf), sql.Null[T], rows.Next/rows.Err.
• IOF io-and-files.md : paramètres io.Reader/io.Writer et fs.FS, filename string, os.Open, os.ReadFile, os.DirFS, os.Root, filepath.Join avec entrée utilisateur.
• HCL http-client-and-net.md : timeouts/partage/pools client (http.Get, http.Post, http.DefaultClient, http.Client, http.Transport), net/netip vs net.IP/net.ParseIP, net.JoinHostPort vs fmt.Sprintf("%s:%d".
• HSV http-server.md : gestionnaires (http.ResponseWriter, *http.Request, http.Handler, r.Body/r.Method), motifs ServeMux/HandleFunc, http.Error, timeouts serveur (http.ListenAndServe, http.Server), MaxBytesHandler, ResponseController, CrossOriginProtection.
• RND randomness-and-ids.md : uuid, crypto/rand, math/rand, math/rand/v2, rand.Seed.

2.6 Tests

• TBA testing-basics.md : catégories de test/balises de construction (func TestX, //go:build integration), -race, t.Parallel, -shuffle, tests pilotés par table/t.Run, helpers, paquets _test externes.
• TST testing-state.md : t.Cleanup, TestMain, t.Context vs context.Background() de test, t.Chdir/t.Setenv/t.TempDir vs os.Chdir/os.Setenv/os.MkdirTemp, testing/synctest, temps de test/time.Sleep, cryptotest.
• TTL testing-tools.md : httptest, testing/iotest, fstest, slogtest, fuzzing (func FuzzX).
• BEN benchmarks.md : func BenchmarkX, b.Loop vs b.N/b.ResetTimer, entrée représentative/réutilisation, benchstat.
• COV coverage-and-test-output.md : -coverpkg, -cover, go build -cover/GOCOVERDIR, t.Output/t.Attr/t.ArtifactDir, test fmt.Println, go test -json.

2.7 Performance

Appliquez les pratiques de disposition, d’allocation et d’inlining uniquement à un chemin chaud identifié par un benchmark, un profil ou une trace.

• PRO profiling.md : pprof (net/http/pprof, /debug/pprof, runtime/pprof, pprof.Lookup), diffs de tas, vidages de goroutines, profils goroutineleak/block/mutex (SetBlockProfileRate, SetMutexProfileFraction), étiquettes (pprof.Do), compteurs de goroutines (runtime/metrics).
• TRC tracing.md : traces d’exécution (runtime/trace, trace.Start), enregistreur de vol (FlightRecorder), pics de latence/requêtes lentes rares, pauses de planification/GC.
• MLY memory-layout.md : localité de cache/stride (boucles chaudes []*T), faux partage (compteurs par goroutine dans une même slice), parallélisme au niveau instruction, alignement de champs, structs.HostLayout.
• ALO allocations.md : analyse d’échappement (-gcflags, retour de pointeurs locaux), tampons appartenant à l’appelant, conversions élidées par le compilateur (string(b) chaud), allocs/op, sync.Pool.
• BRT build-and-runtime-tuning.md : inlining, PGO (default.pgo), GOGC/GOMEMLIMIT/debug.SetGCPercent, GOMAXPROCS sensible au conteneur (automaxprocs, runtime.GOMAXPROCS).
• CGO cgo.md : regroupement d’appels cgo (import "C", C.), directives #cgo (noescape, nocallback).

2.8 Projet et outils

• PKG packages-and-docs.md : structure du projet, cohésion/noms de paquets (util, common), alias (type X = Y, //go:fix inline), commentaires de doc, commentaires de doc exportés manquants, Deprecated:, exemples (func ExampleX).
• TOL tooling.md : gofmt, go vet, linters (golangci-lint), directives tool/tools.go, go fix moderniseurs, vérifications de test vet (-vet=), scripts CI, @latest.
• MOD modules-and-builds.md : hygiène de go.mod/replace, godebug///go:debug, espaces de travail (go.work), contraintes de construction (//go:build, // +build).

3. Appliquer à la tâche

• Écrire du code : satisfaire chaque pratique applicable dans les fichiers routés.
• Réviser du code : lorsque des commandes sont disponibles, exécutez d’abord go vet ./..., go test -race ./... et go fix -diff ./..., en utilisant une copie si le code doit rester intact. Vérifiez chaque puce Signaux dans chaque fichier routé. Excluez les occurrences couvertes par Exceptions. Signalez les autres sous la forme ID | fichier:ligne | ce qui ne va pas | correction. Pour les pratiques qui se chevauchent, citez l’ID le plus spécifique en premier, puis les autres. Utilisez - pour les problèmes qu’aucune pratique ne couvre. Ordonnez par impact : résultats erronés, courses, paniques, fuites, blocages, puis problèmes de ressources/performance, puis idiomes obsolètes/style.
• Déboguer : faites correspondre les symptômes aux Signaux et à Pourquoi, confirmez le mécanisme dans le code, puis appliquez la Pratique.
• Moderniser du code : exécutez go fix ./... jusqu’à ce que le diff soit vide pour appliquer les moderniseurs, puis révisez le diff. Les moderniseurs sautent les formes de code dont ils ne peuvent pas prouver la sécurité, vérifiez donc les Signaux des fichiers routés pour les idiomes obsolètes restants et réécrivez-les à la main. Terminé lorsqu’aucune puce Signaux des fichiers routés ne correspond et que go vet ./... et les tests passent.

Avant de revendiquer un gain de performance, mesurez-le avec un benchmark ou un profil.