Mejores Prácticas de Resiliencia

Documenta la seguridad de reintentos por endpoint en OpenAPI. Estas reglas mantienen los servicios Node.js disponibles cuando las dependencias se ralentizan o fallan.

Cómo Usar Esta Lista

• Aplícala a cada nueva integración saliente y ruta HTTP.
• Combínala con pruebas de carga que simulen una latencia de 503 en el sistema descendente.
• Agrega las extensiones OpenAPI x-retry-safe y x-idempotency por operación.
• Revísala durante los post-mortem de incidentes cuando los reintentos amplificaron las interrupciones.

A - Tiempos de Espera y Plazos

• Cada fetch y llamada de cliente HTTP usa AbortSignal.timeout. Sin esperas infinitas.
• statement_timeout de la base de datos o tiempo de espera de consulta del controlador configurado. Terminación del lado del servidor para SQL descontrolado.
• Tiempo de espera de salida < plazo del manejador < requestTimeout del servidor < inactividad del balanceador de carga. Presupuesto escalonado.
• Tiempo de espera de adquisición de conexión en pools. Registra métricas de espera del pool.
• Los trabajos de BullMQ tienen la opción timeout. Los workers no se ejecutan sin límites.

B - Reintentos e Idempotencia

• Reintentar solo errores 5xx y de red, no 4xx. Clasifica entre reintentables y fatales.
• Retroceso exponencial con fluctuación entre intentos. Máximo 3-5 intentos en rutas síncronas.
• Idempotency-Key en POST que crea cargos u órdenes. Documenta en OpenAPI.
• Almacena el mapeo de clave de idempotencia -> respuesta por más de 24 horas para pagos. Devuelve la caché en caso de duplicado.
• Deja de reintentar cuando el circuito está abierto. Falla rápidamente localmente.

C - Disyuntores y Degradación

• opossum (o equivalente) por dependencia descendente. Disyuntores separados por servicio.
• Mecanismo de reserva solo en características de nivel 1/2. Nunca simules pagos o autenticación exitosos.
• Devuelve meta.degraded en las respuestas de la API al eliminar características. El cliente puede ajustar la interfaz de usuario.
• Banderas de características para deshabilitar rutas opcionales durante incidentes. FEATURE_X=off sin volver a desplegar.
• Alerta sobre eventos de circuito open. Paginación cuando se abre el disyuntor de una dependencia central.

D - Salud y Ciclo de Vida

• La prueba de vida es barata; la prueba de preparación verifica la base de datos y las dependencias críticas. Sin comprobaciones lentas en la prueba de vida.
• SIGTERM elegante: server.close, vaciar pools, sdk.shutdown(). Coincide con el período de gracia de k8s.
• Falla la preparación durante las migraciones si es necesario. El tráfico se desplaza a los pods antiguos.
• El backlog de la cola se monitorea como un indicador principal. Alerta de profundidad antes de los tiempos de espera del worker.
• Caos o inyección de fallas en staging trimestralmente. Valida que las rutas de degradación funcionen.

E - Documentación y Contratos

• OpenAPI documenta la idempotencia y la seguridad de reintentos por operación. Los consumidores conocen las reglas de reintento seguras.
• Runbook por dependencia: tiempo de espera, umbrales de disyuntor, comportamiento de reserva. Preparado para el equipo de guardia.
• Clasifica las dependencias en niveles 0/1/2 en el README del servicio. Aclara la política de degradación.
• El SLI incluye la tasa de tiempo de espera de las dependencias. No solo los 5xx de tu servicio.
• La revisión posterior al incidente pregunta "¿los reintentos amplificaron el problema?" Ajusta los límites del disyuntor y los reintentos.

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Resiliencia - ejemplos introductorios
• Tiempos de Espera en Todas Partes - matriz de tiempos de espera
• Reintentos con Retroceso - patrones de idempotencia
• OpenAPI y Swagger - documenta las extensiones de reintento

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS Activo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, y NestJS 11.