Управление пакетами и библиотеками в Dart

Когда масштаб проекта растёт, крайне важно разделять код на несколько файлов и модулей.

В этой главе рассказывается о системе управления пакетами Dart pub, файле конфигурации зависимостей pubspec.yaml, синтаксисе import/export и о том, как создавать собственные библиотеки.


Конфигурация pubspec.yaml

pubspec.yaml — это основной файл конфигурации для каждого проекта Dart, в котором объявляются метаданные проекта и зависимости.

Типичная структура файла pubspec.yaml выглядит так:

Пример

# Путь к файлу: 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.

Примеры распространённых сторонних пакетов:

Название пакетаНазначениеОписание
httpHTTP-запросОфициально поддерживаемый HTTP-клиент
pathОперации с путямиКроссплатформенный инструмент обработки путей
testМодульное тестированиеОфициальный фреймворк для тестирования
json_serializableСериализация JSONАвтоматическая генерация кода преобразования JSON
dioHTTP-клиентБолее мощная сторонняя HTTP-библиотека, чем http.
riverpodУправление состояниемПопулярное решение для управления состоянием в проектах Flutter

Пример

Добавьте пакет http и используйте его:

// Сначала добавьте в dependencies в pubspec.yaml:
// 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

Пример

// Префикс dart: указывает на встроенные основные библиотеки 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

Импорт сторонних пакетов

Пример

// Префикс package: указывает на сторонние пакеты на pub.dev
import 'package:http/http.dart';
import 'package:path/path.dart' as p;

Импорт локальных файлов

Пример

// Импорт по относительному пути: импорт других файлов Dart в том же проекте
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';              // Стандартный импорт
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 для создания точки входа агрегирующей библиотеки:

// Файл: lib/my_package.dart
// Агрегированный экспорт: единообразно предоставляет все публичные 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 для объявления имени библиотеки

Пример

// Файл: lib/calculator.dart
// 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:

// Файл: lib/user_system.dart
// Основной файл библиотеки
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:

// Файл: lib/src/user_model.dart
// 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:mathimport 'dart:math';Математические константы и функции
dart:convertimport 'dart:convert';Кодирование/декодирование JSON, UTF-8, Base64
dart:ioimport 'dart:io';Операции с файлами, сетью и процессами
dart:asyncimport 'dart:async';Асинхронные инструменты, такие как Future, Stream и т. д.
dart:collectionimport 'dart:collection';Дополнительные типы коллекций (Queue и т. д.)
dart:developerimport 'dart:developer';Инструменты отладки и анализа производительности

dart:core импортируется автоматически, поэтому не нужно писать import 'dart:core', чтобы использовать базовые типы, такие как int, String, List, Map и т. д.

Другие расширения