title: "Mejores Prácticas para la Cadena de Herramientas de Go" section: go-toolchain order: 9 tags:

• "go"
• "go-toolchain"
• "best-practices"
• "list"
• "toolchain" level: basic description: "Aprenda las mejores prácticas de la cadena de herramientas de Go para compilaciones reproducibles, integración de CI y fijación de la cadena de herramientas. Mantenga los flujos de trabajo del comando go consistentes." highlights:
• "Fije la versión de Go en go.mod para que los compañeros de equipo y la CI utilicen el mismo compilador"
• "Ejecute go mod tidy después de los cambios para mantener las líneas de require mínimas y precisas"
• "Confirme go.sum con go.mod para que las sumas de verificación verifiquen compilaciones reproducibles"
• "Establezca GOPRIVATE para módulos internos para evitar filtrar rutas privadas"
• "Envíe artefactos de go build a producción, no go run, para evitar recompilaciones"
• "Use -trimpath y -ldflags para reducir los binarios de lanzamiento" updated: "2026-07-19"

Mejores Prácticas para la Cadena de Herramientas de Go

Compilaciones reproducibles, integración de CI y fijación de la cadena de herramientas.

Estas reglas mantienen los flujos de trabajo del comando go consistentes, desde los portátiles hasta la CI y los artefactos de lanzamiento.

Cómo Usar Esta Lista

• Aplique durante la revisión de PR cuando cambien los comandos de dependencia, compilación o prueba.
• Refleje los mismos valores de GOPRIVATE, GOPROXY y GOTOOLCHAIN en la CI y en la documentación para desarrolladores.
• Ejecute go mod tidy, go test ./... y linters en cada aumento de dependencia antes de fusionar.
• Vuelva a revisar después de las actualizaciones menores de Go; los modernizadores y los analizadores vet se expanden en cada lanzamiento.

A - Higiene de la cadena de herramientas y módulos

• Fije la versión de Go en go.mod y documente la política de GOTOOLCHAIN. Los compañeros de equipo y la CI deben resolver el mismo compilador; use auto solo cuando acepte descargas automáticas.
• Ejecute go mod tidy después de cualquier cambio de importación o dependencia. Mantiene las líneas require mínimas y go.sum precisas.
• Confirme go.sum siempre que cambie go.mod. Las sumas de verificación son parte del contrato de compilación reproducible.
• Establezca GOPRIVATE para cada prefijo de módulo interno. Evita filtrar rutas privadas al proxy público y a la base de datos de sumas.
• Coloque un proxy interno (Athens/Artifactory) delante de proxy.golang.org. Acelera la CI y sobrevive a las interrupciones externas.

B - Comandos de compilación y lanzamiento

• Envíe artefactos de go build, no go run, en producción. run recompila en cada invocación y oculta la ruta del binario.
• Use -trimpath y -ldflags="-s -w" para los binarios de lanzamiento. Reduce el tamaño y elimina las rutas del host de las pilas.
• Nombra las salidas explícitamente con -o bin/<nombre>. Evita colisiones al compilar múltiples comandos en un solo paso de canalización.
• Compile cruzado con CGO_ENABLED=0 a menos que realmente necesite cgo. Las matrices de Go puras son más simples en un constructor de Linux.
• Registre go version y go env en los registros de lanzamiento. Acelera la depuración cuando la CI y las compilaciones del portátil divergen.

C - Puertas de prueba, verificación y lintado

• Ejecute go test ./... (o ./... con -race en CI) en cada PR. La puerta predeterminada antes de fusionar.
• Ejecute go vet ./... antes de los linters opcionales. Línea de base de configuración cero de la biblioteca estándar.
• Ejecute golangci-lint (o staticcheck) con una configuración confirmada. Reglas de todo el equipo más allá de vet.
• Use go test -count=1 mientras depura fallos intermitentes; corrija la causa raíz antes de fusionar. No confíe en la caché de pruebas deshabilitada en la CI de producción para siempre.
• Ejecute go fix -diff después de las actualizaciones de Go, luego aplique con revisión. Los modernizadores detectan modismos que los datos de entrenamiento pueden pasar por alto.

D - Caché, vendor y CI hermética

• Caché GOMODCACHE y GOCACHE en CI. Los pasos de calentamiento de go mod download valen la pena en cada trabajo.
• Use -mod=readonly en CI cuando no esté usando vendor. Falla las compilaciones que modifican go.mod silenciosamente.
• Vuelva a hacer vendor en el mismo commit que los aumentos de dependencia cuando use vendor/. La deriva rompe las canalizaciones de -mod=vendor.
• Evite go clean -modcache en la CI de rutina. Solo borre las cachés cuando se demuestre corrupción.
• Verifique la autenticación de módulos privados en CI con una ejecución de prueba go mod download. Detecte la expiración del token antes de los pasos de compilación.

E - Generación de código y etiquetas

• Fije las versiones del generador en las directivas //go:generate. go run tool@version supera a los binarios locales indocumentados.
• Falle la CI en la deriva de go generate (git diff --exit-code). La salida generada se mantiene sincronizada con las fuentes.
• Documente los -tags requeridos para las compilaciones de producción. La prueba go test predeterminada puede omitir archivos etiquetados que la CI nunca ejercita.
• Pruebe en matriz las combinaciones de etiquetas críticas. Al menos los conjuntos de etiquetas predeterminados y de producción.
• Mantenga las etiquetas de compilación para los backends en tiempo de compilación, no para los toggles de funciones de operaciones. La configuración en tiempo de ejecución evita la rotación de reconstrucción.

Preguntas Frecuentes

Relacionado

• El Comando go: Ciclo de Vida de Compilación, Prueba y Módulos - descripción general conceptual
• Conceptos Básicos de la Cadena de Herramientas de Go - ejemplos de comandos
• go build, run, install & clean - flags de lanzamiento
• go mod tidy, vendor, download & graph - flujos de trabajo de dependencias
• Compilación Cruzada y Proxies de Módulos Privados - configuración de variables de entorno

Versiones de pila: Esta página fue escrita para Go 1.26.x (predeterminado Green Tea GC, modernizadores de go fix - verifique el parche en la compilación), chi (última - verifique en la compilación), gin (última - verifique en la compilación), echo (última - verifique en la compilación), google.golang.org/grpc (última - verifique en la compilación), sigs.k8s.io/controller-runtime (última - verifique en la compilación), kubebuilder (última - verifique en la compilación), tinygo (última - verifique los objetivos de placa en la compilación), wazero (última - verifique en la compilación) y golangci-lint (última - verifique el conjunto de linters en la compilación). cGJxcnRodnFyZi52YnxwdHZiNDU5fDIwMjYwNw==