Conceptos básicos de context

10 ejemplos para empezar con el paquete context: 7 básicos y 3 intermedios.

Prerrequisitos

• Instala Go 1.26.x o posterior desde go.dev/dl.
• Crea un módulo: mkdir ctxdemo && cd ctxdemo && go mod init example.com/ctxdemo.
• Guarda cada fragmento como main.go (o archivos separados en un mismo paquete) y ejecútalo con go run ..

Ejemplos básicos

1. context.Background y TODO

Los contextos raíz inician cadenas que no tienen cancelación de padre.

package main
 
import (
    "context"
    "fmt"
)
 
func main() {
    fmt.Println(context.Background().Err() == nil)
    fmt.Println(context.TODO().Err() == nil)
}

• context.Background() es el contexto vacío de nivel superior para main, servidores y pruebas.
• context.TODO() es un marcador de posición durante refactorizaciones cuando el padre aún no está conectado.
• Ninguno de ellos transporta una fecha límite o valores hasta que los envuelves.

Relacionado: context.Context: Cancelación como API de primera clase - por qué existe context

2. WithCancel

La cancelación manual detiene el trabajo descendiente.

package main
 
import (
    "context"
    "fmt"
    "time"
)
 
func main() {
    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()
 
    go func() {
        <-ctx.Done()
        fmt.Println("detenido:", ctx.Err())
    }()
 
    time.Sleep(50 * time.Millisecond)
    cancel()
    time.Sleep(20 * time.Millisecond)
}

• WithCancel devuelve un contexto hijo y una función cancel.
• Siempre usa defer cancel() para liberar recursos, incluso si cancelas anticipadamente.
• ctx.Err() devuelve context.Canceled después de una cancelación manual.

Relacionado: Propagación de cancelación en manejadores HTTP - ciclos de vida de solicitudes reales

3. WithTimeout

Un plazo relativo cancela automáticamente.

package main
 
import (
    "context"
    "fmt"
    "time"
)
 
func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
    defer cancel()
 
    select {
    case <-time.After(250 * time.Millisecond):
        fmt.Println("trabajo finalizado")
    case <-ctx.Done():
        fmt.Println("tiempo agotado:", ctx.Err())
    }
}

• WithTimeout(parent, d) es un atajo para WithDeadline(parent, time.Now().Add(d)).
• Cuando pasa el plazo, Done() se cierra y Err() es context.DeadlineExceeded.
• Los plazos de los hijos más cortos deben permanecer dentro del presupuesto del plazo del padre.

Relacionado: Plazos y tiempos de espera a través de los límites del servicio - presupuestos de servicio

4. WithDeadline

Los tiempos de finalización absolutos del reloj de pared se adaptan a la caducidad proporcionada por el upstream.

package main
 
import (
    "context"
    "fmt"
    "time"
)
 
func main() {
    deadline := time.Now().Add(80 * time.Millisecond)
    ctx, cancel := context.WithDeadline(context.Background(), deadline)
    defer cancel()
 
    if d, ok := ctx.Deadline(); ok {
        fmt.Println("plazo:", d.Format(time.RFC3339))
    }
    <-ctx.Done()
    fmt.Println(ctx.Err())
}

• Deadline() informa el punto de corte y si se ha establecido un plazo.
• Prefiere WithTimeout cuando piensas en duraciones; usa WithDeadline al sincronizar con una marca de tiempo externa.
• Los plazos de los padres restringen a los hijos: un hijo no puede sobrevivir a su padre.

Relacionado: Plazos y tiempos de espera a través de los límites del servicio - propagación de la caducidad

5. Comprobando ctx.Done() en un bucle

El trabajo prolongado debe sondear la cancelación entre iteraciones.

package main
 
import (
    "context"
    "fmt"
    "time"
)
 
func work(ctx context.Context) error {
    for i := 0; i < 10; i++ {
        select {
        case <-ctx.Done():
            return ctx.Err()
        default:
            time.Sleep(30 * time.Millisecond)
            fmt.Println("tick", i)
        }
    }
    return nil
}
 
func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
    defer cancel()
    fmt.Println(work(ctx))
}

• Un único select con default evita el bloqueo cuando ctx aún está activo.
• Devuelve ctx.Err() para que los llamadores distingan la cancelación de otros fallos.
• Las API de bloqueo deben aceptar ctx en lugar de sondeos manuales cuando estén disponibles.

