albertsko/go-skill

1. Escopo

Estas práticas assumem a semântica da linguagem Go 1.27, os padrões de tempo de execução e a configuração de experimentos padrão.

2. Rota para arquivos de conceito

Rotear pelo código e tarefa em escopo, focando no código alterado para uma mudança ou diff. O índice combina tópicos e padrões de código ilustrativos. X, T, x e v representam qualquer nome. Abra cada referência correspondente, incluindo as rotas adicionais abaixo.

Encontre uma prática pelo prefixo do ID em seu título e cite seu ID completo. Siga a Prática, use o Exemplo como o idioma, e consulte Por que, Exceções e Trade-off para mecanismos, aplicabilidade e custos. Sinais identificam práticas potencialmente ausentes.

Abra também estas referências para salvaguardas ou sintomas ausentes:

• Incompatibilidades de versão de linguagem de módulo ou arquivo, restrições de compilação ou substituições de comportamento de tempo de execução: MOD.
• Código que verifica ou descarta um error: ERH.
• Gorrotinas ou canais: CTX, GOR e SHR.
• E/S bloqueante (rede, banco de dados, HTTP, arquivos) ou um manipulador HTTP: CTX.
• Testes de código concorrente: TBA e TST.
• Memória ou contagem de gorrotinas que cresce: PRO e MRT.
• Alta CPU de GC, ou um programa em um contêiner: BRT, PRO e TRC.
• Um caminho quente, ou uma solicitação para tornar o código mais rápido: PRO, ALO e BEN.

2.1 Linguagem

• CST code-structure.md: sombreamento, nomes de pacotes/built-in (url, len, new, max), retornos antecipados (else após return), func init().
• STD struct-design.md: getters/setters (GetX/SetX), incorporação (sync.Mutex), literais de campo promovido, opções funcionais (NewXWithY, argumentos Config), new(expr) e auxiliares de ponteiro (ptr[T], intPtr).
• INT interfaces.md: criação/propriedade de interfaces, interfaces de implementação única, resultados concretos vs interface, any/interface{}, interfaces/erros nil tipados.
• GEN generics.md: parâmetros de tipo ([T any]), restrições (comparable, ~int, ~string, cmp.Ordered, golang.org/x/exp/constraints), inferência, métodos genéricos, restrições autorreferenciadas.
• FNM functions-and-methods.md: receptores valor/ponteiro ou mistos, receptores de valor que contêm mutex, resultados nomeados (n int, err error), retornos nus.
• LOP loops.md: cópias de range (v.field =), avaliação de expressão, variáveis por iteração (v := v, &v, closures de gorrotina), range n, for i := 0; i <, slices.Backward, breaks rotulados, break dentro de switch/select.
• ITR iterators.md: consumo/criação de iteradores, iter.Seq/iter.Seq2 (incluindo parâmetros), yield, iter.Pull, Next()/Value(), métodos que retornam todos os elementos como slices, slices.Collect.
• DEF defer-and-cleanup.md: defer em loops, avaliação adiada de argumento/receptor, limpeza de io.Closer (defer f.Close(), resp.Body, rows.Close()), erros de Close/Sync, os.Create.

2.2 Dados

