Go Academy · Aula

Vinculação a structs

Faça unmarshal da configuração

Vinculação a structs é uma aula grátis de Go Academy no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Go Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Go Academy inclui 4 aulas no total.

De chaves soltas a uma estrutura

Chamar GetString em toda parte espalha chaves de texto pelo código. Desserializar a configuração em uma estrutura tipada fornece nomes de campos verificados em tempo de compilação e um único lugar para visualizar a estrutura.

Definindo uma estrutura de configuração

Declare uma estrutura cujos campos tenham tags mapstructure para que o Viper saiba qual chave de configuração corresponde a cada campo. Cada campo é seguido por uma tag como mapstructure:"host", escrita entre crases no código-fonte Go real.

type ServerConfig struct {
    Host string // tag: mapstructure host
    Port int    // tag: mapstructure port
}

type Config struct {
    Server ServerConfig // tag: mapstructure server
    Debug  bool         // tag: mapstructure debug
}

Chamando Unmarshal

Depois de ler a configuração, decodifique-a na sua estrutura:

var cfg Config
if err := viper.Unmarshal(&cfg); err != nil {
    log.Fatalf("unable to decode config: %v", err)
}
fmt.Println(cfg.Server.Port)

Por que mapstructure, e não json

O Viper usa a biblioteca mapstructure porque a configuração pode vir de vários formatos (YAML, variáveis de ambiente e TOML), não apenas de JSON. A tag mapstructure independe do formato e decodifica a partir de um mapa genérico.

Desserializando uma única subseção

Você pode decodificar apenas uma seção com UnmarshalKey:

var sc ServerConfig
viper.UnmarshalKey("server", &sc)
fmt.Println(sc.Host, sc.Port)

Campos aninhados e fatias

O mapstructure trata automaticamente de aninhamento e fatias:

Estruturas aninhadas correspondem a seções aninhadas da configuração
Um campo []string corresponde a uma lista YAML/JSON

Um campo de fatia teria uma tag mapstructure:"hosts" (escrita entre crases no código-fonte real).

type Config struct {
    Hosts []string // tag: mapstructure hosts
}

Valores padrão dos campos

Se uma chave estiver ausente e você não definir um padrão, o campo receberá o valor zero do Go (0, cadeia vazia, false). Combine a vinculação da estrutura com SetDefault para garantir valores sensatos.

Validando a estrutura decodificada

Depois de desserializar, valide. Um padrão comum é um método Validate() que retorna um erro para combinações impossíveis (porta 0, host vazio).

func (c Config) Validate() error {
    if c.Server.Port == 0 {
        return fmt.Errorf("server.port is required")
    }
    return nil
}

Erros de decodificação são tipados

Se um valor não puder ser armazenado no tipo do campo (uma string quando se espera um int), a decodificação retornará um erro que descreve o campo. Sempre verifique e apresente esse erro, em vez de ignorá-lo.

A mesma ideia com encoding/json

A biblioteca padrão pode decodificar JSON da mesma forma. Com tags explícitas de estrutura, ela preenche campos tipados; com um mapa, oferece acesso genérico. O exemplo executável abaixo usa um mapa aninhado para que o leitor possa executá-lo sem tags de estrutura.

Executável: decodificando uma configuração aninhada

Este programa independente decodifica uma configuração JSON aninhada em um mapa genérico e lê os campos aninhados, reproduzindo a maneira como Unmarshal preenche uma estrutura.

package main

import (
    "encoding/json"
    "fmt"
)

func main() {
    raw := "{\"server\":{\"host\":\"localhost\",\"port\":8080},\"debug\":true}"
    var c map[string]any
    if err := json.Unmarshal([]byte(raw), &c); err != nil {
        panic(err)
    }
    srv := c["server"].(map[string]any)
    fmt.Printf("%v:%v debug=%v\n", srv["host"], srv["port"], c["debug"])
}

Verificação rápida

Teste sua compreensão sobre a vinculação de configurações a estruturas.

Recapitulação

Você aprendeu a vincular configurações a estruturas:

Use tags mapstructure e viper.Unmarshal(&cfg)
UnmarshalKey decodifica uma única subárvore
Estruturas aninhadas e fatias são decodificadas automaticamente
Adicione um método Validate() para detectar combinações inválidas antecipadamente

Perguntas Frequentes

A aula “Vinculação a structs” é grátis?

Sim — o texto completo de “Vinculação a structs” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Go Academy, atualize para CoddyKit PRO. O curso de Go Academy inclui 4 aulas no total.

O que vou aprender em “Vinculação a structs”?

Faça unmarshal da configuração Você pratica Go Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Go Academy?

Nenhuma experiência prévia é necessária. Go Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.

Quanto tempo leva a aula “Vinculação a structs”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Go Academy?

Sim. Cada aula de Go Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para Go Academy