Aplicación de gofmt y goimports

gofmt y goimports son la capa de formato que todo repositorio Go debería automatizar.

Los equipos los aplican en editores, ganchos pre-commit y CI para que las revisiones se centren en el comportamiento en lugar del espacio en blanco.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

# Formatea todos los paquetes en su lugar
gofmt -w .
goimports -local example.com/mycorp -w .
 
# CI: falla si algún archivo cambiara
test -z "$(gofmt -l .)"
test -z "$(goimports -local example.com/mycorp -l .)"
 
# Optimizaciones opcionales
gofmt -s -w .

Cuándo usar esto:

• Al iniciar CONTRIBUTING.md para un nuevo servicio Go.
• Al corregir ruido de PR de "solo formato" en un monorepo ocupado.
• Al incorporar ingenieros de lenguajes con formateadores configurables.
• Al auditar si el protobuf generado todavía pertenece a las comprobaciones de formato.

Ejemplo de Trabajo

Diseño del repositorio:

example.com/widget/
  go.mod          # module example.com/mycorp/widget
  cmd/api/main.go
  internal/store/store.go

cmd/api/main.go antes de la aplicación:

package main
 
import (
"fmt"
    "example.com/mycorp/widget/internal/store"
"net/http"
)
 
func main() {
store := store.New()
http.HandleFunc("/ok", func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintln(w, store.Ping())
})
http.ListenAndServe(":8080", nil)
}

Aplicar:

goimports -local example.com/mycorp -w ./cmd ./internal
gofmt -s -w ./cmd ./internal

Después (la agrupación de importaciones muestra el efecto de -local):

package main
 
import (
    "fmt"
    "net/http"
 
    "example.com/mycorp/widget/internal/store"
)
 
func main() {
    store := store.New()
    http.HandleFunc("/ok", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, store.Ping())
    })
    http.ListenAndServe(":8080", nil)
}

Extracto de GitHub Actions:

- name: Format check
  run: |
    test -z "$(gofmt -l .)"
    test -z "$(goimports -local example.com/mycorp -l .)"

Lo que esto demuestra:

• goimports corrige la indentación y el orden de las importaciones en una sola pasada.
• -local mantiene los módulos internos en un grupo de importación separado.
• La CI falla ante desviaciones sin reescribir las máquinas de los colaboradores.

Inmersión Profunda

Cómo Funciona

• gofmt analiza el código fuente de Go e imprime el espaciado, la indentación y los saltos de línea canónicos.
• goimports llama a gofmt después de ajustar las declaraciones de importación.
• Ambos son deterministas: no hay anulaciones de .editorconfig para el ancho de tabulación.
• gopls puede aplicar las mismas transformaciones al guardar cuando se habilitan la configuración formatting.gofumpt o goimports.

Orden de Grupos de Importación

Modos de Aplicación

Notas de Go

# Verifica que las versiones de las herramientas coincidan con la CI
gofmt -V   # incluido con la versión de Go
go version -m $(which goimports) | head -1

Fija la pseudo-versión de golang.org/x/tools en tools.go para una instalación reproducible de goimports en portátiles y agentes.

Banderas que Vale la Pena Conocer

Trampas

• Comprobar gofmt pero editar con goimports - Los colaboradores pasan localmente pero la CI falla en la agrupación de importaciones. Solución: Estandariza en goimports en los ganchos y la CI.
• Olvidar -local en CI - Las importaciones internas se mezclan con las rutas de terceros. Solución: Pasa los mismos prefijos -local en la documentación, ganchos y flujos de trabajo.
• Formatear protobuf generado - Las enormes diferencias al regenerar luchan contra los propietarios del código. Solución: Excluye *.pb.go de las rutas de gofmt -l o ejecuta el formato como parte de la generación de código.
• Versiones de Go mixtas en monorepo - La salida de gofmt rara vez difiere, pero el comportamiento de goimports puede cambiar con la versión de x/tools. Solución: Fija las herramientas a través de tools.go y go install en CI.
• Revisar parches sin formato - Las diferencias ocultan la lógica en el ruido del espacio en blanco. Solución: Requiere formato antes de abrir un PR (objetivo make fmt).
• Usar go fmt como comprobación - go fmt siempre reescribe archivos; no es un patrón de CI solo de listado. Solución: Usa gofmt -l o un trabajo de lint dedicado.

Alternativas

Preguntas Frecuentes

Relacionado

• Calidad del Código Go: Opinado por Diseño - por qué el formato es innegociable
• Conceptos Básicos de Calidad del Código - introducción a formato y vet ejecutables
• Ganchos Pre-commit y Listas de Verificación de Revisión - cableado de ganchos
• Configuración de golangci-lint - linter gofmt dentro de golangci-lint
• Estándares de Codificación y Convenciones de Documentación para Equipos - estándares más amplios para equipos

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