O que é e para que serve

A biblioteca mapstructure para a linguagem Go resolve um dos problemas mais comuns ao trabalhar com dados dinâmicos: converter map[string]interface{} não estruturados em structs Go fortemente tipadas. Em projetos reais, os dados geralmente chegam como JSON, YAML, TOML ou de APIs externas, onde a estrutura pode não ser garantida. O encoding/json padrão lida bem com JSON, mas quando você trabalha com maps arbitrários (por exemplo, de arquivos de configuração, Redis Hash ou resultados de consultas SQL), precisa de uma ferramenta que mapeie dados de forma flexível e segura.

A principal função do mapstructure é pegar um map[chave]interface e preencher os campos de uma struct, convertendo tipos automaticamente, suportando structs aninhadas, slices, ponteiros e até tipos personalizados. A biblioteca é especialmente útil ao fazer parsing de configurações, onde as chaves podem estar em snake_case e os campos da struct em CamelCase, ou quando você precisa desserializar dados de fontes que não suportam o esquema JSON padrão.

A grande vantagem do mapstructure sobre o mapeamento manual é a declaratividade. Você descreve a struct com tags, e a biblioteca cuida da travessia recursiva, conversão de tipos (por exemplo, string para int), tratamento de campos opcionais e erros de incompatibilidade de tipos. Isso torna o código mais limpo, seguro e reduz significativamente a quantidade de código boilerplate.

Instalação

Para instalar a biblioteca, use o gerenciador de pacotes padrão do Go. Certifique-se de que seu módulo está inicializado (go mod init).

go get github.com/mitchellh/mapstructure

Após executar o comando, a biblioteca será adicionada ao go.mod e go.sum. Importe-a no seu código:

import "github.com/mitchellh/mapstructure"

A versão no momento da escrita deste artigo é a v1.5.0. A biblioteca não possui dependências externas, além da biblioteca padrão do Go.

Início rápido — exemplo mínimo funcional

Vamos criar uma struct Person simples e converter um map[string]interface{} em uma instância dessa struct.

package main

import (
    "fmt"
    "github.com/mitchellh/mapstructure"
)

type Person struct {
    Name string
    Age  int
    City string
}

func main() {
    input := map[string]interface{}{
        "name": "Alice",
        "age":  30,
        "city": "São Paulo",
    }

    var person Person
    err := mapstructure.Decode(input, &person)
    if err != nil {
        panic(err)
    }

    fmt.Printf("Person: %+v\n", person)
    // Saída: Person: {Name:Alice Age:30 City:São Paulo}
}

Como você pode ver, as chaves do map foram automaticamente mapeadas para os campos da struct (maiúsculas/minúsculas não são relevantes por padrão). Se a chave fosse "AGE", ela ainda assim seria mapeada para o campo Age.

Métodos e funções principais

Vamos explorar 8 funções/métodos principais da biblioteca mapstructure. Cada método vem com sua assinatura, descrição e um exemplo de código.

1. Decode

Assinatura: func Decode(input interface{}, output interface{}) error

O que faz: Função principal para decodificar um map em uma struct. Aceita qualquer input (geralmente map[string]interface{}) e um ponteiro para a struct de output. Retorna um erro se os tipos forem incompatíveis ou ocorrer outro problema.

type Config struct {
    Host string
    Port int
}

func main() {
    data := map[string]interface{}{
        "host": "localhost",
        "port": 8080,
    }
    var cfg Config
    if err := mapstructure.Decode(data, &cfg); err != nil {
        panic(err)
    }
    fmt.Printf("Config: %+v\n", cfg)
    // Saída: Config: {Host:localhost Port:8080}
}