Árboles de Comandos de cobra & urfave/cli

Las herramientas estilo kubectl necesitan subcomandos anidados, flags globales compartidos y texto de ayuda consistente.

cobra (github.com/spf13/cobra) es la opción más común en el ecosistema Go.

urfave/cli v2 (github.com/urfave/cli/v2) ofrece una alternativa basada en structs con hooks y completado de bash.

Ambos compilan en el mismo modelo de binario único; elige basándote en el gusto por la API y la integración con el ecosistema (cobra se empareja naturalmente con viper y los scaffolds de controller-runtime).

Resumen

Los árboles de comandos mapean argv a una función Run o RunE seleccionada.

Los comandos padre albergan flags persistentes (ruta de configuración, verbosidad) mientras que los comandos hoja declaran flags específicos de la acción.

Execute recorre el árbol, imprime ayuda en caso de errores y establece códigos de salida para scripts de shell.

Los generadores de completado de shell reducen los errores tipográficos para rutas de comandos largas como mytool db migrate up.

Receta

Tarjeta de referencia rápida - lista para copiar y pegar.

root := &cobra.Command{Use: "mytool"}
root.PersistentFlags().StringVar(&cfgFile, "config", "", "archivo de configuración")
root.AddCommand(&cobra.Command{
    Use:   "run",
    Short: "iniciar worker",
    RunE: func(cmd *cobra.Command, args []string) error { return runWorker(cfgFile) },
})
return root.Execute()

Cuándo usar esto:

• Más de dos subcomandos o verbos de recursos anidados (get, describe, delete).
• Flags compartidos entre muchos comandos (--kubeconfig, --namespace).
• Quieres ayuda y completado de shell autogenerados.
• Operadores de Kubernetes generados por kubebuilder (cobra por defecto).

Ejemplo Funcional

package main
 
import (
    "fmt"
    "os"
 
    "github.com/spf13/cobra"
)
 
var verbose bool
 
func main() {
    root := &cobra.Command{
        Use:   "ship",
        Short: "utilidades de envío",
    }
    root.PersistentFlags().BoolVar(&verbose, "verbose", false, "logs detallados")
 
    initCmd := &cobra.Command{
        Use:   "init",
        Short: "inicializar espacio de trabajo",
        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", ".", "directorio de destino")
 
    root.AddCommand(initCmd)
    if err := root.Execute(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

Lo que esto demuestra:

• PersistentFlags en root se aplican a init y a sus futuros hermanos.
• Los flags locales se adjuntan solo a initCmd.
• RunE devuelve errores; Execute maneja la impresión y el estado de salida.
• cmd.Flags().GetString lee los valores analizados dentro del manejador.

Inmersión Profunda

Cómo Funciona

• cobra construye un árbol de nodos *cobra.Command en tiempo de inicialización.
• Execute analiza los flags globales, encuentra el comando coincidente más profundo, analiza los flags locales, valida Args, y luego llama a RunE.
• La ayuda fusiona la documentación del padre y del hijo; cmd.Help() es invocable desde el código.
• urfave/cli usa cli.App con []*cli.Command y hooks Before/After en lugar de flags persistentes en una struct.

cobra vs urfave/cli

Completado de Shell

# ejemplo de bash después de generar el script de completado
mytool completion bash > /etc/bash_completion.d/mytool

• Registra valores de flag válidos con RegisterFlagCompletionFunc.
• Documenta la instalación en README para operadores que usan zsh o fish.
• Mantén el completado rápido; evita llamadas de red durante la pulsación de tabulación.

Notas de Go

• Mantén la conexión de comandos en el paquete cmd/; pon la lógica de negocio en internal/.
• Prefiere RunE sobre Run para que los errores se propaguen a Execute.
• Usa SilenceUsage: true en los comandos cuando los errores de análisis no deban volcar la ayuda completa.

Trampas

• Nombres de flags duplicados en padre e hijo - cobra entra en pánico o falla al inicializar. Solución: renombra o usa persistentes solo en la raíz.
• Llamar a Execute desde múltiples pruebas sin restablecer - Estado global en pflags. Solución: root.SetArgs([]string{"init", "--dir", "/tmp"}) por prueba.
• Inicialización pesada en cada paquete de comando - Inicio lento para subcomandos no utilizados. Solución: importaciones perezosas o binarios separados para herramientas de CI-calientes.
• API de urfave/cli v1 - Tutoriales antiguos hacen referencia a v1; la ruta del módulo cambió a /v2. Solución: fija github.com/urfave/cli/v2.
• Validadores de Args faltantes - Los operadores pasan la aridad incorrecta y obtienen errores confusos. Solución: cobra.MinimumNArgs, ValidArgsFunction personalizado.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Herramientas CLI - despacho manual de subcomandos
• Paquete flag & Flags Estilo POSIX - línea base de análisis de stdlib
• Configuración: Viper, Archivos de Entorno y Configuración - integración de BindPFlags
• kingpin & UX Avanzada de CLI - alternativa de flag tipado
• Mejores Prácticas para Herramientas CLI - distribución y pruebas

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado GC de Green Tea, go fix modernizers - verifica el parche en la compilación), chi (última - verifica en la compilación), gin (última - verifica en la compilación), echo (última - verifica en la compilación), google.golang.org/grpc (última - verifica en la compilación), sigs.k8s.io/controller-runtime (última - verifica en la compilación), kubebuilder (última - verifica en la compilación), tinygo (última - verifica objetivos de placa en la compilación), wazero (última - verifica en la compilación), y golangci-lint (último - verifica el conjunto de linters en la compilación).