Управление пакетами и библиотеками в Dart
Когда масштаб проекта растёт, крайне важно разделять код на несколько файлов и модулей.
В этой главе рассказывается о системе управления пакетами Dart pub, файле конфигурации зависимостей pubspec.yaml, синтаксисе import/export и о том, как создавать собственные библиотеки.
Конфигурация pubspec.yaml
pubspec.yaml — это основной файл конфигурации для каждого проекта Dart, в котором объявляются метаданные проекта и зависимости.
Типичная структура файла pubspec.yaml выглядит так:
Пример
name: my_dart_app # Имя проекта (обязательно, строчные буквы + подчёркивание)
description: Пример проекта на Dart# Описание проекта
version: 1.0.0 # Номер версии
# publish_to: none # Если вы не хотите публиковать в pub.dev, раскомментируйте эту строку
environment:
sdk: '>=3.0.0 <4.0.0' # Диапазон версий Dart SDK
dependencies:
# Сторонние пакеты, от которых проект зависит во время выполнения
http: ^1.1.0 # HTTP-клиент
path: ^1.8.0 # Утилиты для работы с путями
dev_dependencies:
# Зависимости, необходимые только во время разработки (тестирование, линтинг и т. д.)
test: ^1.24.0 # Фреймворк для тестирования
lints: ^2.0.0 # Официальные правила линтинга
# Необязательно: точка входа исполняемого файла
# исполняемые файлы:
# my_app: main
Объяснение синтаксиса номера версии:
| Синтаксис | Значение | Пример |
|---|---|---|
| ^1.1.0 | Совместимо с 1.1.0 до 2.0.0 (не включительно) | Наиболее часто используется, рекомендуется |
| 1.1.0 | Точная версия | Не очень гибкий |
| >=1.1.0 <1.5.0 | Диапазон версий | Используйте, когда требуется точный контроль |
| any | Любая версия | Не рекомендуется |
Символ каретки (^) — это способ задания ограничения версий по умолчанию в Dart. ^1.1.0 эквивалентно >=1.1.0 <2.0.0. Это означает, что минорные версии и патч-версии могут обновляться автоматически, но мажорные версии — нет (обновления мажорных версий могут включать обратно несовместимые изменения).
Установите зависимости
$ dart pub get # 安装依赖 $ dart pub upgrade # 升级依赖到最新兼容版本 $ dart pub outdated # 查看哪些依赖有更新
Поиск зависимостей на pub.dev
pub.dev — официальный репозиторий пакетов для Dart и Flutter, аналогичный npm (JavaScript) или PyPI (Python).
Вы можетеhttps://pub.devискать и просматривать десятки тысяч пакетов Dart.
Примеры распространённых сторонних пакетов:
| Название пакета | Назначение | Описание |
|---|---|---|
| http | HTTP-запрос | Официально поддерживаемый HTTP-клиент |
| path | Операции с путями | Кроссплатформенный инструмент обработки путей |
| test | Модульное тестирование | Официальный фреймворк для тестирования |
| json_serializable | Сериализация JSON | Автоматическая генерация кода преобразования JSON |
| dio | HTTP-клиент | Более мощная сторонняя HTTP-библиотека, чем http. |
| riverpod | Управление состоянием | Популярное решение для управления состоянием в проектах Flutter |
Пример
Добавьте пакет http и используйте его:
// http: ^1.1.0
// Затем выполните: dart pub get
import 'package:http/http.dart' as http;
void main() async {
// Отправьте GET-запрос
var url = Uri.parse('https://www.example.com');
var response = await http.get(url);
print('Status code: ${response.statusCode}');
print('Response body length: ${response.body.length} characters');
}
Синтаксис import
import используется для подключения кода из других библиотек в файл Dart.
Dart поддерживает несколько стилей import, каждый подходит для разных сценариев.
Импорт встроенных библиотек Dart
Пример
import 'dart:math'; // Библиотека математики (случайные числа, тригонометрические функции и т. д.)
import 'dart:convert'; // Библиотека преобразования кодировок (JSON, Base64 и т. д.)
import 'dart:io'; // Библиотека ввода-вывода (файлы, сеть и т. д.)
void main() {
// Использование функций из dart:math
print('Pi: $pi');
print('2 to the 10th power: ${pow(2, 10)}');
// Использование функций из dart:convert
var jsonStr = '{"name": "example", "age": 10}';
var decoded = jsonDecode(jsonStr);
print('Parsed JSON: $decoded');
print('Username: ${decoded['name']}');
}
圆周率: 3.141592653589793
2 的 10 次方: 1024
解析后的 JSON: {name: example, age: 10}
用户名: example
Импорт сторонних пакетов
Пример
import 'package:http/http.dart';
import 'package:path/path.dart' as p;
Импорт локальных файлов
Пример
import 'src/utils.dart'; // Подкаталог в том же каталоге
import '../models/user.dart'; // Файл в родительском каталоге
import 'constants.dart'; // Файл в том же каталоге
Модификаторы import
| Модификаторы | Синтаксис | Назначение |
|---|---|---|
| Префикс (as) | import 'lib.dart' as myLib; | Задайте библиотеке псевдоним, чтобы избежать конфликтов имен |
| Импортировать только часть (show) | import 'lib.dart' show foo, bar; | Импортировать только указанные имена |
| Исключить часть (hide) | import 'lib.dart' hide foo; | Импортировать всё, кроме указанных имен |
| Ленивая загрузка (deferred as) | import 'lib.dart' deferred as lib; | Загрузка по требованию для сокращения времени запуска |
Пример
Практическое использование различных модификаторов импорта:
import 'dart:math' as math; // Импорт с префиксом: используйте math.pow() вместо pow()
import 'dart:math' show pi, sqrt; // Импорт только pi и sqrt
import 'dart:math' hide Random; // Импорт всего, кроме Random
void main() {
// Стандартный импорт
print('sin(0) = ${sin(0)}');
// Импорт с префиксом: доступ осуществляется через префикс
print('cos(0) = ${math.cos(0)}');
// Импорт show: можно использовать только pi и sqrt
print('π = $pi');
print('sqrt(16) = ${sqrt(16)}');
// print(sin(0)); // Ошибка: sin не импортирован
// hide import: Random недоступен, всё остальное доступно
print('max(3, 7) = ${max(3, 7)}');
// Random(); // Ошибка: Random исключён
}
sin(0) = 0.0 cos(0) = 1.0 π = 3.141592653589793 sqrt(16) = 4.0 max(3, 7) = 7
show и hide — не просто для удобства: это ещё и инструменты для качества кода. Использование show делает зависимости яснее: сразу видно, какие символы из библиотеки использует этот файл.
синтаксис export
export используется, чтобы повторно предоставлять публичные API других библиотек, в основном для создания агрегирующих библиотек.
Предположим, у вас есть следующая структура файлов:
lib/ ├── my_package.dart # 入口文件(聚合导出) ├── src/ │ ├── models/ │ │ └── user.dart # User 类 │ ├── services/ │ │ └── api_service.dart # API 服务 │ └── utils/ │ └── helpers.dart # 工具函数
Пример
Использование export для создания точки входа агрегирующей библиотеки:
// Агрегированный экспорт: единообразно предоставляет все публичные API
export 'src/models/user.dart';
export 'src/services/api_service.dart';
// Экспортировать только часть содержимого в helpers
export 'src/utils/helpers.dart' show formatDate, validateEmail;
Таким образом, пользователям нужно импортировать только один файл:
Пример
import 'package:my_package/my_package.dart';
void main() {
// Можно напрямую использовать все экспортированные классы
var user = User('example');
var api = ApiService();
}
Создание пользовательских библиотек
Создание собственной библиотеки не требует специального синтаксиса — каждый файл Dart является библиотекой.
Однако можно использовать ключевое слово library, чтобы явно объявить имя библиотеки, и использовать part/part of для разделения больших библиотек.
Использование library для объявления имени библиотеки
Пример
// library объявляет имя библиотеки (необязательно, но полезно для документации)
library calculator;
/// Операция сложения
int add(int a, int b) => a + b;
/// Операция вычитания
int subtract(int a, int b) => a - b;
/// Умножение
int multiply(int a, int b) => a * b;
/// Операция деления, выбрасывает исключение, когда делитель равен 0
double divide(int a, int b) {
if (b == 0) {
throw ArgumentError(Делитель не может быть 0);
}
return a / b;
}
Используйте part для разделения больших библиотек
Когда код библиотеки слишком длинный, можно использовать part, чтобы разделить его на несколько физических файлов, но логически они всё ещё принадлежат одной и той же библиотеке.
Пример
Основной файл объявляет part:
// Основной файл библиотеки
library user_system;
// Объявите другие файлы, из которых состоит эта библиотека
part 'src/user_model.dart';
part 'src/user_service.dart';
part 'src/user_validator.dart';
// Публичный API уровня библиотеки
String libraryVersion = '1.0.0';
Пример
part-файл объявляет part of:
// part of объявляет, к какой библиотеке относится этот файл
part of '../user_system.dart';
// Можно получить доступ к libraryVersion в основной библиотеке
class User {
String name;
User(this.name);
void printVersion() {
print('EXAMPLE User module version: $libraryVersion');
}
}
part/part of обычно не используется в современной разработке на Dart; большинство команд предпочитают import/export для организации кода. Недостаток part в том, что файлы part совместно используют все приватные члены, нарушая инкапсуляцию. Если нет явной необходимости, рекомендуется import/export.
Обзор основной библиотеки Dart
| Имя библиотеки | Способ импорта | Основные возможности |
|---|---|---|
| dart:core | Автоматический импорт | Базовые типы, коллекции, исключения и т. д. |
| dart:math | import 'dart:math'; | Математические константы и функции |
| dart:convert | import 'dart:convert'; | Кодирование/декодирование JSON, UTF-8, Base64 |
| dart:io | import 'dart:io'; | Операции с файлами, сетью и процессами |
| dart:async | import 'dart:async'; | Асинхронные инструменты, такие как Future, Stream и т. д. |
| dart:collection | import 'dart:collection'; | Дополнительные типы коллекций (Queue и т. д.) |
| dart:developer | import 'dart:developer'; | Инструменты отладки и анализа производительности |
dart:core импортируется автоматически, поэтому не нужно писать import 'dart:core', чтобы использовать базовые типы, такие как int, String, List, Map и т. д.
Другие расширения