Prácticas recomendadas avanzadas de concurrencia

Patrones para APIs y servicios concurrentes resilientes.

Estas reglas resumen la sección de concurrencia avanzada: paralelismo limitado, propagación de cancelación, apagado limpio y pruebas de seguridad con tests y perfiles.

Cómo usar esta lista

• Aplique al diseñar un nuevo servicio concurrente o al revisar una ruta crítica antes del lanzamiento.
• Use Nivel A en cada PR que toque goroutines o canales.
• Promueva a Nivel B después del primer incidente de producción o prueba de carga.
• Empareje con Evitar fugas de goroutines y deadlocks de canales durante incidentes.
• Revise cuando las versiones menores de Go cambien el comportamiento del planificador o de x/sync.

A - Limitado y protegido

• Limitar las E/S salientes paralelas con un semáforo o pool. Coincidir los límites con MaxOpenConns de la base de datos y las cuotas de los socios de la API.
• Limitar la velocidad de inicio de solicitudes en el borde. Usar un bucket de tokens antes de que el trabajo entre en un costoso fan-out.
• Descartar carga con errores explícitos cuando las colas están llenas. Devolver errores 503 o reintentables en lugar de búferes ilimitados.
• Dimensionar los búferes de canal deliberadamente. Documentar por qué existe cada profundidad de búfer; evitar valores predeterminados de "9999".
• Hacer fan-out solo cuando la capacidad descendente lo admita. Medir 429s y latencia antes de aumentar el paralelismo.

B - Contexto y cancelación

• Pasar context.Context como primer parámetro después del receptor. La cancelación se propaga a través de clientes QueryContext, gRPC y HTTP.
• Usar r.Context() en los manejadores HTTP. Vincular el trabajo del manejador a la desconexión del cliente y al apagado del servidor.
• Derivar el contexto de errgroup con WithContext. La primera falla cancela a los hermanos que aún realizan E/S.
• Separar el contexto del trabajo en segundo plano del contexto de la solicitud. Los trabajadores de Cron y outbox se cancelan con SIGTERM, no con inactividad del cliente.
• Respetar ctx.Done() en cada bucle largo o reintento de bloqueo. Ninguna goroutine debe ignorar la cancelación durante segundos.

C - Estructura y propiedad

• Documentar quién cierra cada canal en el wiki del equipo o en un comentario de código. Un remitente cierra; los receptores nunca cierran las entradas compartidas.
• Usar pools de trabajadores para flujos constantes; errgroup para lotes de un solo uso. No mezclar metáforas sin límites claros.
• Propagar errores con errgroup o structs Result tipificados. No entrar en pánico desde goroutines de trabajadores.
• Preferir intercambios de configuración inmutables a través de atomic.Pointer. Los lectores cargan instantáneas; los escritores publican nuevas structs.
• Mantener las etapas del pipeline pequeñas y testeables. Alimentar canales cerrados en tests unitarios para cada etapa.

D - Apagado y ciclo de vida

• Implementar apagado HTTP elegante con tiempo de espera. Server.Shutdown y luego cancelar el contexto raíz.
• Cerrar los canales de trabajo solo después de que los productores terminen. Usar WaitGroup en los productores antes de cerrar.
• Esperar a los trabajadores antes de la salida del proceso. WaitGroup, Wait de errgroup, o Shutdown del pool en main.
• Conectar SIGTERM al mismo camino que el apagado intencional. Kubernetes espera un drenaje dentro de terminationGracePeriodSeconds.
• Verificar que el recuento de goroutines vuelve a la línea base en tests de integración. Detectar fugas antes de producción.

E - Observabilidad y verificación

• Ejecutar go test -race en paquetes concurrentes en CI. Bloquear la fusión en condiciones de carrera de datos.
• Exportar métricas de profundidad de colas y en curso. Alerta sobre crecimiento sostenido sin aumento de tráfico.
• Perfilar goroutines bajo carga en staging. Punto final de goroutines de pprof antes de lanzamientos importantes.
• Probar carga con latencia descendente realista. Mocks ilimitados ocultan errores de contrapresión.
• Registrar eventos de descarte y limitación de velocidad a nivel de información con contadores. Los operadores necesitan visibilidad al proteger las dependencias.

Preguntas frecuentes

Relacionado

• Concurrencia en Producción: Patrones Más Allá de Hello Goroutine - descripción general conceptual
• Conceptos Básicos de Concurrencia Avanzada - patrones ejecutables
• Evitar fugas de goroutines y deadlocks de canales - hoja de trucos para incidentes
• Prácticas Recomendadas de Fundamentos de Concurrencia - conceptos básicos de canales y mutex
• Prácticas Recomendadas del Paquete Context - hábitos de cancelación

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