• NUM numbers.md: octal (0644), estouro de inteiro (int32(, math.MaxInt), float ==, NaN/Inf, math.FMA.
• SLC slices.md: comprimento/capacidade, aliasing de append, pré-alocação (make([]), nil/vazio ([]T{}, s == nil), verificações len, copy/slices.Clone, [low:high:max], conversão slice-para-array.
• COL collection-helpers.md: min/max, slices inserir/deletar/ordenar/buscar, maps, cmp, clear. Formas antigas: sort.Slice, math.Min/math.Max, append(s[:i], s[i+1:]...), loops de delete para limpeza de mapas.
• MAP maps.md: dimensionamento de mapas (make(map, map[K]V{}), chaves ordenadas (maps.Keys, sort.Strings), escritas durante iteração de mapa.
• MRT memory-retention.md: caches/mapas de longa duração (mapa ao lado de mutex, deleção, tamanho pós-pico), substrings/subslices retidos, zeramento de ponteiros descartados, strings.Clone/bytes.Clone, runtime.AddCleanup/runtime.SetFinalizer, unique.*, weak.*.
• CMP comparison.md: tipos comparáveis (== em interfaces/structs, [T comparable]), slices.Equal/maps.Equal, reflect.DeepEqual, valores de função (runtime.FuncForPC).
• STX strings-text.md: bytes/runas (len(s) como contagem de caracteres, []rune), validação UTF-8 (utf8), string(int), range de string, tabelas unicode.
• SPR strings-processing.md: Trim*/Cut*, SplitSeq/FieldsSeq/Lines, strings.Split/strings.Index, strings.Builder, loops de string +=, bytes/bytes.Buffer, fmt.Append*/strconv.Append*, []byte(fmt.Sprintf(.

2.3 Erros

• PAN panics.md: panic vs error, recover, Must, panic(nil)/panicnil, debug.SetCrashOutput.
• ERC errors-creating.md: encapsulamento (%w/%v, fmt.Errorf, return err/return nil, err sem contexto), errors.New, sentinelas (var Err) vs tipos de erro (Error() string), errors.Join, ErrUnsupported.
• ERH errors-handling.md: errors.Is/errors.AsType, err ==, err.(type), errors.As, comparações de mensagem, sentinelas de timeout/cancelamento (net.Error, os.ErrDeadlineExceeded, context.DeadlineExceeded), verificação de err antes de resultados, erros ignorados (_ =, x, _ :=).
• LOG logging.md: configuração e registro de erros com log/slog, log.Printf/log.Println, registrar e retornar o mesmo erro.

2.4 Concorrência

• CND concurrency-design.md: concorrência vs paralelismo, limites de inicialização (gorrotina por elemento), dimensionamento de pool de workers, runtime.NumCPU(), GOMAXPROCS.
• SHR shared-state.md: condições de corrida de dados, happens-before, condições de corrida, mutex vs canal, escritas de gorrotina, sync.Mutex/RLock, formatação sob locks (fmt.Sprintf), append/mapas compartilhados.
• SYN sync-primitives.md: atômicos tipados (sync/atomic, atomic.Pointer, atomic.AddInt64/atomic.Value, n++ em gorrotina), sync.Map, sync.Once/sync.OnceValue, sync.Cond, valores sync copiados.
• GOR goroutine-lifecycle.md: vazamentos de gorrotina, plano/proprietário de parada, remetentes bloqueados após retorno antecipado, canais de resultado sem buffer, go func(), sync.WaitGroup, wg.Add/wg.Go, errgroup (g.Go, SetLimit).
• CHA channels.md: canais de notificação e dimensionamento (make(chan, chan bool, chan struct{}), prioridade select, canais nil, close.
• CTX context.md: passagem de context.Context, defer cancel()/context.WithTimeout, ctx.Done() em torno de operações bloqueantes, chaves de valor (context.WithValue, ctx.Value), context.Background() fora de main.
• CXC context-cancellation.md: causas de cancelamento (ctx.Err(), <-ctx.Done(), context.Canceled/context.DeadlineExceeded/context.Cause, WithCancelCause), context.AfterFunc, trabalho em background (WithoutCancel, r.Context() em gorrotina), signal.Notify/signal.NotifyContext.

2.5 Biblioteca padrão

• TIM time.md: unidades de time.Duration/números nus, comparação de time.Time (==), timers em loops (time.After), time.NewTimer, time.Tick.
• JSN json.md: encoding/json, encoding/json/v2, tags JSON (omitzero, omitempty), marshalers incorporados, decodificação de números (json.Unmarshal em map[string]any).
• SQL database-sql.md: database/sql, sql.Open, PingContext, tamanho do pool, argumentos de consulta/declarações preparadas (db.Query, .Exec, QueryRow, ExecContext, SQL via fmt.Sprintf), sql.Null[T], rows.Next/rows.Err.
• IOF io-and-files.md: io.Reader/io.Writer e parâmetros fs.FS, filename string, os.Open, os.ReadFile, os.DirFS, os.Root, filepath.Join com entrada do usuário.
• HCL http-client-and-net.md: timeouts/compartilhamento/pools do 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: manipuladores (http.ResponseWriter, *http.Request, http.Handler, r.Body/r.Method), padrões ServeMux/HandleFunc, http.Error, timeouts do 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 Testes

• TBA testing-basics.md: categorias de teste/tags de compilação (func TestX, //go:build integration), -race, t.Parallel, -shuffle, testes orientados a tabela/t.Run, helpers, pacotes externos _test.
• TST testing-state.md: t.Cleanup, TestMain, t.Context vs context.Background() em teste, t.Chdir/t.Setenv/t.TempDir vs os.Chdir/os.Setenv/os.MkdirTemp, testing/synctest, tempo de teste/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/reuso, benchstat.
• COV coverage-and-test-output.md: -coverpkg, -cover, go build -cover/GOCOVERDIR, t.Output/t.Attr/t.ArtifactDir, fmt.Println em teste, go test -json.

2.7 Desempenho

Aplique as práticas de layout, alocação e inlining apenas a um caminho quente identificado por um benchmark, perfil ou trace.

• PRO profiling.md: pprof (net/http/pprof, /debug/pprof, runtime/pprof, pprof.Lookup), diffs de heap, dumps de gorrotina, perfis de goroutineleak/block/mutex (SetBlockProfileRate, SetMutexProfileFraction), rótulos (pprof.Do), contagens de gorrotina (runtime/metrics).
• TRC tracing.md: trace de execução (runtime/trace, trace.Start), gravador de voo (FlightRecorder), picos de latência/solicitações lentas raras, pausas de escalonamento/GC.
• MLY memory-layout.md: localidade de cache/strides (loops quentes []*T), falso compartilhamento (contadores por gorrotina em um único slice), paralelismo em nível de instrução, alinhamento de campo, structs.HostLayout.
• ALO allocations.md: análise de escape (-gcflags, retorno de ponteiros locais), buffers de propriedade do chamador, conversões eliminadas pelo compilador (string(b) em caminho quente), allocs/op, sync.Pool.
• BRT build-and-runtime-tuning.md: inlining, PGO (default.pgo), GOGC/GOMEMLIMIT/debug.SetGCPercent, GOMAXPROCS ciente de contêiner (automaxprocs, runtime.GOMAXPROCS).
• CGO cgo.md: agrupamento de chamadas cgo (import "C", C.), diretivas #cgo (noescape, nocallback).

2.8 Projeto e ferramentas

• PKG packages-and-docs.md: layout de projeto, coesão/nomes de pacotes (util, common), aliases (type X = Y, //go:fix inline), comentários de documentação, comentários de documentação exportados ausentes, Deprecated:, exemplos (func ExampleX).
• TOL tooling.md: gofmt, go vet, linters (golangci-lint), diretivas tool/tools.go, modernizadores go fix, verificações de vet em teste (-vet=), scripts de CI, @latest.
• MOD modules-and-builds.md: higiene de go.mod/replace, godebug///go:debug, workspaces (go.work), restrições de compilação (//go:build, // +build).

3. Aplicar à tarefa

• Escrevendo código: atenda a todas as práticas aplicáveis nos arquivos roteados.
• Revisando código: quando comandos estiverem disponíveis, primeiro execute go vet ./..., go test -race ./... e go fix -diff ./..., usando uma cópia se o código precisar permanecer intocado. Verifique cada marcador de Sinais em cada arquivo roteado. Exclua ocorrências cobertas por Exceções. Relate o restante como ID | arquivo:linha | o que está errado | correção. Para práticas sobrepostas, cite o ID mais específico primeiro, depois os outros. Use - para problemas que nenhuma prática cobre. Ordene por impacto: resultados errados, condições de corrida, pânicos, vazamentos, travamentos, depois problemas de recurso/desempenho, depois expressões idiomáticas/estilo desatualizados.
• Depurando: corresponda sintomas a Sinais e Por que, confirme o mecanismo no código, depois aplique a Prática.
• Modernizando código: execute go fix ./... até que o diff esteja vazio para aplicar os modernizadores, depois revise o diff. Os modernizadores pulam formas de código que não podem provar seguras, então verifique os Sinais dos arquivos roteados para as expressões idiomáticas desatualizadas restantes e reescreva-as manualmente. Concluído quando nenhum marcador de Sinais dos arquivos roteados corresponder e go vet ./... e os testes passarem.

Antes de reivindicar um ganho de desempenho, meça-o com um benchmark ou um perfil.