Boas Práticas para Ferramentas CLI

Testando CLIs, versionamento e distribuição via go install.

Aplique estas regras na revisão de código, pipelines de lançamento e modelos de plataforma interna para que cada binário Go instale de forma previsível, falhe claramente e permaneça testável sem poluição de flags globais.

Como Usar Esta Lista

• Marque as regras à medida que seu modelo de CLI as adota.
• Codifique itens da Camada A no CI (saída de ajuda dourada, testes de código de saída) sempre que possível.
• Publique tabelas de códigos de saída e precedência de configuração no README da ferramenta.
• Revise ao adicionar modos TUI, novos subcomandos ou lançamentos multiplataforma.

A - UX e streams

• Reserve o stdout para saída de contrato legível por máquina. Mantenha textos, cores e progresso no stderr.
• Imprima erros de uso e parsing no stderr. Pipes e wrappers kubectl permanecem limpos.
• Respeite NO_COLOR e desative ANSI quando não for um TTY. Logs de CI e políticas de acessibilidade dependem disso.
• Documente códigos de saída além de 0 e 1. Scripts ramificam em falhas de configuração vs. autenticação quando documentados.
• Falhe rapidamente em erros de configuração e flags antes de I/O. Economize tempo e evite mutações parciais.

B - Estrutura e dependências

• Mantenha main enxuto; coloque a lógica em pacotes internal/. Permite testes unitários sem os.Exit.
• Evite flag.CommandLine global em bibliotecas. Use FlagSet ou cobra por comando.
• Um framework de parsing por binário. Não misture kingpin, cobra e flags stdlib no mesmo argv.
• Compartilhe tipos de domínio com serviços em internal/. CLI e API permanecem alinhados em enums e IDs.
• Adie importações pesadas para subcomandos críticos para CI quando o profiling provar a necessidade. Divida binários apenas com dados.

C - Configuração

• Documente a precedência: flags > env > arquivo > padrões. Operadores devem saber qual valor vence.
• Use prefixo de env e substituidor de chave para chaves viper aninhadas. Mapeia API_URL para api.url de forma previsível.
• Nunca comite segredos em arquivos de configuração de exemplo. Envie config.example.yaml com placeholders.
• Valide configurações necessárias após a fusão. Retorne erros sentinela mapeados para o código de saída 2.
• Redefina ou isole viper em testes. Evite poluição de testes paralelos a partir de configuração global.

D - Árvores de comandos e flags

• Use cobra ou urfave/cli quando subcomandos excederem dois branches manuais. Autocompletar e ajuda pagam o custo da dependência.
• Anexe flags compartilhadas com PersistentFlags apenas na raiz. Evite nomes de flags duplicados em pai e filho.
• Valide a aridade com helpers Args ou enums. Contagens incorretas de argumentos produzem mensagens acionáveis.
• Gere e documente autocompletar de shell para ferramentas de operador. Reduz erros de digitação em caminhos de comando longos.
• Marque comandos depreciados com avisos antes da remoção. Dê aos consumidores um ciclo de lançamento para migrar.

E - Testes e qualidade

• Teste run(args []string) error sem fazer parsing de os.Args real. A lógica principal permanece segura para paralelismo.
• Use cobra.Command.SetArgs ou FlagSet.Parse isolado em testes CLI. Sem vazamento de flags entre testes.
• Adicione testes de integração os/exec para códigos de saída e saída de ajuda. Capture erros de conexão em main.
• Teste golden --help quando a superfície do comando estiver estável. Renomeações de flags não intencionais quebram scripts.
• Execute go test ./... com o detector de corridas para CLIs concorrentes. Workers e TUIs expõem corridas cedo.

F - Build, versão e distribuição

• Marque a versão com -ldflags "-X main.version=…" no CI. O suporte pode mapear relatórios de bugs para builds.
• Exponha o subcomando --version ou version. Corresponde a tags de imagem de contêiner e tags git.
• Publique via go install module/path@version para módulos públicos. Documente o caminho de importação no README.
• Anexe arquivos de lançamento compilados cruzadamente por GOOS/GOARCH. Operadores Linux, macOS e Windows obtêm binários nativos.
• Registre a integridade do go.sum e notas de build reproduzíveis nos lançamentos. A revisão da cadeia de suprimentos depende disso.

G - UI de Terminal e operações longas

• Detecte não-TTY e rebaixe TUI para linhas de log. GitHub Actions e cron não têm suporte a tela alternativa.
• Execute trabalho bloqueante fora da goroutine Update do bubbletea. Envie mensagens de conclusão de volta para o modelo.
• Manipule ctrl+c e sinais para CLIs em lote. Gravações parciais não devem corromper o estado remoto.
• Mostre progresso no stderr para trabalhos de minutos. Operadores precisam de feedback sem quebrar o JSON do stdout.
• Saia de programas bubbletea de forma limpa para restaurar o estado do cursor. Evite deixar terminais ocultos ou em modo raw.

FAQs

Relacionados

• Design de CLI em Go: Binário Único, Inicialização Rápida - âncora arquitetural
• Noções Básicas de Ferramentas CLI - exemplos introdutórios executáveis
• Árvores de Comandos cobra & urfave/cli - padrões de árvores de comandos
• Configuração: Viper, Env & Arquivos de Configuração - configuração em camadas
• Saída de Cor & Erros Amigáveis ao Usuário - stderr e códigos de saída

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 versão - verifique na build), gin (última versão - verifique na build), echo (última versão - verifique na build), google.golang.org/grpc (última versão - verifique na build), sigs.k8s.io/controller-runtime (última versão - verifique na build), kubebuilder (última versão - verifique na build), tinygo (última versão - verifique os alvos de placa na build), wazero (última versão - verifique na build) e golangci-lint (última versão - verifique o conjunto de linters na build).