Buenas Prácticas para Herramientas CLI

Pruebas de CLIs, versionado y distribución a través de go install.

Aplica estas reglas en la revisión de código, pipelines de lanzamiento y plantillas de plataforma internas para que cada binario de Go se instale de forma predecible, falle claramente y se mantenga testeable sin contaminación de flags globales.

Cómo Usar Esta Lista

• Marca las reglas a medida que tu plantilla CLI las adopte.
• Codifica los elementos de Nivel A en CI (salida de ayuda dorada, pruebas de códigos de salida) siempre que sea posible.
• Publica tablas de códigos de salida y precedencia de configuración en el README de la herramienta.
• Revisa al agregar modos TUI, nuevos subcomandos o lanzamientos multiplataforma.

A - UX y flujos

• Reserva stdout para salida de contrato legible por máquina. Mantén el texto, los colores y el progreso en stderr.
• Imprime errores de uso y análisis en stderr. Las tuberías y los envoltorios de kubectl se mantienen limpios.
• Respeta NO_COLOR y deshabilita ANSI cuando no sea una TTY. Los registros de CI y las políticas de accesibilidad dependen de ello.
• Documenta los códigos de salida más allá de 0 y 1. Los scripts se ramifican en fallos de configuración vs. autenticación cuando están documentados.
• Falla rápidamente ante errores de configuración y flags antes de I/O. Ahorra tiempo y evita mutaciones parciales.

B - Estructura y dependencias

• Mantén main delgado; pon la lógica en paquetes internal/. Permite pruebas unitarias sin os.Exit.
• Evita flag.CommandLine global en bibliotecas. Usa FlagSet o cobra por comando.
• Un framework de análisis por binario. No mezcles kingpin, cobra y flags de stdlib en el mismo argv.
• Comparte tipos de dominio con servicios en internal/. CLI y API se mantienen alineados en enums e IDs.
• Retrasa importaciones pesadas para subcomandos críticos en CI cuando el perfil demuestre la necesidad. Divide binarios solo con datos.

C - Configuración

• Documenta la precedencia: flags > env > archivo > valores predeterminados. Los operadores deben saber qué valor prevalece.
• Usa prefijo de entorno y reemplazador de claves para claves anidadas de viper. Mapea API_URL a api.url de forma predecible.
• Nunca incluyas secretos en archivos de configuración de ejemplo. Envía config.example.yaml con marcadores de posición.
• Valida la configuración requerida después de la fusión. Devuelve errores centinela mapeados al código de salida 2.
• Restablece o aísla viper en las pruebas. Evita la contaminación de pruebas paralelas de la configuración global.

D - Árboles de comandos y flags

• Usa cobra o urfave/cli cuando los subcomandos excedan dos ramas manuales. La finalización y la ayuda compensan el costo de la dependencia.
• Adjunta flags compartidos con PersistentFlags solo en la raíz. Evita nombres de flags duplicados en el padre e hijo.
• Valida la aridad con ayudantes Args o enums. Los recuentos de argumentos incorrectos producen mensajes accionables.
• Genera y documenta la finalización de shell para herramientas de operador. Reduce errores tipográficos en rutas de comandos largas.
• Marca comandos obsoletos con advertencias antes de su eliminación. Da a los consumidores un ciclo de lanzamiento para migrar.

E - Pruebas y calidad

• Prueba run(args []string) error sin analizar os.Args reales. La lógica central se mantiene segura en paralelo.
• Usa cobra.Command.SetArgs o FlagSet.Parse aislado en pruebas CLI. Sin sangrado de flags entre pruebas.
• Agrega pruebas de integración os/exec para códigos de salida y salida de ayuda. Detecta errores de cableado en main.
• Prueba dorada --help cuando la superficie del comando sea estable. Los cambios de nombre de flags no intencionados rompen scripts.
• Ejecuta go test ./... con el detector de carreras para CLIs concurrentes. Los trabajadores y las TUI exponen las carreras temprano.

F - Compilación, versión y distribución

• Estampa la versión con -ldflags "-X main.version=…" en CI. El soporte puede mapear informes de errores a compilaciones.
• Expón el subcomando --version o version. Coincide con las etiquetas de la imagen de contenedor y las etiquetas de git.
• Publica a través de go install module/path@version para módulos públicos. Documenta la ruta de importación en README.
• Adjunta archivos de lanzamiento compilados cruzados por GOOS/GOARCH. Los operadores de Linux, macOS y Windows obtienen binarios nativos.
• Registra la integridad de go.sum y notas de compilación reproducibles en los lanzamientos. La revisión de la cadena de suministro depende de ello.

G - Interfaz de usuario de terminal y operaciones largas

• Detecta no-TTY y degrada TUI a líneas de registro. GitHub Actions y cron carecen de soporte de pantalla alternativa.
• Ejecuta trabajo bloqueante fuera del goroutine Update de bubbletea. Envía mensajes de finalización de vuelta al modelo.
• Maneja ctrl+c y señales para CLIs por lotes. Las escrituras parciales no deben corromper el estado remoto.
• Muestra el progreso en stderr para trabajos de minutos. Los operadores necesitan retroalimentación sin romper el JSON de stdout.
• Cierra programas de bubbletea limpiamente para restaurar el estado del cursor. Evita dejar terminales ocultas o en modo raw.

Preguntas Frecuentes

Relacionado

• Diseño CLI en Go: Binario Único, Inicio Rápido - ancla arquitectónica
• Conceptos Básicos de Herramientas CLI - ejemplos introductorios ejecutables
• Árboles de Comandos de cobra & urfave/cli - patrones de árboles de comandos
• Configuración: Viper, Entorno y Archivos de Configuración - configuración en capas
• Salida de Color y Errores Amigables para el Usuario - stderr y códigos de salida

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado Green Tea GC, 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 (última - verifica el conjunto de linters en la compilación).