Maneja errores con elegancia

En este capítulo, aprenderás a hacer que tu aplicación sea más robusta manejando errores de forma elegante. Explorarás excepciones, bloques try/catch y cómo crear excepciones personalizadas para gestionar errores de manera estructurada.

Antes de comenzar este capítulo, asegúrate de:

• Haber completado el Capítulo 5 y tener un entorno de desarrollo de Dart en funcionamiento con el proyecto dartpedia.
• Entender conceptos básicos de programación como funciones y clases.

Before you start writing code to handle failures, you need to understand the two main types of failures in Dart: errors and exceptions.

• Exceptions represent conditions that you might expect to happen and that your program can recover from. Examples include invalid user input, a missing file, or a network timeout. Your code can catch and handle exceptions to keep running.
• Errors represent failure conditions that indicate bugs in the code. Examples include calling a method on a null object, passing an invalid index to a list, or failing to initialize a late variable before use. You don't catch errors. Instead, you let them crash the application, which helps you find and fix the underlying bug.

In Dart, any non-null object can be thrown as an exception. However, by convention, exceptions implement Exception, while errors extend or implement Error. When you design an API, throw subtypes of Exception for conditions that callers can catch and handle.

En este capítulo, mejorarás la robustez de tu paquete command_runner implementando el manejo de errores. Crearás una clase de excepción personalizada y agregarás manejo de errores al CommandRunner para gestionar de forma elegante los errores que puedan ocurrir durante la ejecución del comando.

Primero, define una clase de excepción personalizada llamada ArgumentException para representar errores relacionados con los argumentos de línea de comandos.

1. Crea el archivo command_runner/lib/src/exceptions.dart. Este archivo contendrá la definición de tu clase ArgumentException.

2. Define una clase llamada ArgumentException que extienda (extends) de FormatException.

   command_runner/lib/src/exceptions.dart

   dart

   class ArgumentException extends FormatException {
     /// The command that was parsed before discovering the error.
     ///
     /// This will be empty if the error was on the root parser.
     final String? command;
   ​
     /// The name of the argument that was being parsed when the error was
     /// discovered.
     final String? argumentName;
   ​
     ArgumentException(
       super.message, [
       this.command,
       this.argumentName,
       super.source,
       super.offset,
     ]);
   ​
     @override
     String toString() {
       return 'ArgumentException: $message';
     }
   }
   

   content_copy

   Esta clase extiende de FormatException, que es una clase de excepción integrada en Dart. Incluye propiedades adicionales para almacenar el comando y el nombre del argumento asociados con el error. Esto proporciona más contexto al manejar la excepción.

   • command: El comando que se estaba procesando cuando ocurrió la excepción.
   • argumentName: El nombre del argumento que causó la excepción.

A continuación, actualiza la clase CommandRunner para manejar posibles errores con elegancia. Esto implica añadir un callback de manejo de errores, usar try/catch para gestionar excepciones y lanzar tu nueva ArgumentException cuando el usuario proporcione una entrada incorrecta.

1. Agrega los imports necesarios.

   En command_runner/lib/src/command_runner_base.dart, añade imports para dart:async (para usar FutureOr) y tu nuevo archivo exceptions.dart.

   dart

   import 'dart:async'; // Add this line
   import 'dart:collection';
   import 'dart:io';
   ​
   import 'arguments.dart';
   import 'exceptions.dart'; // Add this line
   

   content_copy

2. Añade un callback onError al CommandRunner.

   Modifica el CommandRunner para aceptar una función onError opcional en su constructor. Esto permitirá al usuario de tu paquete definir su propia lógica de manejo de errores.

   dart

   class CommandRunner {
     // Add a constructor that accepts the optional callback.
     CommandRunner({this.onError});
   ​
     final Map<String, Command> _commands = <String, Command>{};
   ​
     UnmodifiableSetView<Command> get commands =>
         UnmodifiableSetView<Command>(<Command>{..._commands.values});
   ​
     // Define the onError property.
     FutureOr<void> Function(Object)? onError;
   ​
     // The rest of the class implementation...
   }
   

   content_copy

   Este cambio introduce una propiedad onError que acepta nulos. El tipo FutureOr<void> Function(Object)? significa que es una función que toma un Object y devuelve un Future o nada (void), y podría ser null.

3. Actualiza el método run para usar try/catch.

   Envuelve la lógica dentro del método run en un bloque try/catch. Si ocurre una excepción, este bloque la "atrapará" y la pasará al callback onError o la volverá a lanzar (rethrow) si no se proporcionó ningún callback. rethrow conserva el error y la traza de pila (stack trace) originales.

   dart

   Future<void> run(List<String> input) async {
     // [Step 6 update] try/catch added
     try {
       final ArgResults results = parse(input);
       if (results.command != null) {
         Object? output = await results.command!.run(results);
         print(output.toString());
       }
     } on Exception catch (exception) {
       if (onError != null) {
         onError!(exception);
       } else {
         rethrow;
       }
     }
   }
   

   content_copy

