Manejo de excepciones en Dart

Una excepción es un evento de error que ocurre durante la ejecución del programa.

Un buen manejo de excepciones permite que el programa degrade con elegancia ante errores, en lugar de estrellarse directamente.

Este capítulo presenta try/catch/finally en Dart, throw para lanzar excepciones, on para capturar tipos específicos y rethrow para relanzar.


Fundamentos de try / catch / finally

En el bloque try se coloca el código que puede lanzar excepciones; el bloque catch captura y maneja la excepción; el bloque finally se ejecuta haya o no excepción.

Ejemplo

void main() {
  // try-catch básico
  try {
    int result = 10 ~/ 0;  // La división por cero lanzará una excepción.
    print('Resultado: $result');  // Esta línea no se ejecutará.
  } catch (e) {
    // e es el objeto de excepción.
    print('Excepción capturada: $e');
  }

  // Obtener la excepción y la información de la pila.
  try {
    List<int> numbers = [1, 2, 3];
    print(numbers[10]);  // Acceder a un índice fuera de rango.
  } catch (e, stackTrace) {
    // e es la excepción, stackTrace es la pila de llamadas.
    print('Excepción de EJEMPLO: $e');
    print('Información de la pila:\n$stackTrace');
  }

  // finally: se ejecuta haya o no excepción.
  try {
    print('Intentando ejecutar la operación...');
    int result = 5 ~/ 0;
    print('Esta línea no se ejecutará: $result');
  } catch (e) {
    print('Error: $e');
  } finally {
    // El código en el bloque finally siempre se ejecuta, a menudo se usa para limpiar recursos.
    print('Limpieza de recursos completada (finally siempre se ejecuta)');
  }
}
捕获到异常: IntegerDivisionByZeroException
EJEMPLO 异常: RangeError (index): Invalid value: Not in inclusive range 0..2: 10
堆栈信息:
#0      List.[] (dart:core-patch/growable_array.dart:264)
#1      main (file:///...)
...
尝试执行操作...
出错: IntegerDivisionByZeroException
清理资源完成(finally 总是执行)

El bloque finally es más adecuado para la limpieza de recursos, como cerrar archivos, liberar conexiones de base de datos, etc. Incluso si hay una declaración return en try o catch, finally se ejecutará de todos modos.


throw: lanzar excepciones

Se puede lanzar una excepción activamente usando la palabra clave throw.

Dart permite lanzar cualquier objeto como excepción (no solo subclases de Exception), pero la mejor práctica es lanzar subclases de Exception o Error.

Ejemplo

// Clase de excepción personalizada.
class InvalidAgeException implements Exception {
  final int age;
  final String message;

  InvalidAgeException(this.age)
      : message = 'Edad inválida: $age (la edad debe estar entre 0 y 150)';

  @override
  String toString() => 'InvalidAgeException: $message';
}

// Función que usa una excepción personalizada.
void validateAge(int age) {
  if (age < 0) {
    throw InvalidAgeException(age);
  }
  if (age > 150) {
    throw InvalidAgeException(age);
  }
  print('Edad $age validada correctamente.');
}

// Lanzar una excepción integrada.
int divide(int a, int b) {
  if (b == 0) {
    throw ArgumentError('El divisor no puede ser 0');  // Usar una excepción integrada.
  }
  return a ~/ b;
}

void main() {
  // Probar la excepción personalizada.
  try {
    validateAge(-5);
  } catch (e) {
    print(e);
  }

  try {
    validateAge(200);
  } catch (e) {
    print(e);
  }

  validateAge(25);  // Caso normal.

  // Probar el lanzamiento de una excepción integrada.
  try {
    divide(10, 0);
  } catch (e) {
    print('EJEMPLO Error: $e');
  }
}
InvalidAgeException: 无效的年龄: -5(年龄必须在 0 到 150 之间)
InvalidAgeException: 无效的年龄: 200(年龄必须在 0 到 150 之间)
年龄 25 验证通过
EJEMPLO 错误: Invalid argument(s): 除数不能为 0

Diferencia entre Exception y Error: Exception es un error predecible que el programa puede manejar (como tiempo de espera de red, archivo inexistente); Error es impredecible y generalmente representa un bug del programa (como error de tipo, puntero nulo). Tu código debe capturar Exception, no Error.


on: capturar tipos específicos

La palabra clave on permite capturar por tipo de excepción, haciendo el manejo de errores más preciso.

Ejemplo

