Pacote flag & Flags Estilo POSIX

O pacote flag da biblioteca padrão do Go analisa opções de linha de comando sem dependências de terceiros.

Ele suporta tipos booleanos, string, inteiros, duração e flag.Value personalizados, com -nome=valor estilo POSIX e flags curtas booleanas clusterizadas.

Para ferramentas multi-comando, instâncias dedicadas de flag.FlagSet evitam que as flags de subcomandos colidam.

Resumo

flag registra variáveis antes de Parse, e então as modifica a partir de os.Args.

O conjunto padrão é flag.CommandLine; CLIs de produção frequentemente usam flag.NewFlagSet por subcomando.

O texto de uso, tratamento de erros e saída de ajuda são personalizáveis para que scripts e humanos obtenham um comportamento previsível.

Receita

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

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, "tempo limite da operação")
_ = fs.Parse(os.Args[2:])

Quando usar isso:

• Ferramentas de binário único com um comando e uma superfície de flags modesta.
• Subcomandos que você despacha manualmente com um switch em os.Args[1].
• Testes que precisam de um conjunto de flags isolado sem tocar nos globais.
• Bibliotecas que não devem puxar o cobra para cada consumidor.

Exemplo de Trabalho

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("o modo deve ser dry ou 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 ou apply")
    verbose := fs.Bool("v", false, "logging verboso")
    timeout := fs.Duration("timeout", 10*time.Second, "tempo máximo de espera")
    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())
}

O que isso demonstra:

• Tipos personalizados implementam flag.Value com Set e String.
• fs.Var registra enumerações com validação em Set.
• Flags Duration analisam strings de duração do Go (300ms, 2m).
• O uso imprime no stderr com padrões para cada flag.

Mergulho Profundo

Como Funciona

• Registro (String, Bool, Int, Var) grava metadados em um FlagSet.
• Parse percorre os argumentos: flags começam com -; o primeiro token não-flag encerra a análise de flags, a menos que FlagSet tenha sido configurado de outra forma.
• Flags booleanas aceitam -v, -v=true e -v=false.
• Após a análise, Args() retorna os tokens posicionais restantes.

Convenções de Análise em Resumo

Modos de Erro do FlagSet

Notas do Go

// Introspect flags em testes
fs.Visit(func(f *flag.Flag) {
    t.Log(f.Name, f.Value.String())
})

• Evite mutar flag.CommandLine em bibliotecas; exporte uma Run(args []string) que use um FlagSet privado.
• O estilo GNU --long não é nativo; os usuários esperam o estilo POSIX de um único traço, a menos que você adicione um wrapper.
• Combine com embed ou padrões de env em main, não dentro de pacotes reutilizáveis.

Armadilhas

• Análise antes que todas as flags sejam registradas - Chamadas String tardias após Parse silenciosamente perdem argv. Correção: registre todas as flags na inicialização antes de Parse.
• flag.CommandLine global em testes - Testes paralelos disputam o mesmo conjunto. Correção: NewFlagSet por caso de teste.
• Offset fs.Parse(os.Args[2:]) ausente - O nome do subcomando é analisado como um valor de flag. Correção: fatie os argumentos após o token do subcomando.
• Uso em stdout - Quebra padrões tool --help | grep misturados com pipes de dados. Correção: sempre Fprintf(os.Stderr, ...).
• Sem subcomandos embutidos - O despacho manual escala mal após três comandos. Correção: migre para cobra ou urfave/cli.

Alternativas

FAQs

Relacionado

• Noções Básicas de Ferramentas CLI - exemplos introdutórios de flags
• Design de CLI em Go: Binário Único, Inicialização Rápida - modelo de compilação e distribuição
• Árvores de Comandos cobra & urfave/cli - frameworks de subcomandos
• Configuração: Viper, Env & Arquivos de Configuração - flags mais env e arquivos
• Melhores Práticas para Ferramentas CLI - checklist de testes e UX

Versões da Stack: Esta página foi escrita para Go 1.26.x (padrão GC Green Tea, go fix modernizers - verifique o patch na compilação), chi (última - verifique na compilação), gin (última - verifique na compilação), echo (última - verifique na compilação), google.golang.org/grpc (última - verifique na compilação), sigs.k8s.io/controller-runtime (última - verifique na compilação), kubebuilder (última - verifique na compilação), tinygo (última - verifique os alvos de placa na compilação), wazero (última - verifique na compilação) e golangci-lint (última - verifique o conjunto de linters na compilação).