go generate & stringer

Q: stringer pode lidar com múltiplos tipos?

Sim: stringer -type=Foo,Bar ou múltiplas diretivas.

Q: Onde as diretivas de generate vivem?

Em qualquer arquivo .go no pacote, comumente ao lado da definição do tipo.

Q: Como fixo a versão do stringer?

Use um tools.go com a tag de build tools e instale essa versão do módulo no CI.

go generate orquestra geradores de código.

stringer é o gerador "hello-world": constantes tipadas recebem um método String() correto sem reflection.

Resumo

Coloque comentários //go:generate acima de funções ou tipos em qualquer arquivo .go.

Execute go generate ./... a partir da raiz do módulo para executar esses comandos.

stringer emite um arquivo *_string.go com String() para enums baseados em int.

Equipes confirmam a saída gerada e reexecutam os geradores quando os tipos mudam.

Receita

Fluxo de trabalho de geração de referência rápida.

//go:generate stringer -type=Status -trimprefix=Status
 
type Status int
 
const (
    StatusPending Status = iota
    StatusActive
    StatusDone
)

go install golang.org/x/tools/cmd/stringer@latest
go generate ./...
go test ./...

Quando usar isso:

Enums registrados em métricas, APIs ou UI precisam de nomes de string estáveis
Você quer String() em tempo de compilação sem manter switch statements manualmente
O CI deve falhar quando arquivos gerados divergirem dos tipos fonte
Você está introduzindo qualquer ferramenta go generate (mockgen, protobuf, stringer)

Exemplo de Trabalho

Mini-módulo completo com saída do stringer confirmada.

// status.go
package job
 
//go:generate stringer -type=Status -trimprefix=Status
 
type Status int
 
const (
    StatusPending Status = iota
    StatusRunning
    StatusFailed
    StatusSucceeded
)
 
func (s Status) IsTerminal() bool {
    return s == StatusFailed || s == StatusSucceeded
}

Após go generate:

// status_string.go (gerado)
package job
 
import "strconv"
 
func _() {
    _ = x[StatusPending-0]
}
 
const _Status_name = "PendingRunningFailedSucceeded"
 
var _Status_index = [...]uint8{0, 7, 14, 20, 29}
 
func (i Status) String() string {
    if i < 0 || i >= Status(len(_Status_index)-1) {
        return "Status(" + strconv.FormatInt(int64(i), 10) + ")"
    }
    return _Status_name[_Status_index[i]:_Status_index[i+1]]
}

// job_test.go
package job
 
import "testing"
 
func TestStatusString(t *testing.T) {
    if StatusRunning.String() != "Running" {
        t.Fatal(StatusRunning.String())
    }
}

O que isso demonstra:

-trimprefix remove o prefixo redundante Status da saída da string
O arquivo gerado fica ao lado da fonte com um cabeçalho DO NOT EDIT (o stringer o adiciona)
Valores numéricos inválidos recebem uma string de fallback segura Status(99)
Testes travam o comportamento sem reflection

Mergulho Profundo

Como go generate Funciona

Escaneia arquivos .go em busca de linhas que começam com //go:generate
Executa cada comando com $GOFILE e $GOPACKAGE definidos como o arquivo e pacote contêineres
Não analisa dependências; a ordem segue a ordem de varredura dos arquivos
Falhas param as diretivas restantes desse pacote, a menos que você as programe de outra forma

Geradores Comuns

Ferramenta	Exemplo de diretiva	Saída
stringer	`//go:generate stringer -type=T`	`t_string.go`
mockgen	`//go:generate mockgen -source=iface.go`	`mock_iface.go`
protobuf	`//go:generate protoc --go_out=. api.proto`	`api.pb.go`
enumer	utilitários de enum de terceiros	customizado

Verificação de Drift no CI

go generate ./...
git diff --exit-code || (echo "execute go generate e confirme"; exit 1)

Notas Go

// Mantenha geradores no módulo tools ou em tools.go com a tag de build
//go:build tools
 
package tools
 
import _ "golang.org/x/tools/cmd/stringer"

Armadilhas

Esperar que go build execute generate - Não vai. Correção: Makefile, etapa de CI ou hook de pre-commit.
Editar arquivos gerados - A próxima geração sobrescreverá as correções. Correção: Altere as flags do gerador ou as entradas do template.
stringer após renomear constantes - Strings desatualizadas até a regeneração. Correção: Adicione um portão de CI para gerar+comparar.
Múltiplos tipos em um arquivo - Cada um precisa de sua própria diretiva ou lista -type. Correção: Linhas //go:generate separadas por tipo.
Vendoring stringer - Fixe a versão do golang.org/x/tools em tools.go para CI reproduzível. Correção: go install na versão do módulo fixada no CI.
Arquivos gerados no ruído da revisão de código - Grandes diffs em tweaks de enum. Correção: Commits dedicados para regeneração.

