6.2Resolución rápida de problemas
Lo esencial en 30 segundos
- Reflejo : un síntoma = causas probables = una acción dirigida — se diagnostica antes de reiniciar.
- Bucle : un servidor que se congela o falla señala casi siempre al asíncrono o a los errores no gestionados.
- Producción : toda diferencia entre local y producción se trata con contenedor, variables de entorno y logs.
Hilo Salim — el playbook pegado junto a la pantalla
Salim guarda este playbook junto a su pantalla. Veredicto tras un año : tres líneas fueron las más útiles — el undefined de un resultado aún no listo, el servidor que se congela con varios usuarios, y el secreto que casi se va a Git. Para cada una, acabó aplicando la secuencia (verificar, corregir la causa, probar) en vez de reiniciar al azar.
Síntoma observado, causas verificadas, acciones en orden : el reflejo se resume en tres tiempos.
Diagnosticar antes de reiniciar
Un problema Node rara vez se resuelve al azar : cada síntoma tiene causas típicas y una acción dirigida. La tabla siguiente agrupa las situaciones más frecuentes, del asíncrono al despliegue.
| Síntoma | Causas probables | Acciones |
|---|---|---|
| Obtengo undefined en vez de mi resultado | código asíncrono mal gestionado : el resultado aún no está listo en la línea siguiente | usar await (función async) o .then() ; pensar « cuando esté listo » ; rodear con try/catch (1.2) |
| UnhandledPromiseRejection / el servidor falla | promesa rechazada no gestionada ; sin gestión centralizada de errores | rodear await con try/catch ; middleware centralizado de errores (err, req, res, next) ; gestionar el evento 'error' (4.4) |
| El servidor « se congela » con varios usuarios | operación síncrona (fs.*Sync) o cálculo CPU pesado que bloquea el bucle de eventos | pasar a asíncrono (fs.promises) ; delegar la CPU a los worker threads ; nunca bloquear el bucle (2.1/5.2) |
| Cannot find module / error de import | ruta incorrecta, node_modules ausente, confusión CommonJS / ESM | npm install ; verificar ./ para lo local frente a nombre para npm ; coherencia require frente a import ('type':'module') (1.3) |
| req.body es undefined en Express | middleware de parseo ausente o colocado después de las rutas | añadir app.use(express.json()) ANTES de las rutas ; verificar el Content-Type (3.1) |
| Duplicados o datos incoherentes en base | sin restricción ni validación ; sin búsqueda antes de crear | esquema validado (required, unique) ; buscar luego crear/actualizar ; relacionar en vez de duplicar (3.3) |
| Fallo potencial : inyección / datos no fiables | concatenación de entradas en una consulta ; entradas no validadas | consultas parametrizadas u ORM ; validar las entradas (Zod/Joi) ; nunca confiar en el cliente (3.4/4.2) |
| Mi API es lenta bajo carga | consultas no optimizadas (N+1, sin índice) ; sin caché ; un solo núcleo usado | perfilar ANTES de tocar ; indexar y optimizar las consultas ; caché (Redis) ; clustering (PM2) (5.2) |
| « Funciona en mi máquina » pero no en producción | entorno distinto (versión Node, dependencias, configuración) | contenerizar (Docker) ; config por variables de entorno ; verificar las versiones (5.3) |
| Un secreto se filtró (clave/API en el código o Git) | secreto en claro en el código o versionado | regenerar inmediatamente la clave ; mover a variable de entorno (.env ignorado por Git) ; nunca versionar .env (1.4/4.2) |
Guion listo para decir — diagnosticar sin reiniciar al azar (30 s)
« Mi síntoma : [undefined / fallo / congelación / body vacío / lentitud / diferencia prod]. Consulto los logs, identifico la causa probable del playbook, aplico la acción dirigida y verifico. »
Modelo copiar-pegar — ficha avería exprés
// Ficha avería : await + try/catch + middleware de errores
async function chargerTache(id) {
try {
const tache = await trouverTache(id);
return tache;
} catch (erreur) {
throw new Error("Lectura imposible");
}
}
function gestionErreurs(err, req, res, next) {
console.error(err.message);
res.status(500).json({ error: "Error interno" });
}
module.exports = { chargerTache, gestionErreurs };Pyme muy pequeña / bajo presupuesto
Sin tabla formal : un síntoma, la causa probable del playbook, la acción y el responsable anotado.
Pyme Argelia
Integrar las realidades locales en el diagnóstico : versiones instaladas, puestos compartidos, picos de actividad conocidos.
Remoto / híbrido
Añadir los logs escritos inmediatos a las acciones : a distancia, un síntoma no consignado parece un sistema que funciona.
Intercultural
Explicitar las constataciones por escrito : lo que parece evidente (qué versión, qué entorno) no lo es para todos.
Reto 48h — aplica mañana
Detecta 1 síntoma actual (undefined, congelación, body vacío, lentitud), rellena la ficha avería exprés y prueba la 1.ª acción (logs + corrección dirigida).
- Sé relacionar un síntoma con sus causas probables.
- Rellené (o planifiqué) una ficha avería exprés.
- Conozco el reenvío hacia el nivel a profundizar para mi caso.
El servidor de Salim se congela en cuanto varios usuarios se conectan. ¿Qué reflejo aplica el playbook ?
Un mismo síntoma que vuelve no son diez averías : es un reflejo que falta por anclar (await + try/catch, nunca Sync en servidor, parseo antes de las rutas, validación, .env).