Exemplos como Documentação Executável
Funções de exemplo com comentários Output em godoc.
//
Busque em todas as páginas da documentação
Funções de exemplo com comentários Output em godoc.
Exemplos em Go são funções de teste que o pkg.go.dev renderiza como documentação.
Quando você adiciona um comentário // Output:, go test compara o stdout e falha se o exemplo divergir.
Eles complementam os testes orientados por tabela, mostrando a API pública da maneira como os chamadores a utilizam.
Cartão de receita de referência rápida - pronto para copiar e colar.
func ExampleAdd() {
fmt.Println(Add(2, 3))
// Output: 5
}Quando usar isso:
ExampleUser_Marshal)package greet
import "fmt"
func Hello(name string) string {
if name == "" {
return "Hello, world"
}
return "Hello, " + name
}
func ExampleHello() {
fmt.Println(Hello("Ada"))
// Output: Hello, Ada
}
func ExampleHello_empty() {
fmt.Println(Hello(""))
// Output: Hello, world
}O que isso demonstra:
ExampleHello documenta o caminho comum_empty adiciona um segundo cenário documentadogo test verifica se a saída impressa corresponde ao comentário_test.go com código de produção no mesmo móduloExample ou ExampleXxx são coletadas por go test._ desambigua múltiplos exemplos (ExampleSort_reverse).ExampleDoc (sem sufixo) pode documentar um pacote inteiro quando emparelhado com package greet no arquivo.// Output: compara o stdout com espaços em branco removidos; use // Output:\n para texto esperado de múltiplas linhas.| Padrão de nome | Aparece em |
|---|---|
ExampleFoo | Função Foo |
ExampleBar_qux | Função Bar (cenário qux) |
ExampleMyType | Tipo MyType |
ExampleMyType_method | Método em MyType |
func ExampleShuffle() {
// shuffle output - apenas compilação, sem comentário Output
rand.Shuffle(3, func(i, j int) { /* ... */ })
}Omita // Output: quando a saída for não determinística; o exemplo ainda deve compilar.
go test após cada alteração na documentação; atualize o comentário quando o comportamento mudar.package foo ou foo_test.Output é uma correspondência exata de string. Correção: Corresponda ao espaçamento; prefira fmt.Printf com formato explícito ao ensinar APIs.package foo_test não podem mostrar auxiliares não exportados. Correção: Use package foo para mecânicas internas apenas quando a API exportada permitir.| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
| Blocos de código README | Tutoriais narrativos | Você precisa de verificação de CI |
| Testes orientados por tabela | Casos exaustivos | Ensinando um caminho feliz |
Apenas comentários go doc | Linhas únicas triviais | A forma da saída importa |
| Playground no pkg.go.dev | Snippets compartilháveis | O repositório deve construir sem rede |
Sim - go test os executa com outros testes no pacote.
Falhas nas verificações de Output falham a compilação.
Não - exemplos devem ser funções vazias.
Use fmt.Print para demonstrar resultados.
Imprima cada valor ou uma struct formatada com fmt.Printf("%#v", v).
Raro - documenta a inicialização do pacote.
A maioria dos pacotes usa ExampleFunc em vez disso.
Evite - exemplos devem usar apenas a biblioteca padrão para que o godoc permaneça livre de dependências para os leitores.
Use httptest e imprima o corpo do gravador - mantenha-o curto.
Fluxos longos pertencem a testes normais.
Não - apenas correspondência exata.
Para saída de mapa não ordenada, imprima chaves ordenadas ou omita Output.
example_test.go ou foo_test.go ao lado do código de produção.
go test os pega automaticamente.
Eles rodam localmente, mas caminhos internos não aparecem no pkg.go.dev público da mesma forma.
Prefira exemplos em APIs de módulo exportadas.
Execute o exemplo com go test -run ExampleHello -v, copie o stdout real para o comentário.
Não - benchmarks usam BenchmarkXxx(*testing.B).
Exemplos medem documentação, não desempenho.
Nomes de exemplo não exportados não são mostrados.
Não há //go:example off - exclua ou renomeie se não estiver pronto.
Versões de Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, 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).
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026