albertsko/go-skill

1. Alcance

Estas prácticas asumen la semántica del lenguaje Go 1.27, los valores predeterminados del entorno de ejecución y la configuración experimental predeterminada.

2. Ruta a los archivos de concepto

Enruta según el código y la tarea en cuestión, centrándote en el código modificado para un cambio o diff. El índice combina temas y patrones de código ilustrativos. X, T, x y v representan cualquier nombre. Abre cada referencia que coincida, incluidas las rutas adicionales a continuación.

Encuentra una práctica por el prefijo de ID en su encabezado y cita su ID completo. Sigue la Práctica, usa Ejemplo como el modismo, y consulta Por qué, Excepciones y Compensaciones para conocer los mecanismos, la aplicabilidad y los costos. Las Señales identifican prácticas que podrían faltar.

También abre estas referencias para salvaguardas o síntomas faltantes:

• Desajustes de versión de idioma del módulo o archivo, restricciones de compilación o anulaciones de comportamiento en tiempo de ejecución: MOD.
• Código que verifica o descarta un error: ERH.
• Gorutinas o canales: CTX, GOR y SHR.
• E/S bloqueante (red, base de datos, HTTP, archivos) o un manejador HTTP: CTX.
• Pruebas de código concurrente: TBA y TST.
• Memoria o cantidad de gorutinas que crece: PRO y MRT.
• Alto uso de CPU de GC, o un programa en un contenedor: BRT, PRO y TRC.
• Un camino crítico, o una solicitud para hacer el código más rápido: PRO, ALO y BEN.

2.1 Lenguaje

• CST code-structure.md: sombreado, nombres de paquetes/incorporados (url, len, new, max), retornos tempranos (else después de return), func init().
• STD struct-design.md: getters/setters (GetX/SetX), embebido (sync.Mutex), literales de campos promovidos, opciones funcionales (NewXWithY, argumentos Config), new(expr) y ayudantes de puntero (ptr[T], intPtr).
• INT interfaces.md: creación/propiedad de interfaces, interfaces de implementación única, resultados concretos vs de interfaz, any/interface{}, interfaces/errores nulos tipados.
• GEN generics.md: parámetros de tipo ([T any]), restricciones (comparable, ~int, ~string, cmp.Ordered, golang.org/x/exp/constraints), inferencia, métodos genéricos, restricciones auto-referenciales.
• FNM functions-and-methods.md: receptores de valor/puntero o mixtos, receptores de valor con mutex, resultados nombrados (n int, err error), retornos desnudos.
• LOP loops.md: copias de rango (v.field =), evaluación de expresiones, variables por iteración (v := v, &v, closures de gorutina), range n, for i := 0; i <, slices.Backward, breaks etiquetados, break dentro de switch/select.
• ITR iterators.md: consumo/creación de iteradores, iter.Seq/iter.Seq2 (incluidos parámetros), yield, iter.Pull, Next()/Value(), métodos que devuelven todos los elementos como slices, slices.Collect.
• DEF defer-and-cleanup.md: defer en bucles, evaluación diferida de argumentos/receptores, limpieza de io.Closer (defer f.Close(), resp.Body, rows.Close()), errores de Close/Sync, os.Create.

2.2 Datos

