Aula 18 - Ferramentas de Linha de Comando (CLI) com Cobra e Viper 💻

📑 1. Fundamentos Teóricos & Análise Técnica

As ferramentas mais consagradas de infraestrutura moderna (como kubectl, docker, hugo, gh e terraform) são construídas em Go utilizando o framework Cobra e o gerenciador de configuração Viper.

A arquitetura do Cobra apoia-se em uma gramática POSIX consistente: 1. Padrão de Gramática: APP NOME_COMANDO [SUBCOMANDO] --FLAGS [ARGUMENTOS]: - Permite organizar CLIs em estruturas hierárquicas claras (ex: git remote add origin ... ou kubectl get pods -n producao). 2. Flags Locais vs. Flags Persistentes (Persistent Flags): - Flags Locais: Válidas exclusivamente para o comando específico no qual foram declaradas. - Flags Persistentes: Válidas para o comando raiz e herdadas recursivamente por todos os subcomandos descendentes (ex: --verbose, --config, --output=json). 3. Gerenciamento de Configuração com Viper: - Ordem estrita de precedência de configuração (da maior para a menor prioridade): 1. Flags explícitas passadas na linha de comando. 2. Variáveis de ambiente (ENV_VARS). 3. Arquivo de configuração persistente (config.yaml, config.json). 4. Valores padrão declarados em código (Defaults).

📐 Arquitetura Conceitual & Diagrama de Fluxo

graph TD
    User["Comando: appctl deploy --env=prod --timeout=30s"] --> Cobra["Cobra CLI Engine (Parser de Argumentos)"]
    Cobra --> Precedence["Viper: Avaliação de Precedência de Configuração"]
    Precedence --> P1["1. Flags da Linha de Comando (Prioridade Máxima)"]
    Precedence --> P2["2. Variáveis de Ambiente (APPCTL_*)"]
    Precedence --> P3["3. Arquivo de Configuração (.appctl.yaml)"]
    Precedence --> P4["4. Valores Padrão em Código (Defaults)"]
    P1 & P2 & P3 & P4 --> Execute["Execução do Comando de Engenharia de Sistemas"]
    style User fill:#e1f5fe,stroke:#01579b
    style Cobra fill:#fff3e0,stroke:#e65100
    style Precedence fill:#f3e5f5,stroke:#7b1fa2
    style Execute fill:#e8f5e9,stroke:#2e7d32

🔍 Pilares e Diretrizes Técnicas

Nesta unidade, aprofundamos os seguintes conceitos fundamentais: - Gramática POSIX Padronizada: Conformidade com flags curtas (-v) e longas (--verbose) seguindo o padrão GNU/Linux. - Precedência Declarativa com Viper: Elimina divergências de configuração garantindo que flags de terminal sempre sobreponham arquivos locais. - Auto-Geração de Man Pages e Bash/Zsh Completion: Facilita a produtividade do operador gerando scripts de autocompletar automaticamente. - Validação Estrita de Argumentos (Args: cobra.ExactArgs): Impede execuções com parâmetros faltantes através de validadores embutidos.

🛠️ 2. Implementação Prática em Ferramental CLI em Go, Cobra Framework e Viper

Abaixo está a implementação técnica de referência, estruturada com padrões de engenharia de software e foco em robustez:

// cli_tool_cobra.go (Estrutura de CLI Profissional com Cobra e Viper)
package main

import (
    "fmt"
    "os"

    "github.com/spf13/cobra"
    "github.com/spf13/viper"
)

var (
    cfgFile string
    verbose bool

    rootCmd = &cobra.Command{
        Use:   "sysctl-pro",
        Short: "Utilitário avançado de diagnóstico e engenharia de sistemas",
        Long:  "sysctl-pro é uma ferramenta CLI construída em Go para telemetria e inspeção de nós.",
    }

    pingCmd = &cobra.Command{
        Use:   "ping [host]",
        Short: "Testa conectividade e latência com um nó remoto",
        Args:  cobra.ExactArgs(1),
        Run: func(cmd *cobra.Command, args []string) {
            host := args[0]
            timeout := viper.GetInt("timeout")
            fmt.Printf("Disparando ping contra %s (Timeout: %ds, Verbose: %v)...\n", host, timeout, verbose)
        },
    }
)

func init() {
    cobra.OnInitialize(initConfig)
    rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "Arquivo de config (padrão: $HOME/.sysctl.yaml)")
    rootCmd.PersistentFlags().BoolVarP(&verbose, "verbose", "v", false, "Ativar logs detalhados de depuração")

    pingCmd.Flags().IntP("timeout", "t", 5, "Tempo limite em segundos")
    _ = viper.BindPFlag("timeout", pingCmd.Flags().Lookup("timeout"))

    rootCmd.AddCommand(pingCmd)
}

func initConfig() {
    viper.SetDefault("timeout", 5)
    viper.SetEnvPrefix("SYSCTL")
    viper.AutomaticEnv()
}

func main() {
    if err := rootCmd.Execute(); err != nil {
        os.Exit(1)
    }
}

💡 Análise Passo a Passo do Código

1. Uso de cobra.ExactArgs(1): Garante que o comando falhe com mensagem instrutiva caso o usuário não informe o hostname alvo.
2. Binding com viper.BindPFlag: Integra a flag --timeout ao sistema de variáveis de ambiente SYSCTL_TIMEOUT.
3. Flags Persistentes Globais: Permite que a flag -v / --verbose seja utilizada em qualquer subcomando da ferramenta.

🎯 3. Próximos Passos & Sequência Didática