Conceptos básicos de calidad de código

10 ejemplos para empezar con la calidad de código en Go: 7 básicos y 3 intermedios.

Prerrequisitos

• Instala Go 1.26.x o posterior desde go.dev/dl.
• Crea un módulo: mkdir quality && cd quality && go mod init example.com/quality.
• Instala las utilidades: go install golang.org/x/tools/cmd/goimports@latest y go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest.

Ejemplos básicos

1. gofmt en su lugar

Reescribe un archivo al formato canónico de Go.

gofmt -w main.go

package main
 
import "fmt"
 
func main() {fmt.Println("hello")}

Después de gofmt -w, el espaciado y la indentación coinciden con el estilo de la comunidad.

• gofmt es determinista: la misma entrada siempre produce la misma salida.
• La CI a menudo ejecuta test -z "$(gofmt -l .)" para fallar ante desviaciones.
• No hay una configuración de formato a nivel de proyecto que mantener.

Relacionado: Aplicación de gofmt y goimports - política de formato del equipo

2. goimports para importaciones

Formatea y corrige bloques de importación en un solo paso.

goimports -w .

package main
 
import "fmt"
 
func main() {
    fmt.Println(time.Now()) // falta importación antes de goimports
}

• goimports añade importaciones faltantes de la biblioteca estándar y elimina las no utilizadas.
• Usa -local example.com/quality para agrupar las rutas de tu módulo por separado.
• Los editores a menudo ejecutan goimports al guardar a través de gopls.

Relacionado: Aplicación de gofmt y goimports - agrupación -local

3. go vet en todos los paquetes

Ejecuta analizadores integrados en todo el módulo.

go vet ./...

package main
 
import "fmt"
 
func main() {
    fmt.Printf("%d", "not-a-number") // vet: discrepancia de formato en Printf
}

• Vet informa sobre problemas que el compilador acepta pero que probablemente sean errores.
• Ejecútalo en la CI en cada PR; el valor predeterminado debe ser cero hallazgos.
• Las nuevas versiones de Go pueden añadir comprobaciones de vet; lee las notas de la versión.

Relacionado: go vet y diagnósticos comunes de analizadores - mensajes comunes

4. Puerta de enlace de pruebas mínima

La calidad incluye el comportamiento, no solo las comprobaciones estáticas.

go test ./...

package add
 
func Sum(a, b int) int { return a + b }

package add_test
 
import "testing"
 
func TestSum(t *testing.T) {
    if got := add.Sum(2, 3); got != 5 {
        t.Fatalf("got %d", got)
    }
}

• Las pruebas viven en archivos *_test.go en el mismo paquete (o en el paquete externo _test).
• go test compila las pruebas con el detector de carreras cuando pasas -race.
• Los fallos en las pruebas deben bloquear la fusión antes de que los debates sobre linters importen.

Relacionado: Puertas de calidad de CI: Lint, Test, Race, Vuln - pipeline completo

5. Listar archivos sin formato

Comprueba el formato sin escribir archivos (amigable para CI).

gofmt -l .

• Una salida vacía significa que cada archivo .go está formateado.
• Una salida no vacía lista las rutas que necesitan gofmt -w.
• Combínalo con git diff --exit-code después de formatear en hooks pre-commit.

Relacionado: Hooks pre-commit y listas de verificación de revisiones - automatización local

6. Primera ejecución de golangci-lint

Ejecuta el paquete de linters estándar.

golangci-lint run ./...

• La primera ejecución descarga los binarios de los analizadores; fija la versión en la CI para reproducibilidad.
• Empieza con los linters por defecto; ajusta .golangci.yml después de que la línea base esté en verde.
• Corrige problemas de clase vet antes de perseguir pequeños detalles de estilo.

Relacionado: Configuración de golangci-lint - patrones de archivos de configuración

7. Target check de Makefile

Un comando para los colaboradores.

.PHONY: check
check:
	gofmt -l . | tee /tmp/gofmt.out && test ! -s /tmp/gofmt.out
	go vet ./...
	go test ./...

make check

• Documenta make check en README y CONTRIBUTING.
• Expande con golangci-lint run cuando el equipo esté listo.
• Mantén los targets lo suficientemente rápidos para los hooks pre-push (< 2 minutos en portátiles).

Relacionado: Mejores prácticas de linting y calidad de código - ritmo de adopción

Ejemplos intermedios

8. Detector de carreras en pruebas

Detecta carreras de datos que vet no encuentra.

go test -race ./...

package counter
 
import "sync"
 
type Counter struct {
    mu sync.Mutex
    n  int
}
 
func (c *Counter) Inc() {
    c.mu.Lock()
    c.n++
    c.mu.Unlock()
}

• -race ralentiza las pruebas y necesita más memoria; ejecútalo en la CI, no en cada guardado.
• Los fallos de carreras incluyen pilas de goroutines; arréglalos añadiendo sincronización.
• Los manejadores HTTP que comparten estado mutable sin bloqueos son un desencadenante común.

Relacionado: Puertas de calidad de CI: Lint, Test, Race, Vuln - cuándo requerir race

9. Comprobación de go mod tidy

Mantén la metainformación del módulo consistente.

go mod tidy
git diff --exit-code go.mod go.sum

• Falla la CI cuando las dependencias se desvían sin actualizaciones de go.sum confirmadas.
• Ejecútalo después de las actualizaciones de dependencias y antes de etiquetar lanzamientos.
• Combínalo con govulncheck para el escaneo de seguridad en el grafo ordenado.

Relacionado: govulncheck para vulnerabilidades de dependencias - escaneo de CVE

10. Script simple de pre-commit

Bloquea commits que fallan las comprobaciones rápidas.

#!/usr/bin/env bash
set -euo pipefail
gofmt -l . | grep . && { echo "run gofmt -w"; exit 1; } || true
go vet ./...
go test ./...

chmod +x scripts/pre-commit.sh
# enlazar con: ln -s ../../scripts/pre-commit.sh .git/hooks/pre-commit

• Los hooks detectan problemas antes del tiempo de espera de la cola de CI.
• Mantén los hooks rápidos; delega golangci-lint a la CI si excede ~60s localmente.
• Documenta la política de omisión (--no-verify) solo para emergencias.

Relacionado: Hooks pre-commit y listas de verificación de revisiones - plantillas de hooks

Versiones de la pila: Esta página se escribió para Go 1.26.x (predeterminado Green Tea GC, go fix modernizers - 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 la 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). Y29kZWd1aWRlcy5pb3xjZ2lvNDUwfDIwMjYwNw==