Práticas Recomendadas de CGO e Interoperabilidade

Isole o cgo por trás de pequenos pacotes e teste em todos os alvos.

Estas regras mantêm a interop nativa distribuível: propriedade clara, builds reproduzíveis e 'escape hatches' quando CGO_ENABLED=0 é necessário.

Como Usar Esta Lista

• Aplique na revisão de design antes de adicionar import "C" a pacotes de aplicação.
• Marque itens durante a revisão de PR para qualquer diff que toque em unsafe, #cgo ou arquivos .so de fornecedores.
• Execute CI tanto com CGO_ENABLED=1 quanto com CGO_ENABLED=0 quando o módulo reivindicar builds portáteis.
• Vincule violações a linters (staticcheck, govulncheck) e exceções documentadas em ADRs.

A - Limites de Pacote e APIs

• Confinar import "C" a um pacote interno por dependência nativa. O código da aplicação depende apenas de tipos e erros Go.
• Expor funções Go estreitas, não tipos C.*, nos limites do módulo. Os chamadores não devem precisar de conhecimento de cgo para compilar.
• Fornecer fallbacks //go:build !cgo ou erros claros quando o cgo for obrigatório. CI e cross-compiles devem falhar ruidosamente, não se comportar mal silenciosamente.
• Fixar versões de SDKs de fornecedores em SBOM e README. Registrar nomes de .so, licenças e matriz de SO/arquitetura suportados.
• Evitar funções init que chamam C. A inicialização preguiçosa no primeiro uso simplifica testes e ordem de inicialização.

B - Memória, ponteiros e callbacks

• Emparelhar cada C.CString/C.CBytes com C.free em todos os caminhos. Usar defer imediatamente após a alocação ter sucesso.
• Documentar a propriedade de ponteiros retornados de C. Copiar para Go com C.GoString/C.GoBytes, a menos que C retenha a propriedade por contrato.
• Nunca permitir que C armazene ponteiros Go após uma chamada sem fixação e alcançabilidade. Copiar para o heap C quando o tempo de vida se estende assincronamente.
• Proteger callbacks //export com mutexes ou canais. Assumir que C chama de threads de SO arbitrárias.
• Usar runtime.LockOSThread apenas em torno da configuração de thread local C, não em manipuladores inteiros. Desbloquear prontamente para preservar a taxa de transferência do scheduler.

C - Desempenho e confiabilidade

• Agrupar trabalho para reduzir cruzamentos cgo em loops 'hot'. Perfil de runtime.cgocall antes de micro-otimizar o código Go.
• Limitar a entrada cgo concorrente com semáforos dimensionados para CPUs ou documentação da biblioteca. Prevenir crescimento ilimitado de threads de SO.
• Manter seções C curtas; tratar C longas como I/O bloqueante. Tempo limite em limites Go com contextos, sempre que possível.
• Executar código C sob ASan/Valgrind em harnesses de teste nativos. Testes Go sozinhos perdem overflows de buffer C.
• Recuperar panics dentro de funções //export. Panics não capturados através da fronteira FFI abortam o processo.

D - Build, CI e release

• Documentar pacotes CGO_CFLAGS, CGO_LDFLAGS e pkg-config para imagens de CI. Builds reproduzíveis superam caminhos exclusivos de laptop.
• Testar builds linux/arm64 e darwin ao distribuir cgo. Cross-compilar cgo requer bibliotecas e compiladores de destino.
• Distribuir imagens de contêiner com camadas de libc/SDK necessárias documentadas. Imagens 'scratch' precisam de variantes puras Go ou planos musl estáticos.
• Bloquear merges em go test ./... com cgo ligado e desligado quando aplicável. Capturar tags de build ausentes precocemente.
• Preferir drivers puros Go em bibliotecas consumidas por outros. Módulos downstream herdam seus requisitos de toolchain cgo.

E - Estratégia e alternativas

• Experimentar golang.org/x/sys e portas puras antes de novo cgo. Experiência do consumidor mais simples e menor superfície de ataque.
• Escolher RPC quando o isolamento de falhas ou release independente superar a latência de microssegundos. Registrar a decisão em um ADR.
• Planejar caminhos wasm sem cgo para alvos de navegador/WASI. Marcar arquivos import "C" com !wasm.
• Revisar escolhas de interop anualmente à medida que o stdlib e as portas da comunidade amadurecem. O cgo de ontem pode ser o Go puro de hoje.
• Medir a latência de ponta a ponta antes de se comprometer com cgo in-process. O estilo de integração importa mais do que os nanossegundos de cruzamento.

FAQs

Relacionado

• CGO: Cruzando a Fronteira Go-C - Modelo mental e trade-offs
• Segurança FFI: Ponteiros, C.CString & Free - Regras de propriedade
• Interações de Desempenho CGO e Scheduler - Limites de thread e latência
• Guia de Decisão de Interop: CGO vs RPC vs Rewrite - Estratégia antes da implementação
• Noções Básicas de CGO - Exemplos iniciais executáveis

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