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
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ón | Significado | Ejemplo |
|---|---|---|
| ^1.1.0 | Compatible con 1.1.0 hasta 2.0.0 (sin incluir) | La más utilizada, se recomienda |
| 1.1.0 | Versión exacta | Poco flexible |
| >=1.1.0 <1.5.0 | Rango de versiones | Se usa cuando se necesita un control preciso |
| any | Cualquier versión | No 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 paquete | Uso | Descripción |
|---|---|---|
| http | Solicitudes HTTP | Cliente HTTP mantenido oficialmente |
| path | Operaciones con rutas | Herramienta multiplataforma para manejo de rutas |
| test | Pruebas unitarias | Marco de pruebas oficial |
| json_serializable | Serialización JSON | Genera automáticamente código de conversión JSON |
| dio | Cliente HTTP | Biblioteca HTTP de terceros más potente que http |
| riverpod | Gestión de estado | Solución popular de gestión de estado para proyectos Flutter |
Ejemplo
Agregar el paquete http y usarlo:
// 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
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
import 'package:http/http.dart';
import 'package:path/path.dart' as p;
Importar archivos locales
Ejemplo
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
| Modificador | Sintaxis | Uso |
|---|---|---|
| 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' 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:
// 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
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
// 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 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:
// 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 biblioteca | Método de importación | Funciones principales |
|---|---|---|
| dart:core | Importación automática | Tipos básicos, colecciones, excepciones, etc. |
| dart:math | import 'dart:math'; | Constantes y funciones matemáticas |
| dart:convert | import 'dart:convert'; | Codificación/descodificación de JSON, UTF-8, Base64 |
| dart:io | import 'dart:io'; | Operaciones de archivos, red y procesos |
| dart:async | import 'dart:async'; | Herramientas asíncronas como Future, Stream, etc. |
| dart:collection | import 'dart:collection'; | Más tipos de colecciones (Queue, etc.) |
| dart:developer | import '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