Ejemplos como Documentación Ejecutable
Funciones de ejemplo con comentarios de Output en godoc.
//
Busca en todas las páginas de la documentación
Funciones de ejemplo con comentarios de Output en godoc.
Los ejemplos de Go son funciones de prueba que pkg.go.dev renderiza como documentación.
Cuando agregas un comentario // Output:, go test compara la salida estándar y falla si el ejemplo se desvía.
Complementan las pruebas basadas en tablas al mostrar la API pública tal como la usan los llamadores.
Tarjeta de receta de referencia rápida - lista para copiar y pegar.
func ExampleAdd() {
fmt.Println(Add(2, 3))
// Output: 5
}Cuándo usar esto:
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
}Lo que esto demuestra:
ExampleHello documenta la ruta común._empty agrega un segundo escenario documentado.go test verifica que la salida impresa coincida con el comentario._test.go con el código de producción en el mismo módulo.Example o ExampleXxx son recopiladas por go test._ desambigua múltiples ejemplos (ExampleSort_reverse).ExampleDoc (sin sufijo) puede documentar un paquete completo cuando se empareja con package greet en el archivo.// Output: compara la salida estándar recortada; usa // Output:\n para texto esperado multilínea.| Patrón de nombre | Aparece en |
|---|---|
ExampleFoo | Función Foo |
ExampleBar_qux | Función Bar (escenario qux) |
ExampleMyType | Tipo MyType |
ExampleMyType_method | Método en MyType |
func ExampleShuffle() {
// shuffle output - solo compilación, sin comentario Output
rand.Shuffle(3, func(i, j int) { /* ... */ })
}Omite // Output: cuando la salida no es determinista; el ejemplo aún debe compilar.
go test después de cada cambio en la documentación; actualiza el comentario cuando cambie el comportamiento.package foo o foo_test.Output es una coincidencia de cadena exacta. Solución: Coincide con el espaciado; prefiere fmt.Printf con formato explícito al enseñar APIs.package foo_test no pueden mostrar ayudantes no exportados. Solución: Usa package foo para la mecánica interna solo cuando la API exportada lo permita.| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
| Bloques de código README | Tutoriales narrativos | Necesitas verificación de CI |
| Pruebas basadas en tablas | Casos exhaustivos | Enseñar un camino feliz |
Solo comentarios go doc | Líneas triviales de una sola línea | La forma de la salida importa |
| Playground en pkg.go.dev | Fragmentos compartibles | El repositorio debe compilarse sin red |
Sí - go test los ejecuta con otras pruebas del paquete.
Los fallos en las comprobaciones de Output hacen fallar la compilación.
No - los ejemplos deben ser funciones vacías.
Usa fmt.Print para demostrar resultados.
Imprime cada valor o una estructura formateada con fmt.Printf("%#v", v).
Raro - documenta la inicialización del paquete.
La mayoría de los paquetes usan ExampleFunc en su lugar.
Evítalo - los ejemplos solo deben usar la biblioteca estándar para que godoc se mantenga libre de dependencias para los lectores.
Usa httptest e imprime el cuerpo del grabador - mantenlo corto.
Los flujos largos pertenecen a pruebas normales.
No - solo coincidencia exacta.
Para la salida de mapas no ordenada, imprime claves ordenadas o omite Output.
example_test.go o foo_test.go junto al código de producción.
go test los recoge automáticamente.
Se ejecutan localmente pero las rutas internas no aparecen en pkg.go.dev público de la misma manera.
Prefiere ejemplos en APIs de módulos exportados.
Ejecuta el ejemplo con go test -run ExampleHello -v, copia la salida estándar real en el comentario.
No - los benchmarks usan BenchmarkXxx(*testing.B).
Los ejemplos miden la documentación, no el rendimiento.
Los nombres de ejemplo no exportados no se muestran.
No hay //go:example off - elimina o renombra si no está listo.
Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado Green Tea GC, go fix modernizers - verificar parche en la compilación), chi (última - verificar en la compilación), gin (última - verificar en la compilación), echo (última - verificar en la compilación), google.golang.org/grpc (última - verificar en la compilación), sigs.k8s.io/controller-runtime (última - verificar en la compilación), kubebuilder (última - verificar en la compilación), tinygo (última - verificar objetivos de placa en la compilación), wazero (última - verificar en la compilación), y golangci-lint (última - verificar conjunto de linters en la compilación).
Revisado por Chris St. John·Última actualización: 16 jul 2026