Alternativas

Alternativa	Use Quando	Não Use Quando
`String()` escrito à mão	Uma ou duas constantes	Grandes enums mudam frequentemente
`fmt.Sprintf("%d")`	Apenas para depuração	Logs e APIs precisam de nomes
iota + map	Enums minúsculos sem tooling	Você já usa stringer em outros lugares
enums protobuf	Serviços gRPC	Tipos de domínio Go puros

FAQs

go generate roda em go test?

Não.

Invoque-o explicitamente no CI ou em scripts locais.

Devo confirmar arquivos gerados?

A maioria dos projetos Go sim, para que os consumidores construam sem ferramentas geradoras.

Documente o comando de regeneração no README ou CONTRIBUTING.

O que -trimprefix faz?

Remove um prefixo dos nomes das constantes na string gerada.

StatusRunning se torna "Running" com -trimprefix=Status.

stringer pode lidar com múltiplos tipos?

Sim: stringer -type=Foo,Bar ou múltiplas diretivas.

Onde as diretivas de generate vivem?

Em qualquer arquivo .go no pacote, comumente ao lado da definição do tipo.

Como fixo a versão do stringer?

Use um tools.go com a tag de build tools e instale essa versão do módulo no CI.

E se generate falhar no CI?

Corrija o comando do gerador, plugins protoc ausentes ou PATH.

Registre $GOFILE para a diretiva que falhou.

stringer é baseado em reflection?

Não.

É um gerador de código em tempo de compilação usando go/types.

Posso usar go generate com go fix?

Sim.

Propósitos diferentes: generate cria arquivos; fix moderniza chamadas.

Execute ambos em branches de upgrade.

Como testo métodos String gerados?

Teste em tabela constantes conhecidas e um valor fora do intervalo.

Relacionados

Construindo Geradores de Código Personalizados - escreva seu próprio gerador
Reflection vs. Geração de Código em Go - codegen vs reflect
Diretivas Inline e de Migração de API go:fix - ferramentas de migração
Boas Práticas de Reflection e Geração de Código - regras de fluxo de trabalho da equipe

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

stringer é o gerador "hello-world": constantes tipadas recebem um método String() correto sem reflection.

Resumo

Coloque comentários //go:generate acima de funções ou tipos em qualquer arquivo .go.

Execute go generate ./... a partir da raiz do módulo para executar esses comandos.

stringer emite um arquivo *_string.go com String() para enums baseados em int.

Equipes confirmam a saída gerada e reexecutam os geradores quando os tipos mudam.

Receita

Fluxo de trabalho de geração de referência rápida.

//go:generate stringer -type=Status -trimprefix=Status
 
type Status int
 
const (
    StatusPending Status = iota
    StatusActive
    StatusDone
)

go install golang.org/x/tools/cmd/stringer@latest
go generate ./...
go test ./...

Quando usar isso:

Enums registrados em métricas, APIs ou UI precisam de nomes de string estáveis
Você quer String() em tempo de compilação sem manter switch statements manualmente
O CI deve falhar quando arquivos gerados divergirem dos tipos fonte
Você está introduzindo qualquer ferramenta go generate (mockgen, protobuf, stringer)

Exemplo de Trabalho

Mini-módulo completo com saída do stringer confirmada.

// status.go
package job
 
//go:generate stringer -type=Status -trimprefix=Status
 
type Status int
 
const (
    StatusPending Status = iota
    StatusRunning
    StatusFailed
    StatusSucceeded
)
 
func (s Status) IsTerminal() bool {
    return s == StatusFailed || s == StatusSucceeded
}

Após go generate:

// status_string.go (gerado)
package job
 
import "strconv"
 
func _() {
    _ = x[StatusPending-0]
}
 
const _Status_name = "PendingRunningFailedSucceeded"
 
var _Status_index = [...]uint8{0, 7, 14, 20, 29}
 
func (i Status) String() string {
    if i < 0 || i >= Status(len(_Status_index)-1) {
        return "Status(" + strconv.FormatInt(int64(i), 10) + ")"
    }
    return _Status_name[_Status_index[i]:_Status_index[i+1]]
}

// job_test.go
package job
 