• NUM numbers.md: octal (0644), desbordamiento de enteros (int32(, math.MaxInt), float ==, NaN/Inf, math.FMA.
• SLC slices.md: longitud/capacidad, aliasing de append, preasignación (make([]), nil/vacío ([]T{}, s == nil), comprobaciones de len, copy/slices.Clone, [low:high:max], conversión de slice a array.
• COL collection-helpers.md: min/max, slices insert/delete/sort/search, maps, cmp, clear. Formas antiguas: sort.Slice, math.Min/math.Max, append(s[:i], s[i+1:]...), bucles de delete para limpiar mapas.
• MAP maps.md: dimensionamiento de mapas (make(map, map[K]V{}), claves ordenadas (maps.Keys, sort.Strings), escrituras durante la iteración del mapa.
• MRT memory-retention.md: cachés/mapas de larga duración (mapa junto a mutex, eliminación, tamaño posterior al pico), subcadenas/subslises retenidos, puesta a cero de punteros descartados, strings.Clone/bytes.Clone, runtime.AddCleanup/runtime.SetFinalizer, unique.*, weak.*.
• CMP comparison.md: tipos comparables (== en interfaces/structs, [T comparable]), slices.Equal/maps.Equal, reflect.DeepEqual, valores de función (runtime.FuncForPC).
• STX strings-text.md: bytes/runas (len(s) como recuento de caracteres, []rune), validación UTF-8 (utf8), string(int), rango de cadenas, tablas unicode.
• SPR strings-processing.md: Trim*/Cut*, SplitSeq/FieldsSeq/Lines, strings.Split/strings.Index, strings.Builder, bucles de string +=, bytes/bytes.Buffer, fmt.Append*/strconv.Append*, []byte(fmt.Sprintf(.

2.3 Errores

• PAN panics.md: panic vs error, recover, Must, panic(nil)/panicnil, debug.SetCrashOutput.
• ERC errors-creating.md: envoltura (%w/%v, fmt.Errorf, return err/return nil, err sin contexto), errors.New, centinelas (var Err) vs tipos de error (Error() string), errors.Join, ErrUnsupported.
• ERH errors-handling.md: errors.Is/errors.AsType, err ==, err.(type), errors.As, comparaciones de mensajes, centinelas de tiempo de espera/cancelación (net.Error, os.ErrDeadlineExceeded, context.DeadlineExceeded), verificar err antes de los resultados, errores ignorados (_ =, x, _ :=).
• LOG logging.md: configuración y registro de errores de log/slog, log.Printf/log.Println, registrar y devolver el mismo error.

2.4 Concurrencia

• CND concurrency-design.md: concurrencia vs paralelismo, umbrales de creación (gorutina por elemento), dimensionamiento de grupos de workers, runtime.NumCPU(), GOMAXPROCS.
• SHR shared-state.md: carreras de datos, sucede-antes, condiciones de carrera, mutex vs canal, escrituras de gorutina, sync.Mutex/RLock, formateo bajo bloqueos (fmt.Sprintf), append/mapas compartidos.
• SYN sync-primitives.md: atómicos tipados (sync/atomic, atomic.Pointer, atomic.AddInt64/atomic.Value, gorutina n++), sync.Map, sync.Once/sync.OnceValue, sync.Cond, valores sync copiados.
• GOR goroutine-lifecycle.md: fugas de gorutinas, plan de parada/propietario, remitentes bloqueados después de un retorno temprano, canales de resultados sin búfer, go func(), sync.WaitGroup, wg.Add/wg.Go, errgroup (g.Go, SetLimit).
• CHA channels.md: canales de notificación y dimensionamiento (make(chan, chan bool, chan struct{}), prioridad en select, canales nil, close.
• CTX context.md: pasar context.Context, defer cancel()/context.WithTimeout, ctx.Done() alrededor de operaciones bloqueantes, claves de valor (context.WithValue, ctx.Value), context.Background() fuera de main.
• CXC context-cancellation.md: causas de cancelación (ctx.Err(), <-ctx.Done(), context.Canceled/context.DeadlineExceeded/context.Cause, WithCancelCause), context.AfterFunc, trabajo en segundo plano (WithoutCancel, gorutina r.Context()), signal.Notify/signal.NotifyContext.

2.5 Biblioteca estándar

• TIM time.md: unidades de time.Duration/números simples, comparación de time.Time (==), temporizadores en bucles (time.After), time.NewTimer, time.Tick.
• JSN json.md: encoding/json, encoding/json/v2, etiquetas JSON (omitzero, omitempty), marshalers embebidos, decodificación de números (json.Unmarshal en map[string]any).
• SQL database-sql.md: database/sql, sql.Open, PingContext, tamaño del pool, argumentos de consulta/sentencias preparadas (db.Query, .Exec, QueryRow, ExecContext, SQL vía fmt.Sprintf), sql.Null[T], rows.Next/rows.Err.
• IOF io-and-files.md: parámetros io.Reader/io.Writer y fs.FS, filename string, os.Open, os.ReadFile, os.DirFS, os.Root, filepath.Join con entrada de usuario.
• HCL http-client-and-net.md: tiempos de espera/compartición/pools del cliente (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: manejadores (http.ResponseWriter, *http.Request, http.Handler, r.Body/r.Method), patrones de ServeMux/HandleFunc, http.Error, tiempos de espera del servidor (http.ListenAndServe, http.Server), MaxBytesHandler, ResponseController, CrossOriginProtection.
• RND randomness-and-ids.md: uuid, crypto/rand, math/rand, math/rand/v2, rand.Seed.

2.6 Pruebas

• TBA testing-basics.md: categorías de prueba/etiquetas de compilación (func TestX, //go:build integration), -race, t.Parallel, -shuffle, pruebas basadas en tablas/t.Run, ayudantes, paquetes _test externos.
• TST testing-state.md: t.Cleanup, TestMain, t.Context vs context.Background() de prueba, t.Chdir/t.Setenv/t.TempDir vs os.Chdir/os.Setenv/os.MkdirTemp, testing/synctest, tiempo de prueba/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, entrada representativa/reutilización, benchstat.
• COV coverage-and-test-output.md: -coverpkg, -cover, go build -cover/GOCOVERDIR, t.Output/t.Attr/t.ArtifactDir, prueba fmt.Println, go test -json.

2.7 Rendimiento

Aplica las prácticas de diseño, asignación e inlining solo a un camino crítico que haya sido identificado por un benchmark, perfil o traza.

• PRO profiling.md: pprof (net/http/pprof, /debug/pprof, runtime/pprof, pprof.Lookup), diferencias de heap, volcados de gorutinas, perfiles de goroutineleak/bloqueo/mutex (SetBlockProfileRate, SetMutexProfileFraction), etiquetas (pprof.Do), conteos de gorutinas (runtime/metrics).
• TRC tracing.md: trazas de ejecución (runtime/trace, trace.Start), grabador de vuelo (FlightRecorder), picos de latencia/solicitudes lentas raras, pausas de planificación/GC.
• MLY memory-layout.md: localidad de caché/strides (bucles []*T críticos), falso compartimiento (contadores por gorutina en un solo slice), paralelismo a nivel de instrucciones, alineación de campos, structs.HostLayout.
• ALO allocations.md: análisis de escape (-gcflags, devolución de punteros locales), búferes propiedad del llamante, conversiones elididas por el compilador (string(b) crítica), allocs/op, sync.Pool.
• BRT build-and-runtime-tuning.md: inlining, PGO (default.pgo), GOGC/GOMEMLIMIT/debug.SetGCPercent, GOMAXPROCS consciente del contenedor (automaxprocs, runtime.GOMAXPROCS).
• CGO cgo.md: agrupar llamadas cgo (import "C", C.), directivas #cgo (noescape, nocallback).

2.8 Proyecto y herramientas

• PKG packages-and-docs.md: diseño del proyecto, cohesión/nombres de paquetes (util, common), alias (type X = Y, //go:fix inline), comentarios de documentación, comentarios de documentación exportados faltantes, Deprecated:, ejemplos (func ExampleX).
• TOL tooling.md: gofmt, go vet, linters (golangci-lint), directivas tool/tools.go, modernizadores go fix, comprobaciones de pruebas con vet (-vet=), scripts de CI, @latest.
• MOD modules-and-builds.md: higiene de go.mod/replace, godebug///go:debug, espacios de trabajo (go.work), restricciones de compilación (//go:build, // +build).

3. Aplicar a la tarea

• Escribir código: satisface cada práctica aplicable en los archivos enrutados.
• Revisar código: cuando los comandos estén disponibles, primero ejecuta go vet ./..., go test -race ./... y go fix -diff ./..., usando una copia si el código debe permanecer intacto. Revisa cada viñeta de Señales en cada archivo enrutado. Excluye los aciertos cubiertos por Excepciones. Informa el resto como ID | archivo:línea | qué está mal | corrección. Para prácticas superpuestas, cita primero el ID más específico, luego los otros. Usa - para problemas que ninguna práctica cubre. Ordena por impacto: resultados incorrectos, carreras, pánicos, fugas, cuelgues, luego problemas de recursos/rendimiento, luego modismos/estilo obsoletos.
• Depurar: iguala los síntomas con Señales y Por qué, confirma el mecanismo en el código, luego aplica la Práctica.
• Modernizar código: ejecuta go fix ./... hasta que el diff esté vacío para aplicar los modernizadores, luego revisa el diff. Los modernizadores omiten formas de código que no pueden probar que sean seguras, así que verifica las Señales de los archivos enrutados para los modismos obsoletos restantes y reescríbelos manualmente. Termina cuando ninguna viñeta de Señales de los archivos enrutados coincida y go vet ./... y las pruebas pasen.

Antes de afirmar una ganancia de rendimiento, mídela con un benchmark o un perfil.