Árvores de Comandos cobra & urfave/cli

Ferramentas no estilo kubectl precisam de subcomandos aninhados, flags globais compartilhadas e texto de ajuda consistente.

cobra (github.com/spf13/cobra) é a escolha mais comum no ecossistema Go.

urfave/cli v2 (github.com/urfave/cli/v2) oferece uma alternativa orientada a structs com hooks e completação bash.

Ambos compilam no mesmo modelo de binário único; escolha com base no gosto pela API e integração com o ecossistema (cobra se integra naturalmente com viper e scaffolds do controller-runtime).

Resumo

Árvores de comandos mapeiam argv para uma função Run ou RunE selecionada.

Comandos pais detêm flags persistentes (caminho de configuração, verbosidade), enquanto comandos folha declaram flags específicas da ação.

Execute percorre a árvore, imprime ajuda em caso de erros e define códigos de saída para scripts de shell.

Geradores de completação de shell reduzem erros de digitação para caminhos de comando longos como mytool db migrate up.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

root := &cobra.Command{Use: "mytool"}
root.PersistentFlags().StringVar(&cfgFile, "config", "", "arquivo de configuração")
root.AddCommand(&cobra.Command{
    Use:   "run",
    Short: "inicia worker",
    RunE: func(cmd *cobra.Command, args []string) error { return runWorker(cfgFile) },
})
return root.Execute()

Quando usar isso:

• Mais de dois subcomandos ou verbos de recurso aninhados (get, describe, delete).
• Flags compartilhadas entre muitos comandos (--kubeconfig, --namespace).
• Você deseja ajuda e completação de shell geradas automaticamente.
• Operadores Kubernetes gerados por kubebuilder (cobra por padrão).

Exemplo de Trabalho

package main
 
import (
    "fmt"
    "os"
 
    "github.com/spf13/cobra"
)
 
var verbose bool
 
func main() {
    root := &cobra.Command{
        Use:   "ship",
        Short: "utilitários de envio",
    }
    root.PersistentFlags().BoolVar(&verbose, "verbose", false, "logs verbosos")
 
    initCmd := &cobra.Command{
        Use:   "init",
        Short: "inicializa workspace",
        RunE: func(cmd *cobra.Command, args []string) error {
            dir, _ := cmd.Flags().GetString("dir")
            if verbose {
                fmt.Println("init", dir)
            }
            return nil
        },
    }
    initCmd.Flags().String("dir", ".", "diretório de destino")
 
    root.AddCommand(initCmd)
    if err := root.Execute(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

O que isso demonstra:

• PersistentFlags em root se aplicam a init e futuros irmãos.
• Flags locais se anexam apenas a initCmd.
• RunE retorna erros; Execute lida com a impressão e o status de saída.
• cmd.Flags().GetString lê valores analisados dentro do manipulador.

Mergulho Profundo

Como Funciona

• cobra constrói uma árvore de nós *cobra.Command no momento da inicialização.
• Execute analisa flags globais, encontra o comando correspondente mais profundo, analisa flags locais, valida Args e, em seguida, chama RunE.
• A ajuda mescla a documentação pai e filho; cmd.Help() pode ser chamado a partir do código.
• urfave/cli usa cli.App com []*cli.Command e hooks Before/After em vez de flags persistentes em uma struct.

cobra vs urfave/cli

Completação de Shell

# exemplo bash após gerar o script de completação
mytool completion bash > /etc/bash_completion.d/mytool

• Registre valores de flag válidos com RegisterFlagCompletionFunc.
• Documente a instalação no README para operadores que usam zsh ou fish.
• Mantenha a completação rápida; evite chamadas de rede durante a pressão da tecla Tab.

Notas de Go

• Mantenha a conexão de comandos no pacote cmd/; coloque a lógica de negócios em internal/.
• Prefira RunE em vez de Run para que os erros se propaguem para Execute.
• Use SilenceUsage: true em comandos quando erros de análise não devem despejar a ajuda completa.

Armadilhas

• Nomes de flag duplicados no pai e filho - cobra entra em pânico ou gera erro na inicialização. Correção: renomeie ou use persistente apenas na raiz.
• Chamar Execute de múltiplos testes sem resetar - Estado global em pflags. Correção: root.SetArgs([]string{"init", "--dir", "/tmp"}) por teste.
• Inicialização pesada em cada pacote de comando - Inicialização lenta para subcomandos não utilizados. Correção: importações preguiçosas ou binários separados para ferramentas "quentes" de CI.
• API urfave/cli v1 - Tutoriais antigos referenciam v1; o caminho do módulo mudou para /v2. Correção: fixe github.com/urfave/cli/v2.
• Validador Args ausente - Operadores passam aridade errada e obtêm erros confusos. Correção: cobra.MinimumNArgs, ValidArgsFunction personalizado.

Alternativas

FAQs

Relacionado

• Noções Básicas de Ferramentas CLI - despacho manual de subcomandos
• Pacote flag & Flags Estilo POSIX - linha de base de análise do stdlib
• Configuração: Viper, Arquivos de Ambiente & Configuração - integração BindPFlags
• kingpin & UX Avançada de CLI - alternativa de flag tipada
• Melhores Práticas para Ferramentas CLI - distribuição e testes

Versões da Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, go fix modernizers - 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).