4. Añade validación al método parse.

   Finalmente, reemplaza el método parse existente en command_runner_base.dart con la siguiente versión actualizada. Esta nueva versión es mucho más robusta. Está llena de comprobaciones que lanzarán tu ArgumentException personalizada cada vez que detecte una entrada de usuario no válida.

   dart

   // [Step 6 update] This method is replaced entirely.
   ArgResults parse(List<String> input) {
     ArgResults results = ArgResults();
     if (input.isEmpty) return results;
   ​
     // Throw an exception if the command is not recognized.
     if (_commands.containsKey(input.first)) {
       results.command = _commands[input.first];
       input = input.sublist(1);
     } else {
       throw ArgumentException(
         'The first word of input must be a command.',
         null,
         input.first,
       );
     }
   ​
     // Throw an exception if multiple commands are provided.
     if (results.command != null &&
         input.isNotEmpty &&
         _commands.containsKey(input.first)) {
       throw ArgumentException(
         'Input can only contain one command. Got ${input.first} and ${results.command!.name}',
         null,
         input.first,
       );
     }
   ​
     // Section: Handle options, including flags.
     Map<Option, Object?> inputOptions = {};
     int i = 0;
     while (i < input.length) {
       if (input[i].startsWith('-')) {
         var base = _removeDash(input[i]);
         // Throw an exception if an option is not recognized for the given command.
         var option = results.command!.options.firstWhere(
           (option) => option.name == base || option.abbr == base,
           orElse: () {
             throw ArgumentException(
               'Unknown option ${input[i]}',
               results.command!.name,
               input[i],
             );
           },
         );
   ​
         if (option.type == OptionType.flag) {
           inputOptions[option] = true;
           i++;
           continue;
         }
   ​
         if (option.type == OptionType.option) {
           // Throw an exception if an option requires an argument but none is given.
           if (i + 1 >= input.length) {
             throw ArgumentException(
               'Option ${option.name} requires an argument',
               results.command!.name,
               option.name,
             );
           }
           if (input[i + 1].startsWith('-')) {
             throw ArgumentException(
               'Option ${option.name} requires an argument, but got another option ${input[i + 1]}',
               results.command!.name,
               option.name,
             );
           }
           var arg = input[i + 1];
           inputOptions[option] = arg;
           i++;
         }
       } else {
         // Throw an exception if more than one positional argument is provided.
         if (results.commandArg != null && results.commandArg!.isNotEmpty) {
           throw ArgumentException(
             'Commands can only have up to one argument.',
             results.command!.name,
             input[i],
           );
         }
         results.commandArg = input[i];
       }
       i++;
     }
     results.options = inputOptions;
   ​
     return results;
   }
   ​
   String _removeDash(String input) {
     if (input.startsWith('--')) {
       return input.substring(2);
     }
     if (input.startsWith('-')) {
       return input.substring(1);
     }
     return input;
   }
   

   content_copy

   Este método parse actualizado ahora se defiende activamente contra las entradas incorrectas. Específicamente, las nuevas sentencias throw manejan varios casos de error comunes:

   • Comandos desconocidos: El primer bloque if/else asegura que el primer argumento sea un comando válido.
   • Múltiples comandos: Verifica que el usuario no haya intentado ejecutar más de un comando a la vez.
   • Opciones desconocidas: El parámetro orElse dentro de firstWhere ahora lanza una excepción si un usuario proporciona una bandera u opción (como --foo) que no ha sido definida para ese comando.
   • Valores de opción ausentes: Asegura que una opción (como --output) vaya seguida de un valor y no de otra opción o del final de la entrada.
   • Demasiados argumentos: Impone la regla de que los comandos solo pueden tener un argumento posicional.

Modifica cli/bin/cli.dart para usar el nuevo manejo de errores en CommandRunner.

1. Abre el archivo cli/bin/cli.dart.

2. Actualiza la función main para pasar una función onError al CommandRunner:

   cli/bin/cli.dart

   dart

   import 'package:command_runner/command_runner.dart';
   ​
   const version = '0.0.1';
   ​
   void main(List<String> arguments) {
     // [Step 6 update] Add onError method
     var commandRunner = CommandRunner(
       onError: (Object error) {
         if (error is Error) {
           throw error;
         }
         if (error is Exception) {
           print(error);
         }
       },
     )..addCommand(HelpCommand());
     commandRunner.run(arguments);
   }
   

   content_copy

   This code passes in an onError callback function to the CommandRunner constructor. If an error occurs during the execution of a command, the onError callback function is called with the error object. The callback checks whether the error is an Error or an Exception. Because an Error indicates a bug in the code, the callback rethrows it. This lets the application crash so you can fix the bug. For an Exception, which represents a recoverable failure, the callback handles it gracefully by printing it to the console instead of rethrowing it.

Haz que ArgumentException esté disponible para la librería command_runner.

1. Abre command_runner/lib/command_runner.dart y añade las siguientes exportaciones:

   command_runner/lib/command_runner.dart

   dart

   /// Support for doing something awesome.
   ///
   /// More dartdocs go here.
   library;
   ​
   export 'src/arguments.dart';
   export 'src/command_runner_base.dart';
   export 'src/help_command.dart';
   export 'src/exceptions.dart'; // Add this line
   ​
   // TODO: Export any libraries intended for clients of this package.
   

   content_copy

   Esto asegura que la ArgumentException esté disponible para los consumidores del paquete command_runner.

Prueba el nuevo manejo de errores ejecutando la aplicación con argumentos inválidos.

1. Abre tu terminal y navega al directorio cli.

2. Ejecuta el comando dart run bin/cli.dart invalid_command.

   Deberías ver la siguiente salida:

   bash

   ArgumentException: The first word of input must be a command.
   

   content_copy

   Esto confirma que la ArgumentException se está lanzando y capturando correctamente.

En la siguiente lección, aprenderás sobre características avanzadas orientadas a objetos en Dart, incluyendo enums mejorados y extensiones. Mejorarás el formato de salida y añadirás color a tu aplicación de CLI.