import "testing"
 
func TestStatusString(t *testing.T) {
    if StatusRunning.String() != "Running" {
        t.Fatal(StatusRunning.String())
    }
}

O que isso demonstra:

-trimprefix remove o prefixo redundante Status da saída da string
O arquivo gerado fica ao lado da fonte com um cabeçalho DO NOT EDIT (o stringer o adiciona)
Valores numéricos inválidos recebem uma string de fallback segura Status(99)
Testes travam o comportamento sem reflection

Mergulho Profundo

Como go generate Funciona

Escaneia arquivos .go em busca de linhas que começam com //go:generate
Executa cada comando com $GOFILE e $GOPACKAGE definidos como o arquivo e pacote contêineres
Não analisa dependências; a ordem segue a ordem de varredura dos arquivos
Falhas param as diretivas restantes desse pacote, a menos que você as programe de outra forma

Geradores Comuns

Ferramenta	Exemplo de diretiva	Saída
stringer	`//go:generate stringer -type=T`	`t_string.go`
mockgen	`//go:generate mockgen -source=iface.go`	`mock_iface.go`
protobuf	`//go:generate protoc --go_out=. api.proto`	`api.pb.go`
enumer	utilitários de enum de terceiros	customizado

Verificação de Drift no CI

go generate ./...
git diff --exit-code || (echo "execute go generate e confirme"; exit 1)

Notas Go

// Mantenha geradores no módulo tools ou em tools.go com a tag de build
//go:build tools
 
package tools
 
import _ "golang.org/x/tools/cmd/stringer"

Armadilhas

Esperar que go build execute generate - Não vai. Correção: Makefile, etapa de CI ou hook de pre-commit.
Editar arquivos gerados - A próxima geração sobrescreverá as correções. Correção: Altere as flags do gerador ou as entradas do template.
stringer após renomear constantes - Strings desatualizadas até a regeneração. Correção: Adicione um portão de CI para gerar+comparar.
Múltiplos tipos em um arquivo - Cada um precisa de sua própria diretiva ou lista -type. Correção: Linhas //go:generate separadas por tipo.
Vendoring stringer - Fixe a versão do golang.org/x/tools em tools.go para CI reproduzível. Correção: go install na versão do módulo fixada no CI.
Arquivos gerados no ruído da revisão de código - Grandes diffs em tweaks de enum. Correção: Commits dedicados para regeneração.

Alternativas

Alternativa	Use Quando	Não Use Quando
`String()` escrito à mão	Uma ou duas constantes	Grandes enums mudam frequentemente
`fmt.Sprintf("%d")`	Apenas para depuração	Logs e APIs precisam de nomes
iota + map	Enums minúsculos sem tooling	Você já usa stringer em outros lugares
enums protobuf	Serviços gRPC	Tipos de domínio Go puros

FAQs

go generate roda em go test?

Não.

Invoque-o explicitamente no CI ou em scripts locais.

Devo confirmar arquivos gerados?

A maioria dos projetos Go sim, para que os consumidores construam sem ferramentas geradoras.

Documente o comando de regeneração no README ou CONTRIBUTING.

O que -trimprefix faz?

Remove um prefixo dos nomes das constantes na string gerada.

StatusRunning se torna "Running" com -trimprefix=Status.

stringer pode lidar com múltiplos tipos?

Sim: stringer -type=Foo,Bar ou múltiplas diretivas.

Onde as diretivas de generate vivem?

Em qualquer arquivo .go no pacote, comumente ao lado da definição do tipo.

Como fixo a versão do stringer?

Use um tools.go com a tag de build tools e instale essa versão do módulo no CI.

E se generate falhar no CI?

Corrija o comando do gerador, plugins protoc ausentes ou PATH.

Registre $GOFILE para a diretiva que falhou.

stringer é baseado em reflection?

Não.

É um gerador de código em tempo de compilação usando go/types.

Posso usar go generate com go fix?

Sim.

Propósitos diferentes: generate cria arquivos; fix moderniza chamadas.

Execute ambos em branches de upgrade.

Como testo métodos String gerados?

Teste em tabela constantes conhecidas e um valor fora do intervalo.

Relacionados

Construindo Geradores de Código Personalizados - escreva seu próprio gerador
Reflection vs. Geração de Código em Go - codegen vs reflect
Diretivas Inline e de Migração de API go:fix - ferramentas de migração
Boas Práticas de Reflection e Geração de Código - regras de fluxo de trabalho da equipe

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

go generate & stringer

Buscar na documentação

go generate & stringer