Relacionado: Probar código que acepta context.Context - afirmando rutas de cancelación

6. Pasar ctx como el primer parámetro

La forma estándar de la función propaga el ciclo de vida hacia abajo en la pila.

package main
 
import (
    "context"
    "fmt"
)
 
func fetch(ctx context.Context, id int) (string, error) {
    if err := ctx.Err(); err != nil {
        return "", err
    }
    return fmt.Sprintf("user-%d", id), nil
}
 
func handler(ctx context.Context) error {
    name, err := fetch(ctx, 42)
    if err != nil {
        return err
    }
    fmt.Println(name)
    return nil
}
 
func main() {
    _ = handler(context.Background())
}

• Nombra el parámetro ctx y colócalo primero: los revisores y los linters esperan esto.
• Comprueba ctx.Err() antes de un trabajo costoso cuando las llamadas son profundas.
• Pasa el mismo ctx hacia abajo; no crees un Background() nuevo a mitad de la solicitud.

Relacionado: Mejores prácticas del paquete context - reglas de nomenclatura del equipo

7. WithValue para metadatos de solicitud

Las claves tipadas transportan datos transversales con moderación.

package main
 
import (
    "context"
    "fmt"
)
 
type ctxKey string
 
const requestIDKey ctxKey = "requestID"
 
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
}
 
func main() {
    ctx := withRequestID(context.Background(), "req-abc")
    fmt.Println(requestID(ctx))
}

• Usa tipos de clave no exportados para evitar colisiones entre paquetes.
• Los valores son para metadatos en el ámbito de la solicitud, no para parámetros opcionales.
• Prefiere argumentos de función explícitos para datos de negocio.

Relacionado: Valores de context: Cuándo y cuándo no - disciplina de valores

Ejemplos intermedios

8. La cancelación del hijo no detiene al padre

La cancelación fluye solo del padre al hijo.

package main
 
import (
    "context"
    "fmt"
)
 
func main() {
    parent, parentCancel := context.WithCancel(context.Background())
    defer parentCancel()
 
    child, childCancel := context.WithCancel(parent)
    defer childCancel()
 
    childCancel()
    fmt.Println("error del padre:", parent.Err())
    fmt.Println("error del hijo:", child.Err())
}

• Llamar a childCancel() establece child.Err() en context.Canceled.
• El padre permanece activo hasta que se ejecuta parentCancel().
• Diseña las API de modo que el upstream sea el propietario del ciclo de vida raíz.

Relacionado: Antipatrones de uso incorrecto de context - errores de ciclo de vida

9. Derivar un tiempo de espera más corto de un padre

Cada capa debe restar la sobrecarga del presupuesto restante.

package main
 
import (
    "context"
    "fmt"
    "time"
)
 
func callDownstream(parent context.Context) error {
    ctx, cancel := context.WithTimeout(parent, 50*time.Millisecond)
    defer cancel()
 
    select {
    case <-time.After(200 * time.Millisecond):
        return nil
    case <-ctx.Done():
        return ctx.Err()
    }
}
 
func main() {
    parent, cancel := context.WithTimeout(context.Background(), 1*time.Second)
    defer cancel()
    fmt.Println(callDownstream(parent))
}

• Los tiempos de espera de los hijos deben ser menores o iguales al tiempo restante del padre.
• El middleware a menudo reduce milisegundos para la serialización antes de llamar a los servicios.
• Registra DeadlineExceeded en la capa que estableció el tiempo de espera más corto para facilitar la depuración.

Relacionado: Plazos y tiempos de espera a través de los límites del servicio - presupuestos de salto

10. context.WithCancelCause (Go 1.20+)

Adjunta una razón a la cancelación para obtener errores más claros.

package main
 
import (
    "context"
    "errors"
    "fmt"
)
 
func main() {
    ctx, cancel := context.WithCancelCause(context.Background())
    defer cancel(nil)
 
    cause := errors.New("el fallo de validación upstream")
    cancel(cause)
 
    fmt.Println(context.Cause(ctx))
}

• WithCancelCause se empareja con context.Cause(ctx) para la observabilidad.
• Usa causas para razones de detención específicas del dominio, no para cadenas de registro genéricas.
• Sigue devolviendo ctx.Err() en los límites de la API a menos que los llamadores necesiten la causa.

Relacionado: Probar código que acepta context.Context - afirmando causas de cancelación

Versiones de la pila: Esta página se escribió para Go 1.26.x (GC predeterminado de 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).