void main() {
  // Capturar diferentes excepciones por tipo
  try {
    // Simular diferentes tipos de excepciones
    int result = performOperation('divide_by_zero');
    print('Resultado: $result');
  } on IntegerDivisionByZeroException {
    // Capturar solo la excepción de división por cero
    print('EJEMPLO Error: no se puede dividir por cero');
  } on FormatException catch (e) {
    // Capturar la excepción de formato y obtener la información de la excepción
    print('EJEMPLO Error de formato: ${e.message}');
  } on RangeError {
    // Capturar solo la excepción de rango
    print('EJEMPLO Error: índice fuera de límites');
  } catch (e) {
    // Fallback: capturar todas las demás excepciones
    print('Error desconocido: $e');
  } finally {
    print('Operación finalizada\n');
  }

  // Ejemplo de coincidencia en orden
  print('--- Probando diferentes operaciones ---');
  for (var op in ['divide_by_zero', 'parse_error', 'out_of_range', 'normal']) {
    try {
      performOperation(op);
    } on IntegerDivisionByZeroException {
      print('$op -> excepción de división por cero');
    } on FormatException {
      print('$op -> excepción de formato');
    } on RangeError {
      print('$op -> excepción de rango');
    } catch (e) {
      print('$op -> otra excepción: $e');
    }
  }
}

int performOperation(String operation) {
  switch (operation) {
    case 'divide_by_zero':
      return 10 ~/ 0;  // Lanzar IntegerDivisionByZeroException
    case 'parse_error':
      int.parse('not_a_number');  // Lanzar FormatException
      return 0;
    case 'out_of_range':
      var list = [1, 2, 3];
      return list[100];  // Lanzar RangeError
    case 'normal':
      return 42;
    default:
      throw Exception('Operación desconocida');
  }
}
EJEMPLO 错误: 不能除以零
操作结束

--- 测试不同的操作 ---
divide_by_zero -> 除零异常
parse_error -> 格式异常
out_of_range -> 范围异常

El orden de on y catch es muy importante: Dart coincide los tipos de excepción de arriba hacia abajo. Los tipos de excepción más específicos deben ir primero, y los más genéricos después. Si pones catch (e) al principio, los on siguientes nunca se ejecutarán.


rethrow: relanzar

A veces necesitas hacer algo después de capturar la excepción (como registrar un log) y luego dejar que la excepción continúe propagándose hacia arriba.

La palabra clave rethrow se usa para volver a lanzar la excepción capturada actual, conservando la información de la pila original.

Ejemplo

// Simular un escenario de llamadas en varias capas
void databaseOperation() {
  print(' Conectando a la base de datos...');
  throw Exception('EJEMPLO Fallo de conexión a la base de datos');
}

void serviceLayer() {
  try {
    print(' Capa de servicio: llamando a la operación de base de datos');
    databaseOperation();
  } catch (e) {
    // Registrar primero el log y luego relanzar la excepción
    print(' [Log] Excepción en la operación de base de datos: $e');
    rethrow;  // Conservar la excepción original y la pila, continuar propagando hacia arriba
  }
}

void controllerLayer() {
  try {
    print('Capa del controlador: procesando la solicitud');
    serviceLayer();
  } catch (e, stackTrace) {
    // La capa más externa captura y procesa
    print('La capa del controlador capturó la excepción');
    print('Mensaje de error: $e');
    print('Devolver al usuario: "El servicio no está disponible temporalmente, por favor inténtelo más tarde"');
  }
}

void main() {
  controllerLayer();
  print('\n--- Diferencia entre rethrow y throw e ---);

  // Demostrar la diferencia entre rethrow y throw e
  try {
    try {
      throw FormatException('Excepción original');
    } catch (e) {
      // throw e: restablece la información de la pila y pierde la ubicación original de la llamada
      print('Usando throw e (se pierde la pila original)...');
      throw e;  // La pila comienza aquí
    }
  } catch (e, stack) {
    print('Capturado: $e');
    print('La pila apunta aquí (no a la ubicación original):\n$stack');
  }
}
控制器层: 处理请求
  服务层: 调用数据库操作
  正在连接数据库...
  [日志] 数据库操作异常: Exception: EJEMPLO 数据库连接失败
控制器层捕获到异常
错误信息: Exception: EJEMPLO 数据库连接失败
给用户返回: "服务暂时不可用,请稍后重试"

--- rethrow vs throw e 的区别 ---
使用 throw e(丢失原始堆栈)...
捕获: FormatException: 原始异常
堆栈指向这里(不是原始位置):
...

La diferencia entre rethrow y throw e es clave: rethrow conserva toda la información de la pila de la excepción original, lo que facilita localizar la causa raíz; throw e restablece la pila y comienza desde la posición actual. Cuando necesites continuar propagando la excepción después de registrar el log, usa rethrow.


Mejores prácticas para el manejo de excepciones

PrácticaDescripción
Solo captura excepciones que puedas manejarNo captures todas las excepciones a ciegas solo para "evitar errores". Si no sabes cómo manejarla, déjala propagarse hacia arriba.
Captura por tipoUsa on para especificar el tipo de excepción, evita usar un solo catch que se trague todas las excepciones.
Usa finally para limpiar recursosCierra archivos, conexiones de red y otros recursos en finally.
No te tragues las excepcionesCapturar una excepción y no hacer nada (bloque catch vacío) es peligroso; al menos registra un log.
Usa rethrowCuando necesites continuar propagando la excepción después de registrar el log, usa rethrow en lugar de throw e.
El mensaje de excepción debe ser específicothrow Exception('Error de conexión a la base de datos: 192.168.1.1:3306') es más útil que throw Exception('se produjo un error')
Otras extensiones