Struct Tags & Custom Tag Parsing

Tags de struct anexam metadados declarativos a campos.

Bibliotecas leem essas strings em tempo de execução com reflection ou em tempo de compilação com ferramentas AST.

Esta página mostra como analisar tags json, db e validate e construir um pequeno binder personalizado.

Resumo

Tags de struct são strings entre crases (backticks) após a declaração de um campo.

O pacote reflect as expõe como valores StructTag com Get e Lookup.

Parsers de produção validam a sintaxe, suportam múltiplas chaves e armazenam planos de campo por tipo em cache.

Para caminhos de alta performance, a geração de código lê as mesmas tags da origem e emite atribuições diretas.

Receita

Cartão de referência rápida para análise de tags.

// Declaração de campo
Name string `json:"name,omitempty" db:"user_name" validate:"required,min=2"`
 
// Lê uma chave
tag := field.Tag.Get("json")        // "name,omitempty"
name, opts, _ := strings.Cut(tag, ",")
 
// Lookup com flag ok
v, ok := field.Tag.Lookup("validate") // "required,min=2", true

Quando usar isso:

• Construindo binders de configuração, env ou CLI a partir de tags de struct
• Escrevendo middleware de validação que reflete DTOs de requisição
• Compartilhando uma única struct entre APIs JSON e colunas SQL através de chaves de tag diferentes
• Prototipagem antes de investir em um passo go generate

Exemplo de Trabalho

Um parser mínimo de tag env que preenche uma struct a partir de um mapa.

package main
 
import (
	"fmt"
	"reflect"
	"strconv"
	"strings"
)
 
type Server struct {
	Host string `env:"HOST" validate:"required"`
	Port int    `env:"PORT" validate:"min=1"`
}
 
type fieldPlan struct {
	index int
	key   string
	kind  reflect.Kind
}
 
func plans(t reflect.Type) ([]fieldPlan, error) {
	if t.Kind() != reflect.Struct {
		return nil, fmt.Errorf("precisa de struct")
	}
	var out []fieldPlan
	for i := 0; i < t.NumField(); i++ {
		f := t.Field(i)
		if !f.IsExported() {
			continue
		}
		key, ok := f.Tag.Lookup("env")
		if !ok || key == "" {
			continue
		}
		out = append(out, fieldPlan{index: i, key: key, kind: f.Type.Kind()})
	}
	return out, nil
}
 
func bind(ptr any, env map[string]string) error {
	v := reflect.ValueOf(ptr)
	if v.Kind() != reflect.Ptr || v.Elem().Kind() != reflect.Struct {
		return fmt.Errorf("ptr deve ser *struct")
	}
	v = v.Elem()
	t := v.Type()
	fp, err := plans(t)
	if err != nil {
		return err
	}
	for _, p := range fp {
		raw, ok := env[p.key]
		if !ok {
			continue
		}
		fv := v.Field(p.index)
		switch p.kind {
		case reflect.String:
			fv.SetString(raw)
		case reflect.Int:
			n, err := strconv.Atoi(raw)
			if err != nil {
				return fmt.Errorf("%s: %w", p.key, err)
			}
			fv.SetInt(int64(n))
		default:
			return fmt.Errorf("tipo não suportado %s para %s", p.kind, p.key)
		}
	}
	return nil
}
 
func main() {
	s := &Server{}
	err := bind(s, map[string]string{"HOST": "0.0.0.0", "PORT": "3000"})
	fmt.Println(s, err)
}

O que isso demonstra:

• Tag.Lookup distingue chaves ausentes de valores vazios
• Planos de campo armazenam índices em cache para que binds repetidos evitem percorrer tipos novamente
• Apenas campos exportados podem ser vinculados de outros pacotes
• Tags de validação estão presentes para um validador subsequente (veja "Gotchas")

Mergulho Profundo

Como Funciona

• O compilador armazena tags como strings opacas; nenhuma validação em tempo de compilação da sintaxe da tag.
• reflect.Type.Field(i) retorna StructField com Name, Type, Tag e offset.
• StructTag.Get(key) retorna a porção do valor antes da primeira vírgula para aquela chave.
• Múltiplas chaves vivem em uma única string: `json:"x" xml:"x"`.

Chaves de Tag Comuns

Análise de Regras de Validação

Divide por vírgulas, depois analisa opções chave=valor:

func parseRules(tag string) map[string]string {
	rules := map[string]string{}
	for _, part := range strings.Split(tag, ",") {
		k, v, ok := strings.Cut(strings.TrimSpace(part), "=")
		if !ok {
			rules[k] = "true"
			continue
		}
		rules[k] = v
	}
	return rules
}

Notas de Go

// Armazena planos em cache por reflect.Type em um sync.Map para frameworks
var cache sync.Map // chave: reflect.Type, valor: []fieldPlan

Gotchas

• Espaços dentro de valores de tag - Tags não podem conter espaços sem escape; use vírgulas para opções. Correção: Siga a gramática documentada de cada biblioteca.
• Chaves JSON duplicadas - Dois campos com json:"name" causam sobrescritas silenciosas em encoding/json. Correção: Execute go vet e linters personalizados no CI.
• Campos não exportados - Outros pacotes não podem defini-los via reflection. Correção: Mantenha campos vinculáveis exportados ou permaneça no pacote.
• Alterações de tag sem invalidar cache - Fatias fieldPlan em cache ficam obsoletas se você recarregar tipos em plugins de longa duração. Correção: Use a identidade do tipo como chave do cache e documente os limites de recarga dinâmica.
• Ignorando o ok do Lookup - Get retorna "" tanto para ausentes quanto para vazios. Correção: Use Lookup quando a presença for importante.
• Strings de tag enormes - Cadeias de validação muito longas prejudicam a legibilidade. Correção: Mova regras complexas para funções de validação personalizadas.

WTI5a1pXZDFhV1JsY3k1cGIzeGpaMmx2TkRRd2ZESXdNall3Tnc9PQ==

Alternativas

FAQs

Relacionado

• Fundamentos de Reflection - Fundamentos de iteração de campos
• Reflection vs. Geração de Código em Go - Tags em ambos os modelos
• Construindo Geradores de Código Personalizados - Geração de código de tags baseada em AST
• Custos de Reflection de ORM & Serializador - Custos de ORM baseados em tags

Versões de 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 versão - verifique na compilação), gin (última versão - verifique na compilação), echo (última versão - verifique na compilação), google.golang.org/grpc (última versão - verifique na compilação), sigs.k8s.io/controller-runtime (última versão - verifique na compilação), kubebuilder (última versão - verifique na compilação), tinygo (última versão - verifique os alvos de placa na compilação), wazero (última versão - verifique na compilação) e golangci-lint (última versão - verifique o conjunto de linters na compilação).