Melhores Práticas para Recursos Avançados de Linguagem

Alcance recursos poderosos apenas com necessidade operacional clara.

Estas regras destilam a seção de recursos avançados da linguagem: use Go portátil por padrão, documente comandos de release e trate plugins, assembly e linkname como exceções.

Como Usar Esta Lista

• Aplique ao projetar pipelines de release ou revisar um PR que toque em go:embed, tags de compilação ou -buildmode.
• Use o Nível A antes de mesclar qualquer alteração de recurso poderoso.
• Promova para o Nível B ao enviar plugins, c-shared ou assembly para produção.
• Emparelhe com Além da Especificação: Embed, Modos de Compilação e Assembly para contexto conceitual.
• Revise após atualizações menores do Go; plugins e diretivas quebram com mais frequência entre versões.

A - Use Go Portátil por Padrão

• Comece com Go comum e injeção de disco/configuração. Alcance embed e modos de compilação apenas quando a operação ou portabilidade exigir.
• Faça profiling antes de usar assembly ou noinline. Prove o custo de CPU com pprof ou benchmarks, não com intuição.
• Prefira flags de runtime em vez de tags de compilação para alternância de produtos. Tags são para matrizes de plataforma e toolchain, não para alternância diária de recursos.
• Mantenha branches de plataforma em arquivos com tags, não verificações runtime.GOOS espalhadas com imports estrangeiros. Um arquivo por plataforma escala de forma mais limpa na revisão.
• Documente por que um recurso poderoso é necessário no PR e no runbook. Mantenedores futuros devem ver o gatilho operacional.

B - Embed e Assets

• Incorpore apenas assets que devem ser enviados dentro do binário. Arquivos grandes ou voláteis pertencem a CDN, armazenamento de objetos ou ConfigMaps.
• Nunca incorpore segredos da máquina de compilação. Incorpore apenas padrões; injete credenciais em runtime.
• Use embed.FS com fs.Sub para rotas estáticas HTTP. Remova prefixos para que os caminhos de URL permaneçam intuitivos.
• Versionar migrações incorporadas com a tag do binário. Schema e código são implantados juntos; registre essa ligação nas notas de release.
• Meça a delta do tamanho do binário em CI quando as pastas de embed crescerem. Falhe na revisão quando os artefatos excederem os limites orçamentários.

C - Restrições de Compilação e Comandos de Release

• Use //go:build em novos arquivos; migre // +build legado ao tocar. Mantenha as restrições legíveis com parênteses.
• CI compila cruzado pelo menos um GOOS não-linux quando você envia multiplataforma. Windows ou darwin capturam fallbacks ausentes precocemente.
• Fixe -ldflags, -tags e -buildmode no Makefile ou nos logs de CI. Artefatos reproduzíveis exigem comandos exatos para copiar e colar.
• Carimbe a versão com -X main.version=... usando o caminho de importação correto. Verifique com go list -f '{{.ImportPath}}' ./cmd/....
• Mantenha alvos de compilação com stripping (-s -w) e de depuração separados. Operadores precisam de símbolos durante incidentes.

D - Plugins, c-shared e ABIs Estrangeiras

• Trate plugins como código confiável no espaço de endereço do host. Sem API de descarregamento; plugins ruins exigem reinicialização do processo.
• Recompile o host e os plugins na mesma versão de patch do Go. Registre pares em um manifesto de release.
• Compartilhe versões de go.mod/go.sum entre os módulos do host e do plugin. Desvios de dependência causam crashes sutis em Lookup.
• Prefira RPC ou WASM para extensões não confiáveis. Reserve plugin para catálogos controlados on-premise.
• Documente o suporte à plataforma: sem plugins para Windows. Planeje mecanismos de extensão alternativos para clientes Windows.

E - Assembly e Diretivas do Compilador

• Forneça fallback puramente Go para cada implementação .s. Arquivos //go:build !amd64 (ou arquitetura relevante) são obrigatórios.
• Proíba //go:linkname em pacotes de aplicação. Restrinja a forks de padrões de runtime/stdlib com proprietários de upgrade.
• Restrinja //go:noinline a testes e benchmarks, a menos que um contrato de runtime exija. Não pessimise caminhos de produção quentes.
• Execute arquiteturas direcionadas em CI quando houver arquivos .s. Testes apenas amd64 perdem sintaxe arm64 quebrada.
• Execute go fix após upgrades de toolchain e revise os diffs. Modernizadores capturam migrações inline e de API precocemente.

FAQs

Relacionados

• Além da Especificação: Embed, Modos de Compilação e Assembly - âncora da seção
• //go:embed para Arquivos e Templates - padrões de incorporação de assets
• Pacotes de Plugins e Carregamento Dinâmico - ressalvas operacionais de plugins
• Diretivas do Compilador: //go:noinline, linkname & go:fix inline - perigos das diretivas
• Melhores Práticas de Pacotes e Módulos - higiene de módulos para hosts de plugins

Versões da Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, modernizadores go fix - verifique o patch na compilação), chi (última versão - verifique na compilação), gin (última versão - verifique na compilação), echo (última versão - verifique na compilação), google.golang.org/grpc (última versão - verifique na compilação), sigs.k8s.io/controller-runtime (última versão - verifique na compilação), kubebuilder (última versão - verifique na compilação), tinygo (última versão - verifique os alvos de placa na compilação), wazero (última versão - verifique na compilação) e golangci-lint (última versão - verifique o conjunto de linters na compilação).