Gestión de paquetes y bibliotecas de Dart

Cuando el tamaño del proyecto crece, dividir el código en múltiples archivos y módulos es esencial.

Este capítulo presenta el sistema de gestión de paquetes de Dart, `pub`, el archivo de configuración de dependencias `pubspec.yaml`, la sintaxis de `import`/`export` y cómo crear bibliotecas personalizadas.


Configuración de pubspec.yaml

`pubspec.yaml` es el archivo de configuración central de cada proyecto Dart; declara los metadatos y las dependencias del proyecto.

La estructura típica de un archivo `pubspec.yaml` es la siguiente:

Ejemplo

# Ruta del archivo: pubspec.yaml
name
: my_dart_app              # Nombre del proyecto (obligatorio, minúsculas + guion bajo)
description
: Un proyecto de ejemplo en Dart# Descripción del proyecto
version
: 1.0.0                 # Número de versión
# publish_to: none # Si no deseas publicar en pub.dev, descomenta esta línea

environment
:
  sdk
: '>=3.0.0 <4.0.0'      # Rango de versiones del SDK de Dart

dependencies
:
 # Paquetes de terceros de los que depende el proyecto en tiempo de ejecución
  http
: ^1.1.0                # Cliente HTTP
  path
: ^1.8.0                # Herramienta de rutas

dev_dependencies
:
 # Dependencias necesarias solo durante el desarrollo (pruebas, análisis de código, etc.)
  test
: ^1.24.0               # Marco de pruebas
  lints
: ^2.0.0               # Reglas oficiales de lint

# Opcional: punto de entrada del ejecutable
# executables:
#   my_app: main

Explicación de las notaciones de versión:

NotaciónSignificadoEjemplo
^1.1.0Compatible con 1.1.0 hasta 2.0.0 (sin incluir)La más utilizada, se recomienda
1.1.0Versión exactaPoco flexible
>=1.1.0 <1.5.0Rango de versionesSe usa cuando se necesita un control preciso
anyCualquier versiónNo recomendado

El símbolo `^` (caret) es la forma predeterminada de restricción de versiones en Dart. `^1.1.0` equivale a `>=1.1.0 <2.0.0`. Esto significa que se pueden actualizar automáticamente las versiones menores y los parches, pero no la versión principal (las actualizaciones de la versión principal pueden contener cambios disruptivos).

Instalación de dependencias

$ dart pub get           # 安装依赖
$ dart pub upgrade       # 升级依赖到最新兼容版本
$ dart pub outdated      # 查看哪些依赖有更新

Buscar dependencias en pub.dev

`pub.dev` es el repositorio oficial de paquetes para Dart y Flutter, similar a npm (JavaScript) o PyPI (Python).

Puedeshttps://pub.devbuscar y explorar decenas de miles de paquetes Dart en pub.dev.

Ejemplos de paquetes de terceros de uso común:

Nombre del paqueteUsoDescripción
httpSolicitudes HTTPCliente HTTP mantenido oficialmente
pathOperaciones con rutasHerramienta multiplataforma para manejo de rutas
testPruebas unitariasMarco de pruebas oficial
json_serializableSerialización JSONGenera automáticamente código de conversión JSON
dioCliente HTTPBiblioteca HTTP de terceros más potente que http
riverpodGestión de estadoSolución popular de gestión de estado para proyectos Flutter

Ejemplo

Agregar el paquete http y usarlo:

// Primero agrega en dependencies de pubspec.yaml:
//   http: ^1.1.0
// Luego ejecuta: dart pub get

import 'package:http/http.dart' as http;

void main() async {
  // Envía una solicitud GET
  var url = Uri.parse('https://www.example.com');
  var response = await http.get(url);

  print('Código de estado: ${response.statusCode}');
  print('Longitud del cuerpo de la respuesta: ${response.body.length} caracteres');
}

Sintaxis de importación (import)

`import` se utiliza para introducir código de otras bibliotecas en un archivo Dart.

Dart admite varias formas de importación, cada una adecuada para diferentes escenarios.

Importar bibliotecas integradas de Dart

Ejemplo

// El prefijo dart: indica las bibliotecas centrales integradas de Dart
import 'dart:math';    // Biblioteca matemática (números aleatorios, funciones trigonométricas, etc.)
import 'dart:convert'; // Biblioteca de conversión de codificación (JSON, Base64, etc.)
import 'dart:io';      // Biblioteca de E/S (archivos, red, etc.)

void main() {
  // Usar funciones de dart:math
  print('Número pi: $pi');
  print('2 elevado a 10: ${pow(2, 10)}');

  // Usar funciones de dart:convert
  var jsonStr = '{"name": "ejemplo", "age": 10}';
  var decoded = jsonDecode(jsonStr);
  print('JSON analizado: $decoded');
  print('Nombre de usuario: ${decoded['name']}');
}
圆周率: 3.141592653589793
2 的 10 次方: 1024
解析后的 JSON: {name: ejemplo, age: 10}
用户名: ejemplo

Importar paquetes de terceros

Ejemplo

// El prefijo package: indica paquetes de terceros en pub.dev
import 'package:http/http.dart';
import 'package:path/path.dart' as p;

Importar archivos locales

Ejemplo

// Importación por ruta relativa: importa otros archivos Dart del mismo proyecto
import 'src/utils.dart';          // Subdirectorio del mismo directorio
import '../models/user.dart';    // Archivo en el directorio padre
import 'constants.dart';         // Archivo en el mismo directorio

Modificadores de import

