Guía de inicio rápida de Go Rules

10 ejemplos para empezar con las reglas de Go: 7 básicos y 3 intermedios.

Prerrequisitos

• Instala Go 1.26.x o posterior desde go.dev/dl.
• Crea un módulo: mkdir rulesdemo && cd rulesdemo && go mod init example.com/rulesdemo.
• Lee Effective Go una vez, luego usa esta página como un compañero ejecutable.

Ejemplos básicos

1. gofmt es innegociable

El formato canónico es la primera regla que comparte cada repositorio de Go.

gofmt -w .
test -z "$(gofmt -l .)" || echo "los archivos necesitan formato"

package main
 
import "fmt"
 
func main() {fmt.Println("antes de gofmt")}

• gofmt elimina por completo el debate sobre el formato de las revisiones de código.
• La CI debe fallar cuando gofmt -l imprima cualquier ruta.
• No hay configuración de estilo por proyecto que mantener.

Relacionado: Effective Go como estándar vivo - cómo la guía oficial se superpone con las reglas del equipo

2. Comprueba cada retorno de error

Go trata los errores como valores; ignorarlos viola los modismos centrales.

package main
 
import (
    "fmt"
    "os"
)
 
func main() {
    f, err := os.Open("config.yaml")
    if err != nil {
        fmt.Fprintf(os.Stderr, "abrir config: %v\n", err)
        os.Exit(1)
    }
    defer f.Close()
}

• Cada err de una llamada a función necesita una rama explícita.
• Las bibliotecas devuelven errores; main decide si registrar, envolver o salir.
• _ descarta solo cuando aceptas deliberadamente la pérdida de señal.

Relacionado: Errores como valores: la filosofía de errores de Go - por qué los errores no son excepciones

3. Envuelve errores con contexto

Añade %w cuando los llamadores necesiten errors.Is o errors.As.

package demo
 
import (
    "errors"
    "fmt"
    "io"
)
 
var ErrNotFound = errors.New("demo: no encontrado")
 
func Load(r io.Reader) error {
    if r == nil {
        return fmt.Errorf("carga: %w", ErrNotFound)
    }
    return nil
}

• Envuelve en los límites donde añades contexto de operación (load, fetch user).
• Los centinelas permanecen estables; los mensajes envueltos pueden incluir IDs.
• No envuelvas puramente para cambiar la redacción sin nueva información.

Relacionado: Envoltura de errores con %w y errors.As - profundidad de envoltura e inspección

4. context.Context como primer parámetro

Las funciones de IO y RPC aceptan cancelación y plazos a través de context.

package demo
 
import (
    "context"
    "time"
)
 
func Fetch(ctx context.Context, id string) error {
    ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
    defer cancel()
    // ... usa ctx en llamadas salientes
    return nil
}

• Nombra el parámetro ctx; colócalo primero en la firma.
• Pasa ctx por la pila; no lo almacenes en structs.
• context.Background() pertenece a main, pruebas y manejadores de nivel superior.

Relacionado: Lista de verificación de reglas de concurrencia - reglas de cancelación y propiedad

5. Acepta interfaces, devuelve tipos concretos

Mantén los parámetros de función flexibles; mantén los tipos de retorno específicos.

package demo
 
import "io"
 
type Store struct{}
 
func (s *Store) Save(w io.Writer, data []byte) (int, error) {
    return w.Write(data)
}
 
func NewStore() *Store { return &Store{} }

• Los llamadores pasan io.Writer, io.Reader o interfaces de dominio pequeñas.
• Devolver *Store evita comportamientos sorpresa detrás de interfaces sin nombre.
• Define interfaces junto a los consumidores, no junto a los productores.

Relacionado: Reglas de diseño de API para bibliotecas de Go - reglas de nomenclatura y superficie

6. Documenta los símbolos exportados

Los identificadores exportados son un contrato de compatibilidad.

// Package demo muestra godoc mínimo en exportaciones.
package demo
 
// Greeter formatea un saludo para name.
// Devuelve una cadena vacía cuando name está en blanco.
func Greeter(name string) string {
    if name == "" {
        return ""
    }
    return "hello, " + name
}

• Godoc en paquetes y funciones/tipos exportados es obligatorio para bibliotecas.
• Comienza los comentarios con el nombre del símbolo ("Greeter ...").
• Los ejemplos en example_test.go aparecen en pkg.go.dev.

Relacionado: Lista de verificación de reglas de Effective Go - lista completa de modismos

7. Ejecuta go vet antes de la revisión

Vet detecta errores que el compilador permite.

go vet ./...

package main
 
import "fmt"
 
func main() {
    fmt.Printf("%d", "text") // vet: discrepancia de verbo de formato
}

• Añade vet a la CI junto con las pruebas.
• Las nuevas versiones de Go a veces añaden analizadores de vet; lee las notas de la versión.
• Vet complementa a los linters; no es un sustituto de las pruebas.

Relacionado: Conceptos básicos de calidad de código - formato, vet y hooks

Ejemplos intermedios

8. Pruebas basadas en tablas para ejemplos de reglas

Codifica el comportamiento de la regla como datos para que los revisores vean los casos claramente.

package demo
 
import "testing"
 
func TestGreeter(t *testing.T) {
    tests := []struct {
        name string
        in   string
        want string
    }{
        {"vacío", "", ""},
        {"alice", "alice", "hello, alice"},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            if got := Greeter(tt.in); got != tt.want {
                t.Fatalf("got %q want %q", got, tt.want)
            }
        })
    }
}

• Las pruebas de tablas documentan el comportamiento esperado mejor que las reglas en prosa.
• Usa nombres de t.Run que se lean como elementos de una lista de verificación.
• Empareja con -race cuando las pruebas toquen goroutines.

Relacionado: Pruebas basadas en tablas y subpruebas - reglas de estructura de pruebas

9. internal/ para límites de módulos

Oculta los paquetes de implementación que los consumidores no deben importar.

rulesdemo/
  go.mod
  demo/
    public.go
  internal/
    storage/
      storage.go

// la raíz del módulo importa solo paquetes públicos; internal es forzado por el compilador.
import "example.com/rulesdemo/internal/storage" // falla fuera del módulo

• Las rutas internal/ son rechazadas por el compilador a través de los límites del módulo.
• La superficie de la API pública se mantiene pequeña; semver se aplica a los paquetes exportados.
• Prefiere internal sobre la documentación sola para "no importar".

Relacionado: Nomenclatura de paquetes y directorios internal/ - reglas de diseño

10. Mide antes de aplicar reglas de rendimiento

Las reglas de optimización asumen evidencia de perfilado.

go test -bench=. -benchmem ./...
go test -cpuprofile=cpu.prof -bench=. ./...
go tool pprof -top cpu.prof

• Por defecto, usa código claro; optimiza los caminos calientes mostrados en los perfiles.
• Registra benchmarks de referencia al reclamar una mejora de velocidad.
• Lee Reglas de rendimiento: Cuándo optimizar antes de ajustar GC o asignaciones.

Relacionado: Reglas de rendimiento: Cuándo optimizar - flujo de trabajo de medir primero

Enlaces externos relacionados

• A Tour of Go - Introducción interactiva oficial a Go.
• Effective Go - Guía oficial para escribir Go claro e idiomático.
• Tutoriales de Go (Oficial) - Tutoriales oficiales en varias partes.
• Get Programming with Go (Manning) - Nathan Youngman & Roger Peppé.
• The Go Programming Language (ebook) - Donovan & Kernighan.

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