Boas Práticas para WebAssembly & TinyGo

Testando compilações WASM em CI e evitando syscall/js em módulos de servidor.

Estas regras mantêm os artefatos WASM portáteis, amigáveis ao sandbox e com tamanho apropriado, desde o primeiro protótipo até os hosts de produção.

Como Usar Esta Lista

• Aplique durante a revisão de design quando um recurso mencionar WASM, TinyGo, wazero ou deploy de edge.
• Adicione etapas de compilação GOOS=wasip1 GOARCH=wasm e testes rápidos wasmtime run à CI para pacotes guest.
• Emparelhe com o Guia de Decisão: Go Nativo vs TinyGo vs Rust WASM quando a escolha da toolchain não estiver definida.
• Revise após atualizações menores do Go; o comportamento do runtime WASM evolui (o chunking de heap do Go 1.26 é um exemplo recente).

A - Higiene de Target e Compilação

• Defina módulos de servidor para wasip1/wasm por padrão. Reserve js/wasm apenas para requisitos de DOM do navegador.
• Nunca importe syscall/js em pacotes WASI. Aplique com tags de compilação js && wasm em arquivos do navegador.
• Remova artefatos de release WASM com -ldflags="-s -w". Mantenha artefatos não removidos no armazenamento da CI para triagem de crash.
• Fixe as versões da toolchain em imagens de CI. Registre Go 1.26.x, TinyGo, wasmtime e wazero juntas no log de compilação.
• Audite go list -deps para mains de guest. Rejeite imports acidentais de net/http/pprof ou apenas para testes em entrypoints de plugin.

B - CI e Testes

• Compile WASM em todo PR que toque em código guest. GOOS=wasip1 GOARCH=wasm go build ./... captura regressões de importação precocemente.
• Execute testes rápidos de guests com wasmtime. Códigos de saída diferentes de zero devem falhar o pipeline como binários nativos.
• Espelhe testes de embed do wazero se os hosts de produção forem em Go. O sucesso no CLI não garante que a configuração de embed esteja correta.
• Adicione jobs de compilação TinyGo quando TinyGo for para produção. tinygo build -target=wasm pode falhar enquanto as compilações gc passam.
• Registre os tamanhos dos artefatos na CI. Monitore bytes de gc vs TinyGo para detectar o aumento de dependências ao longo do tempo.

C - Runtime do Host e Sandboxing

• Pré-abra diretórios com privilégio mínimo. Mapeie apenas os caminhos de host necessários para os namespaces guest (--dir / FSConfig do wazero).
• Passe o ambiente explicitamente. Não confie na paridade implícita do ambiente do host entre laptops de desenvolvimento e produção.
• Limite a execução do guest com deadlines de contexto no wazero. Evite CPU descontrolada em embedders multi-tenant.
• Cacheie módulos compilados em hosts de longa duração. Reinstanciar compilações frias domina a latência.
• Escolha wazero para embedders puramente Go; wasmtime para paridade CLI/dev. Documente o motivo se escolher de outra forma.

D - Tamanho e Seleção de Toolchain

• Meça o tamanho antes de escolher gc vs TinyGo. Compare ls -lh na mesma fatia de funcionalidade, não apenas em hello-world.
• Reavalie gc WASM em Go 1.26+ quando a memória era o bloqueador. Chunks de heap menores ajudam pools wazero densos.
• Use TinyGo para MCUs e limites de edge sub-megabyte. Verifique as limitações de stdlib e reflection com um protótipo de compilação primeiro.
• Evite frameworks JSON/reflection pesados em guests TinyGo. Prefira structs pequenas e marshaling ajustado manualmente.
• Documente a toolchain por plugin nos metadados do registro de plugins. Operadores devem saber qual compilador construiu cada .wasm.

E - Navegador e syscall/js

• Versione wasm_exec.js com sua toolchain Go. Incompatibilidade causa falhas de importação obscuras em navegadores.
• Chame js.Func.Release() ao remover listeners. Evite vazamentos em páginas SPA de longa duração.
• Bloqueie main com select {} em guests de navegador. Sair de main desativa o runtime antes que os callbacks sejam acionados.
• Sirva .wasm como application/wasm. Corrija os mapas MIME do servidor estático para instantiateStreaming.
• Mantenha a área de superfície do DOM pequena. Prefira TS/React para layout; WASM para computação quando possível.

F - Operações e Segurança

• Trate WASM como artefatos versionados imutáveis. Publique hashes; atualize trocando os bytes do módulo deliberadamente.
• Não monte a raiz do host em guests. Um plugin comprometido não deve ler todo o sistema de arquivos.
• Alinhe as concessões de capacidade WASI entre dev e prod. Desvios aqui são um modo de falha comum de "funciona localmente".
• Atualize Go para correções de segurança em guests de criptografia. Fixe em 1.26.x e reconstrua WASM em releases de segurança.
• Execute go fix modernizadores em pacotes compartilhados. O go fix do Go 1.26 mantém o código idiomático antes de compilar cruzado para WASM.

FAQs

Relacionados

• Compilando com GOOS=wasip1 GOARCH=wasm - comandos de compilação
• Runtimes de Host WASI: wasmtime, wazero & Spin - configuração do host
• syscall/js: Go no Navegador - interop apenas para navegador
• Melhorias no Runtime WASM e Memória do Go 1.26 - gatilhos de atualização
• Noções Básicas de WebAssembly & TinyGo - pontos de partida práticos

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 targets 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).