Valores de context: Cuándo y cuándo no

context.WithValue transporta metadatos en el ámbito de la solicitud a través de pilas de llamadas sin pasar diez parámetros de cadena a cada función.

Usado correctamente, los valores contienen IDs de rastreo y principales de autenticación; usado incorrectamente, se convierten en un mapa global para datos de negocio opcionales.

Resumen

Almacena metadatos de infraestructura transversales en el contexto con claves tipadas no exportadas.

Pasa las entradas de negocio como parámetros de función explícitos.

Nunca pongas secretos en los valores de contexto sin entender que pueden filtrarse a través de registros e introspección.

Receta

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

type ctxKey int
 
const (
    requestIDKey ctxKey = iota
    userKey
)
 
func WithRequestID(ctx context.Context, id string) context.Context {
    return context.WithValue(ctx, requestIDKey, id)
}
 
func RequestID(ctx context.Context) string {
    v, _ := ctx.Value(requestIDKey).(string)
    return v
}

Cuándo usar esto:

• Middleware adjunta IDs de solicitud, sujetos de autenticación o idioma después de analizar encabezados.
• Los registradores y exportadores de métricas leen valores en las llamadas hoja sin cambiar cada firma.
• No almacenes filtros opcionales, paginación o alternadores de funciones que pertenezcan a structs.

Ejemplo de trabajo

package main
 
import (
    "context"
    "fmt"
    "log/slog"
)
 
type ctxKey string
 
const (
    requestIDKey ctxKey = "requestID"
    userKey      ctxKey = "user"
)
 
type User struct {
    ID   string
    Role string
}
 
func withMeta(ctx context.Context, reqID string, u User) context.Context {
    ctx = context.WithValue(ctx, requestIDKey, reqID)
    return context.WithValue(ctx, userKey, u)
}
 
func logAction(ctx context.Context, action string) {
    attrs := []any{slog.String("action", action)}
    if id, ok := ctx.Value(requestIDKey).(string); ok && id != "" {
        attrs = append(attrs, slog.String("request_id", id))
    }
    if u, ok := ctx.Value(userKey).(User); ok && u.ID != "" {
        attrs = append(attrs, slog.String("user_id", u.ID))
    }
    slog.Info("audit", attrs...)
}
 
func serviceCall(ctx context.Context) {
    logAction(ctx, "billing.sync")
}
 
func main() {
    ctx := withMeta(context.Background(), "req-7f3a", User{ID: "u-42", Role: "admin"})
    serviceCall(ctx)
    fmt.Println("done")
}

Lo que esto demuestra:

• Los tipos de clave no exportados respaldados por cadenas evitan colisiones entre paquetes.
• Las funciones hoja enriquecen los registros desde el contexto sin parámetros adicionales.
• Los valores son opcionales: las aserciones de tipo toleran claves faltantes.
• Los nombres de las acciones de negocio permanecen explícitos; solo los metadatos provienen del contexto.

Inmersión Profunda

Cómo funciona

• Los valores de contexto forman una cadena enlazada; Value recorre los punteros padres hasta que una clave coincide.
• Las llamadas posteriores a WithValue sombrean las claves padres con el mismo tipo y valor.
• Los valores son inmutables: las actualizaciones requieren un nuevo contexto hijo a través de WithValue.
• No hay una API de enumeración: los consumidores deben conocer las claves de antemano.

Valores Aceptables vs Inaceptables

Adjunto de Middleware (net/http)

func authMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        u := UserFromJWT(r.Header.Get("Authorization"))
        ctx := context.WithValue(r.Context(), userKey, u)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

Prefiere tipos de valor pequeños copiados por valor o punteros inmutables.

Notas de Go

// El paquete auth posee sus claves; otros paquetes no pueden colisionar
package auth
 
type key struct{}
 
var userKey = key{}
 
func User(ctx context.Context) (User, bool) {
    u, ok := ctx.Value(userKey).(User)
    return u, ok
}

Trampas

• Claves de cadena en bibliotecas - Los paquetes de terceros pueden colisionar en "user". Solución: claves tipadas no exportadas por paquete.
• Almacenamiento de conexiones de bases de datos - La vida útil no coincide limpiamente con el ámbito de la solicitud. Solución: pasa *sql.DB a través de constructores, no del contexto.
• Mutación de structs de valor después de adjuntar - Carrera si las gorutinas comparten punteros. Solución: almacena instantáneas inmutables o copia en escritura.
• Uso del contexto para parámetros opcionales - Oculta la superficie de la API y rompe el análisis estático. Solución: struct de opciones o parámetros explícitos.
• Registro de contexto completo - No hay API de serialización; los valores pueden incluir PII. Solución: lista blanca de claves para exportadores de registros.
• Valores de interfaz nil - WithValue(ctx, key, nil) aún almacena una entrada. Solución: omite la clave cuando está ausente o usa tipos puntero.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos básicos de context - Ejemplo introductorio de WithValue
• Propagación de cancelación en manejadores HTTP - cableado de middleware
• Contexto en database/sql & gRPC - metadatos en RPC
• Antipatrones de mal uso de context - patrones de abuso de valores
• Mejores prácticas del paquete context - reglas de propiedad de claves

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado de GC Green Tea, 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). NzA2MjAyfDI2NG9pZ2N8b2kuc2VkaXVnZWRvYw==