Paquete flag y Flags Estilo POSIX

El paquete flag de la biblioteca estándar de Go analiza opciones de línea de comandos sin dependencias de terceros.

Admite tipos booleanos, de cadena, enteros, de duración y flag.Value personalizados, con -nombre=valor estilo POSIX y flags cortas booleanas agrupadas.

Para herramientas de comandos múltiples, instancias flag.FlagSet dedicadas evitan que los flags de subcomandos choquen.

Resumen

flag registra variables antes de Parse, luego las modifica a partir de os.Args.

El conjunto predeterminado es flag.CommandLine; las CLIs de producción a menudo usan flag.NewFlagSet por subcomando.

El texto de uso, el manejo de errores y la salida de ayuda son personalizables para que los scripts y los humanos obtengan un comportamiento predecible.

Receta

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

fs := flag.NewFlagSet("deploy", flag.ExitOnError)
fs.Usage = func() {
    fmt.Fprintf(os.Stderr, "uso: mytool deploy [flags] <env>\n")
    fs.PrintDefaults()
}
timeout := fs.Duration("timeout", 30*time.Second, "tiempo de espera de la operación")
_ = fs.Parse(os.Args[2:])

Cuándo usar esto:

• Herramientas de un solo binario con un comando y una superficie de flags modesta.
• Subcomandos que se despachan manualmente con un switch en os.Args[1].
• Pruebas que necesitan un conjunto de flags aislado sin tocar los globales.
• Bibliotecas que no deben incluir cobra en cada consumidor.

Ejemplo de Trabajo

package main
 
import (
    "flag"
    "fmt"
    "os"
    "time"
)
 
type mode string
 
func (m *mode) Set(s string) error {
    switch s {
    case "dry", "apply":
        *m = mode(s)
        return nil
    default:
        return fmt.Errorf("el modo debe ser dry o apply")
    }
}
 
func (m *mode) String() string { return string(*m) }
 
func main() {
    fs := flag.NewFlagSet("run", flag.ExitOnError)
    var m mode
    fs.Var(&m, "mode", "dry o apply")
    verbose := fs.Bool("v", false, "registro detallado")
    timeout := fs.Duration("timeout", 10*time.Second, "espera máxima")
    fs.Usage = func() {
        fmt.Fprintf(os.Stderr, "uso: %s run [flags]\n", os.Args[0])
        fs.PrintDefaults()
    }
    if err := fs.Parse(os.Args[1:]); err != nil {
        os.Exit(2)
    }
    fmt.Printf("mode=%s verbose=%v timeout=%s args=%v\n", m, *verbose, *timeout, fs.Args())
}

Lo que esto demuestra:

• Los tipos personalizados implementan flag.Value con Set y String.
• fs.Var registra enumeraciones con validación en Set.
• Los flags Duration analizan cadenas de duración de Go (300ms, 2m).
• Usage imprime en stderr con los valores predeterminados para cada flag.

Inmersión Profunda

Cómo Funciona

• Registro (String, Bool, Int, Var) guarda metadatos en un FlagSet.
• Parse recorre los argumentos: los flags comienzan con -; el primer token que no es un flag finaliza el análisis de flags a menos que FlagSet lo indique de otra manera.
• Los flags booleanos aceptan -v, -v=true y -v=false.
• Después del análisis, Args() devuelve los tokens posicionales restantes.

Convenciones de Análisis de un Vistazo

Modos de Error de FlagSet

Notas de Go

// Introspeccionar flags en pruebas
fs.Visit(func(f *flag.Flag) {
    t.Log(f.Name, f.Value.String())
})

• Evita mutar flag.CommandLine en bibliotecas; exporta un Run(args []string) que use un FlagSet privado.
• --long estilo GNU no es nativo; los usuarios esperan el estilo POSIX de un solo guion a menos que agregues un envoltorio.
• Combina con embed o valores predeterminados de entorno en main, no dentro de paquetes reutilizables.

Trampas

• Análisis antes de que se registren todos los flags - Las llamadas tardías a String después de Parse omiten silenciosamente argv. Solución: registra cada flag al inicio antes de Parse.
• flag.CommandLine global en pruebas - Las pruebas paralelas luchan por el mismo conjunto. Solución: NewFlagSet por caso de prueba.
• Falta el desplazamiento fs.Parse(os.Args[2:]) - El nombre del subcomando se analiza como un valor de flag. Solución: corta los args después del token del subcomando.
• Uso en stdout - Rompe los patrones tool --help | grep mezclados con tuberías de datos. Solución: siempre Fprintf(os.Stderr, ...).
• Sin subcomandos incorporados - El despacho manual escala mal más allá de tres comandos. Solución: migra a cobra o urfave/cli.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Herramientas CLI - ejemplos introductorios de flags
• Diseño CLI en Go: Binario Único, Arranque Rápido - modelo de compilación y distribución
• Árboles de Comandos de cobra & urfave/cli - frameworks de subcomandos
• Configuración: Viper, Entorno y Archivos de Configuración - flags más entorno y archivos
• Mejores Prácticas para Herramientas CLI - lista de verificación de pruebas y UX

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