Patrones de diseno de manejo de errores con Claude Code

Mejorando el diseno de manejo de errores con Claude Code

Un manejo de errores adecuado impacta directamente en la robustez de la aplicacion. Con Claude Code, puede implementar eficientemente patrones de manejo de errores con seguridad de tipos y consistencia.

Diseno de clases de error personalizadas

> Disena clases de error personalizadas para usar en toda la aplicacion.
> Incluye correspondencia con codigos de estado HTTP, codigos de error
> y mensajes para el usuario.

// errors/base.ts
export abstract class AppError extends Error {
  abstract readonly statusCode: number;
  abstract readonly code: string;
  readonly isOperational: boolean;

  constructor(message: string, isOperational = true) {
    super(message);
    this.name = this.constructor.name;
    this.isOperational = isOperational;
    Error.captureStackTrace(this, this.constructor);
  }

  toJSON() {
    return {
      error: {
        code: this.code,
        message: this.message,
        ...(process.env.NODE_ENV === "development" && { stack: this.stack }),
      },
    };
  }
}

// errors/http.ts
export class NotFoundError extends AppError {
  readonly statusCode = 404;
  readonly code = "NOT_FOUND";

  constructor(resource: string, id?: string) {
    super(id ? `${resource}(${id}) no encontrado` : `${resource} no encontrado`);
  }
}

export class ValidationError extends AppError {
  readonly statusCode = 400;
  readonly code = "VALIDATION_ERROR";
  readonly fields: Record<string, string[]>;

  constructor(fields: Record<string, string[]>) {
    super("Hay errores de validacion");
    this.fields = fields;
  }

  toJSON() {
    return {
      error: {
        code: this.code,
        message: this.message,
        fields: this.fields,
      },
    };
  }
}

export class UnauthorizedError extends AppError {
  readonly statusCode = 401;
  readonly code = "UNAUTHORIZED";
  constructor(message = "Authentication required") {
    super(message);
  }
}

export class ForbiddenError extends AppError {
  readonly statusCode = 403;
  readonly code = "FORBIDDEN";
  constructor(message = "No tiene permisos") {
    super(message);
  }
}

Patron de tipo Result

Un patron de tipo Result que maneja errores de forma segura en tipos sin usar excepciones.

> Implementa el patron de tipo Result.
> Que se pueda distinguir exito y fallo a nivel de tipos.

// types/result.ts
type Result<T, E = Error> =
  | { success: true; data: T }
  | { success: false; error: E };

function ok<T>(data: T): Result<T, never> {
  return { success: true, data };
}

function err<E>(error: E): Result<never, E> {
  return { success: false, error };
}

// Ejemplo de uso
async function findUser(id: string): Promise<Result<User, NotFoundError>> {
  const user = await db.user.findUnique({ where: { id } });
  if (!user) {
    return err(new NotFoundError("User", id));
  }
  return ok(user);
}

// Lado de la llamada
const result = await findUser("123");
if (result.success) {
  console.log(result.data.name); // Acceso con seguridad de tipos
} else {
  console.log(result.error.message); // El tipo de error tambien es seguro
}

Manejador de errores global

Implementamos un manejador de errores global para Express.

> Crea un middleware de manejo de errores global para Express.
> Convierte AppError en respuestas apropiadas, errores inesperados en 500.
> En produccion, ocultar el stack trace.

import { Request, Response, NextFunction } from "express";
import { AppError } from "../errors/base";

export function globalErrorHandler(
  err: Error,
  req: Request,
  res: Response,
  _next: NextFunction
) {
  // Salida de log
  if (err instanceof AppError && err.isOperational) {
    console.warn(`[${err.code}] ${err.message}`);
  } else {
    console.error("Unexpected error:", err);
  }

  // Si es AppError, devolver la respuesta definida
  if (err instanceof AppError) {
    return res.status(err.statusCode).json(err.toJSON());
  }

  // Error inesperado
  res.status(500).json({
    error: {
      code: "INTERNAL_ERROR",
      message: process.env.NODE_ENV === "production"
        ? "Ha ocurrido un error del servidor"
        : err.message,
    },
  });
}

Captura de errores asincronos

> Crea un wrapper que capture automaticamente los errores
> de los async route handlers de Express.

import { Request, Response, NextFunction, RequestHandler } from "express";

function asyncHandler(
  fn: (req: Request, res: Response, next: NextFunction) => Promise<void>
): RequestHandler {
  return (req, res, next) => {
    fn(req, res, next).catch(next);
  };
}

// Ejemplo de uso: ya no se necesita try-catch
router.get("/users/:id", asyncHandler(async (req, res) => {
  const user = await userService.findById(req.params.id);
  if (!user) {
    throw new NotFoundError("User", req.params.id);
  }
  res.json({ data: user });
}));

Error Boundary en el frontend

> Crea un React Error Boundary.
> Que muestre diferentes UIs segun el tipo de error.

import { Component, ReactNode } from "react";

interface Props {
  children: ReactNode;
  fallback?: (error: Error, retry: () => void) => ReactNode;
}

interface State {
  error: Error | null;
}

class ErrorBoundary extends Component<Props, State> {
  state: State = { error: null };

  static getDerivedStateFromError(error: Error) {
    return { error };
  }

  handleRetry = () => {
    this.setState({ error: null });
  };

  render() {
    if (this.state.error) {
      if (this.props.fallback) {
        return this.props.fallback(this.state.error, this.handleRetry);
      }
      return (
        <div className="p-8 text-center">
          <h2 className="text-xl font-bold text-red-600">Ha ocurrido un error</h2>
          <p className="mt-2 text-gray-600">{this.state.error.message}</p>
          <button
            onClick={this.handleRetry}
            className="mt-4 rounded bg-blue-500 px-4 py-2 text-white"
          >
            Reintentar
          </button>
        </div>
      );
    }
    return this.props.children;
  }
}

Para metodos concretos de depuracion e investigacion de errores, consulte la guia completa de tecnicas de depuracion. Para el diseno de tipos con TypeScript, consulte Tecnicas de uso de TypeScript. Para el manejo de informacion de errores desde la perspectiva de seguridad, consulte tambien Automatizacion de auditorias de seguridad.

Resumen

Un diseno de manejo de errores consistente mejora significativamente la robustez y mantenibilidad de la aplicacion. Con Claude Code, puede implementar eficientemente clases de error personalizadas, tipo Result y manejadores globales.

Para las mejores practicas de manejo de errores, consulte la guia oficial de Node.js. Para Claude Code, consulte la documentacion oficial de Anthropic.