ModificadorSintaxisUso
Prefijo (as)import 'lib.dart' as myLib;Poner un alias a la biblioteca para evitar conflictos de nombres
Importar solo parte (show)import 'lib.dart' show foo, bar;Importar solo los nombres especificados
Excluir parte (hide)import 'lib.dart' hide foo;Importar todo excepto los nombres especificados
Carga diferida (deferred as)import 'lib.dart' deferred as lib;Carga bajo demanda, reduce el tiempo de inicio

Ejemplo

Uso práctico de varios modificadores de importación:

import 'dart:math';              // Importación estándar
import 'dart:math' as math;      // Importación con prefijo: usa math.pow() en lugar de pow()
import 'dart:math' show pi, sqrt;  // Importar solo pi y sqrt
import 'dart:math' hide Random;    // Importar todo excepto Random

void main() {
  // Importación estándar
  print('sin(0) = ${sin(0)}');

  // Importación con prefijo: se debe acceder a través del prefijo
  print('cos(0) = ${math.cos(0)}');

  // Importación con show: solo se pueden usar pi y sqrt
  print('π = $pi');
  print('sqrt(16) = ${sqrt(16)}');
  // print(sin(0)); // Error: sin no ha sido importado

  // Importación con hide: Random no está disponible, todo lo demás sí
  print('max(3, 7) = ${max(3, 7)}');
  // Random(); // Error: Random ha sido excluido
}
sin(0) = 0.0
cos(0) = 1.0
π = 3.141592653589793
sqrt(16) = 4.0
max(3, 7) = 7

`show` y `hide` no son solo por conveniencia; también son herramientas de calidad de código. Usar `show` hace que las dependencias sean más claras: de un vistazo puedes ver qué símbolos de la biblioteca usa este archivo.


Sintaxis de exportación (export)

`export` se utiliza para reexponer la API pública de otras bibliotecas, principalmente para crear bibliotecas de agregación.

Supongamos que tienes la siguiente estructura de archivos:

lib/
├── my_package.dart          # 入口文件(聚合导出)
├── src/
│   ├── models/
│   │   └── user.dart        # User 类
│   ├── services/
│   │   └── api_service.dart # API 服务
│   └── utils/
│       └── helpers.dart     # 工具函数

Ejemplo

Usar `export` para crear el punto de entrada de una biblioteca de agregación:

// Archivo: lib/my_package.dart
// Exportación agregada: expone uniformemente toda la API pública

export 'src/models/user.dart';
export 'src/services/api_service.dart';
// Exportar solo parte del contenido de helpers
export 'src/utils/helpers.dart' show formatDate, validateEmail;

De esta manera, el usuario solo necesita importar un archivo:

Ejemplo

// El usuario solo necesita importar el archivo de entrada
import 'package:my_package/my_package.dart';

void main() {
  // Se pueden usar directamente todas las clases exportadas
  var user = User('ejemplo');
  var api = ApiService();
}

Creación de bibliotecas personalizadas

Crear una biblioteca personalizada no requiere una sintaxis especial: cada archivo Dart es una biblioteca.

Pero puedes usar la palabra clave `library` para declarar explícitamente el nombre de la biblioteca, y usar `part`/`part of` para dividir bibliotecas grandes.

Usar `library` para declarar el nombre de la biblioteca

Ejemplo

// Archivo: lib/calculator.dart
// library declara el nombre de la biblioteca (opcional, pero útil para la documentación)
library calculator;

/// Operación de suma
int add(int a, int b) => a + b;

/// Operación de resta
int subtract(int a, int b) => a - b;

/// Operación de multiplicación
int multiply(int a, int b) => a * b;

/// Operación de división, lanza una excepción si el divisor es 0
double divide(int a, int b) {
  if (b == 0) {
    throw ArgumentError('El divisor no puede ser 0');
  }
  return a / b;
}

Usar `part` para dividir bibliotecas grandes

Cuando el código de una biblioteca es demasiado largo, se puede usar part para dividirlo en múltiples archivos físicos, pero lógicamente siguen perteneciendo a la misma biblioteca.

Ejemplo

El archivo principal declara part:

// Archivo: lib/user_system.dart
// Archivo principal de la biblioteca
library user_system;

// Declara otros archivos que componen esta biblioteca
part 'src/user_model.dart';
part 'src/user_service.dart';
part 'src/user_validator.dart';

// API pública a nivel de biblioteca
String libraryVersion = '1.0.0';

Ejemplo

El archivo part declara part of:

// Archivo: lib/src/user_model.dart
// part of declara a qué biblioteca pertenece
part of '../user_system.dart';

// Puede acceder a libraryVersion de la biblioteca principal
class User {
  String name;
  User(this.name);

  void printVersion() {
    print('Versión del módulo EJEMPLO User: $libraryVersion');
  }
}

part/part of no se usa comúnmente en el desarrollo moderno de Dart; la mayoría de los equipos prefieren usar import/export para organizar el código. La desventaja de part es que todos los miembros privados se comparten entre los archivos part, rompiendo la encapsulación. A menos que haya una necesidad clara, se recomienda usar import/export.


Descripción general de la biblioteca principal de Dart

Nombre de la bibliotecaMétodo de importaciónFunciones principales
dart:coreImportación automáticaTipos básicos, colecciones, excepciones, etc.
dart:mathimport 'dart:math';Constantes y funciones matemáticas
dart:convertimport 'dart:convert';Codificación/descodificación de JSON, UTF-8, Base64
dart:ioimport 'dart:io';Operaciones de archivos, red y procesos
dart:asyncimport 'dart:async';Herramientas asíncronas como Future, Stream, etc.
dart:collectionimport 'dart:collection';Más tipos de colecciones (Queue, etc.)
dart:developerimport 'dart:developer';Herramientas de depuración y análisis de rendimiento

dart:core se importa automáticamente; no necesitas escribir import 'dart:core' para usar tipos básicos como int, String, List, Map.

Otras extensiones