Prácticas recomendadas para el paquete context

Convenciones del equipo para claves de contexto, tiempos de espera y apagado.

Aplique estas reglas en la revisión de código, la incorporación y las plantillas de servicio para que cada manejador, repositorio y cliente RPC propague la cancelación de manera consistente.

Cómo usar esta lista

• Marque las reglas a medida que su plantilla de servicio las adopte.
• Codifique los elementos de Nivel A en comprobaciones personalizadas de golangci-lint o pruebas de unidad de arquitectura siempre que sea posible.
• Documente los presupuestos de tiempo de espera por dependencia en README o en la configuración junto a la regla.
• Vuelva a revisar trimestralmente al agregar clientes RPC o controladores de bases de datos.

A - Firmas de funciones y propagación

• Acepte ctx context.Context como el primer parámetro en APIs bloqueantes. Los revisores rechazan nuevas E/S sin contexto.
• Nombra el parámetro ctx, no c ni context. Coincide con las expectativas de Effective Go y staticcheck.
• Pase ctx sin cambios, excepto para plazos o valores hijos intencionados. No cree Background() en medio de una solicitud.
• Devuelva ctx.Err() cuando la cancelación termine el trabajo. Consérvelo con %w solo al agregar contexto de capa.
• Reemplace Query/Exec por las variantes *Context en las rutas de solicitud. Prohíba SQL sin contexto en los manejadores.

B - Puntos de entrada HTTP y RPC

• Contexto del manejador raíz en r.Context() o equivalente del framework. Los envoltorios de chi/gin/echo todavía se mapean a la solicitud.
• Adjunte metadatos en middleware a través de r.WithContext. Los valores y los tiempos de espera cortos envuelven el ctx entrante.
• Mapee context.Canceled sin 500 ruidosos cuando la respuesta no se pueda enviar. Registre en depuración para abandonos del cliente.
• Use http.NewRequestWithContext para HTTP saliente. Vincule la vida útil de la dependencia al llamador.
• Pase ctx a los stubs de gRPC y respete los plazos en el lado del servidor. Traduzca a codes.DeadlineExceeded cuando sea apropiado.

C - Tiempos de espera y plazos

• Publique una tabla de tiempos de espera por dependencia (DB, caché, autenticación). Reduzca los presupuestos en cada salto desde el SLO del borde.
• Derive los tiempos de espera hijos del padre, nunca de Background(). Preserva la cancelación del usuario y los relojes ascendentes.
• Siempre defer cancel() después de WithCancel/WithTimeout/WithDeadline. Evita fugas de temporizadores en pruebas y producción.
• Limite los reintentos con contextos por intento más pequeños. Deténgase cuando el ctx padre ya esté hecho.
• Use Shutdown(ctx) con un contexto limitado al salir del proceso. Empareje con el manejo de señales en main.

D - Valores y claves

• Defina las claves de contexto como tipos no exportados en el paquete propietario. Evite claves de cadena en bibliotecas.
• Limite los valores a metadatos transversales (ID de solicitud, principal, idioma). Los filtros de negocio pertenecen a las estructuras.
• Exponha accesores tipados (User(ctx)) en lugar de llamadas Value crudas. Mantiene los tipos de clave privados.
• No almacene secretos ni grandes bloques en el contexto. Trate el contexto solo como una preocupación interna del proceso.
• Documente las claves permitidas en un comentario de paquete o ADR. La incorporación lee una lista, no cincuenta archivos de middleware.

E - Concurrencia, pruebas y operaciones

• Seleccione en ctx.Done() en bucles largos y flujos. Los bucles Recv/Send de gRPC se verifican en cada iteración.
• Use context.WithoutCancel solo para trabajo posterior a la respuesta documentado. La facturación y la auditoría son casos comunes.
• Pruebe en tabla las rutas Canceled y DeadlineExceeded. Los tiempos de espera cortos superan time.Sleep en CI.
• Ejecute -race en paquetes que generan gorutinas por solicitud. Detecta carreras de cancelación ignoradas.
• Registre el presupuesto de plazo restante en los límites del servicio durante incidentes de depuración. Acelera el triaje de latencia de cola.

Preguntas frecuentes

Relacionado

• context.Context: Cancelación como API de primera clase - ancla conceptual
• Conceptos básicos de context - ejemplos iniciales ejecutables
• Antipatrones de mal uso del contexto - patrones negativos a evitar
• Plazos y tiempos de espera entre límites de servicio - ejemplos de tablas de tiempos de espera
• Probar código que acepta context.Context - verificar rutas de cancelación

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