La simplicidad como restricción deliberada en el diseño de APIs

La restricción del lenguaje Go impulsa las APIs de bibliotecas y servicios hacia superficies pequeñas, dependencias explícitas y comportamiento predecible.

Eso no es una preferencia de estilo, es cómo los sistemas Go mantenibles sobreviven años de rotación de personal y actualizaciones de dependencias.

Resumen

Go favorece las APIs aburridas: pocos constructores, interfaces estrechas, errores explícitos y paquetes que hacen una sola tarea.

Esa restricción acelera las revisiones, reduce las matrices de pruebas y mantiene las actualizaciones compatibles con la promesa de Go 1.

Esta página muestra cómo diseñar límites de paquetes y HTTP que coincidan con el lenguaje en lugar de luchar contra él.

Cuándo recurrir a esto: Estás publicando una biblioteca interna compartida, estabilizando un módulo público o refactorizando un "paquete dios" antes de un cambio de versión importante.

Receta

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

// Interfaz del lado del consumidor - un método, definido donde se usa.
type ObjectStore interface {
    Put(ctx context.Context, key string, body io.Reader) error
}
 
// El constructor devuelve el tipo concreto; mantén las opciones funcionales.
type S3Store struct { /* ... */ }
 
func NewS3Store(cfg Config) (*S3Store, error) { /* valida cfg */ return &S3Store{}, nil }
 
// La función acepta una interfaz, documenta los errores.
func UploadReport(ctx context.Context, store ObjectStore, r io.Reader) error {
    if err := store.Put(ctx, "report.pdf", r); err != nil {
        return fmt.Errorf("upload report: %w", err)
    }
    return nil
}

Cuándo recurrir a esto:

• Un paquete exporta más de tres constructores o una struct Config con 20 campos.
• Los llamadores mockean interfaces que requieren simular métodos no utilizados.
• Los manejadores HTTP acceden a singletons globales en lugar de aceptar dependencias.
• Las cadenas de error son el único contrato entre servicios.

Ejemplo de Trabajo

package checkout
 
import (
    "context"
    "errors"
    "fmt"
    "time"
)
 
// Los errores de dominio son centinelas a nivel de paquete - estables para errors.Is.
var ErrInsufficientFunds = errors.New("checkout: insufficient funds")
 
type PaymentGateway interface {
    Charge(ctx context.Context, customerID string, cents int64) (chargeID string, err error)
}
 
type Service struct {
    gw  PaymentGateway
    now func() time.Time
}
 
func New(gw PaymentGateway) *Service {
    return &Service{gw: gw, now: time.Now}
}
 
type Request struct {
    CustomerID string
    Cents      int64
}
 
func (s *Service) Pay(ctx context.Context, req Request) (string, error) {
    if req.Cents <= 0 {
        return "", fmt.Errorf("checkout: invalid amount %d", req.Cents)
    }
    id, err := s.gw.Charge(ctx, req.CustomerID, req.Cents)
    if err != nil {
        return "", fmt.Errorf("checkout: charge: %w", err)
    }
    return id, nil
}

Lo que esto demuestra:

• Interfaz pequeña en el consumidor (PaymentGateway) mantiene los fakes de un método de ancho.
• Struct de servicio concreto con New documenta las dependencias requeridas sin un framework de DI.
• Error centinela más envoltura dan a los operadores una clasificación estable y cadenas depurables.
• Struct Request agrupa las entradas en lugar de aumentar la aridad de la función.
• Inyección de reloj a través del campo now muestra cómo probar el tiempo sin exportar globales.

Inmersión Profunda

Cómo Funciona

• Los paquetes de Go son la unidad de diseño de API; los identificadores exportados comienzan con una letra mayúscula y se convierten en compromisos de compatibilidad.
• Las interfaces se satisfacen implícitamente - diseña las en los puntos de llamada para que los productores no se vean obligados a declaraciones implements de boilerplate.
• Los errores son valores; envolver con %w vincula las causas mientras se preservan las comprobaciones de centinelas a través de errors.Is y las comprobaciones de tipo a través de errors.As.
• context.Context es el primer parámetro para la cancelación y los valores con ámbito de solicitud en los límites de E/S.

Reglas de Superficie de API de un Vistazo

Límites de HTTP y gRPC

Para gRPC, prefiere mensajes protobuf que reflejen los sustantivos del dominio, no todos los DTO internos.

Mapea los errores de dominio a codes.InvalidArgument, codes.NotFound y codes.Internal en un solo lugar.

Notas de Go

// Opción funcional - escala sin explosión de Config.
type Option func(*Server)
 
func WithTimeout(d time.Duration) Option {
    return func(s *Server) { s.timeout = d }
}
 
func NewServer(opts ...Option) *Server {
    s := &Server{timeout: 30 * time.Second}
    for _, opt := range opts {
        opt(s)
    }
    return s
}

• Las opciones son idiomáticas cuando los valores predeterminados son sensatos y las anulaciones son poco comunes.
• Los campos no exportados mantienen los invariantes dentro del paquete.
• Documenta qué opciones son seguras de llamar después de Start - mutar servidores en ejecución es un pie de foso común.

Trampas

• Las interfaces exportadas crecen sin límite - cada nuevo método rompe todos los mocks. Solución: dividir interfaces o mantenerlas sin exportar dentro del paquete que necesita fakes.
• Structs Config gigantes - los llamadores no conocen los campos requeridos; los valores cero los configuran silenciosamente de forma incorrecta. Solución: validar en New, devolver error, proporcionar valores predeterminados solo para perillas seguras.
• Filtración de *sql.DB a través de cada capa - acopla el dominio al almacenamiento. Solución: interfaz de repositorio con tipos de dominio en el borde del servicio.
• Errores tipificados como cadenas a través de servicios - las alertas se convierten en arqueología de expresiones regulares. Solución: documentar errores centinela y mapear a códigos HTTP/gRPC centralmente.
• Paquetes de abstracción prematuros - internal/platform/core sin llamadores. Solución: esperar al segundo consumidor antes de extraer.
• Contexto en structs - almacena la cancelación con un ámbito incorrecto. Solución: pasar context.Context por método, nunca guardarlo en campos.
• Cambios disruptivos sin versión principal - los módulos usan sufijos de ruta de importación (/v2) para cambios incompatibles en la API. Solución: planificar v2 al eliminar o renombrar exportaciones.

Alternativas

Preguntas Frecuentes

Relacionado

• Por qué existe Go - objetivos de simplicidad y legibilidad a nivel de lenguaje
• Fundamentos de la Filosofía Go - aceptar interfaces, devolver structs en la práctica
• Mejores Prácticas de la Filosofía Go - lista de verificación de modismos para todo el equipo
• Cuándo Go es la Herramienta Equivocada - cuándo no invertir en el pulido de la API de Go

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

383k393a3c3q3e393a3o1r3e3k3x383c3e3k1x1v1v3x1v1t1v1z1t20