pub: ключови понятия, мениджър на пакети Dart и pubspec.yaml

Какво е pub?

pub (Package Universal Browser) — вграден мениджър на пакети, който се доставя с Dart SDK. Той управлява външни библиотеки, разрешава конфликти на версии, изтегля транзитивни зависимости и кешира пакети локално. В екосистемата Flutter, pub се използва като основен инструмент за свързване на плъгини за навигация, HTTP клиенти, мениджъри на състояние и други компоненти.

Основните функции на pub включват: инсталиране на зависимости от регистъра pub.dev, локални пътища (path зависимости) и git хранилища; разрешаване на версии според правилата на семантичното версиониране; кеширане на изтеглени пакети в системната директория; публикуване на собствени пакети в отворения регистър. Всички тези операции са достъпни чрез CLI командата dart pub или еквивалентната flutter pub.

Архитектурата на pub се основава на затворен граф на зависимости: мениджърът изгражда дърво, в което всеки пакет се появява точно веднъж. Ако две библиотеки изискват различни версии на един и същ пакет, pub се опитва да намери съвместим диапазон или съобщава за грешка при конфликт. Това се различава от подхода на npm, където се допускат множество версии на един и същ пакет в различни възли на дървото.

Структура на pubspec.yaml

Файлът pubspec.yaml — централният конфигурационен файл на всеки Dart или Flutter проект. Написан е във формат YAML и съдържа метаданни, зависимости, конфигурация на изграждане и ограничения на SDK. По-долу е даден типичен пример за Flutter приложение:

name: my_app
description: Пример Flutter-приложения
version: 1.0.0+1
publish_to: none

environment:
  sdk: ">=3.0.0 <4.0.0"
  flutter: ">=3.10.0"

dependencies:
  flutter:
    sdk: flutter
  http: ^1.1.0
  provider: ^6.0.5
  shared_preferences: ^2.2.0
  path_provider: ^2.1.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^3.0.0
  mockito: ^5.4.3

flutter:
  uses-material-design: true
  assets:
    - assets/images/
    - assets/fonts/

Ключови полета на pubspec.yaml: name — уникално име на пакета (само латиница, долна черта, цифри); description — кратко описание (задължително за публикуване); version — семантична версия с опционален build номер след плюс; environment — минимални версии на Dart SDK и Flutter SDK; dependencies — основните зависимости на приложението; dev_dependencies — зависимости само за разработка и тестване; flutter — секция за конфигурация на Flutter (assets, fonts, plugins).

Полето publish_to контролира достъпността на публикуване: стойността none забранява публикуването (типично за приложения), стойността по подразбиране — https://pub.dev. Полето dependency_overrides позволява принудително преопределяне на версията на пакет в конфликтна ситуация — използвайте внимателно, само за временно решение.

Зависимости и техните видове

pub поддържа четири вида зависимости, всеки от които се посочва със собствен синтаксис в pubspec.yaml:

Регистрови (hosted)

Стандартен тип — пакетът се изтегля от регистъра pub.dev или друг съвместим регистър. Посочват се име на пакета и версия. Пример: http: ^1.1.0 ще изтегли последната съвместима версия от диапазона >=1.1.0 и <2.0.0 според правилата на caret версиониране.

SDK зависимости

Използват се за свързване на Flutter SDK или Dart SDK. Синтаксис: flutter: sdk: flutter. Пакетът се взема от локалната инсталация на Flutter SDK, а не от регистъра. SDK зависимостите не се версионират — тяхната версия се определя от текущо инсталираната версия на Flutter.

Пътеви (path)

Сочат към локална директория с пакет. Полезни при разработка на библиотека и тестване без публикуване. Синтаксис:

dependencies:
  my_local_lib:
    path: ../my_local_lib

Пътевите зависимости не се фиксират в pubspec.lock — всяка актуализация се разрешава отново от посочения път.

Git зависимости

Позволяват свързване на пакет директно от git хранилище. Поддържат се клонове, тагове и комити:

dependencies:
  my_git_lib:
    git:
      url: https://github.com/user/my_git_lib.git
      ref: main

Git зависимостите са удобни за форкове, непубликувани корекции или работа по Pull Request. Препоръчва се да се посочва конкретен таг или комит вместо клон, за да се избегнат неочаквани промени при изграждане.

Версиониране и диапазони

pub стриктно следва Semantic Versioning 2.0: формат MAJOR.MINOR.PATCH, където MAJOR — несъвместими промени, MINOR — обратно съвместими добавки, PATCH — обратно съвместими корекции. Въз основа на тази схема pub определя съвместимостта на пакетите и разрешава конфликти.

За задаване на версии се използват три основни оператора в pubspec.yaml:

• Caret (^) — ^1.2.3 е еквивалентно на >=1.2.3 и <2.0.0. Най-разпространеният оператор, тъй като предполага съвместимост в рамките на основната версия. За пакети с основна версия 0 (нула) — ^0.1.2 означава >=0.1.2 и <0.2.0, което съответства на правилата на SemVer за нестабилни версии.
• Tilde (~) — ~1.2.3 е еквивалентно на >=1.2.3 и <1.3.0. Фиксира второстепенната версия, позволявайки само patch актуализации. Използва се по-рядко, основно когато е известна несъвместимост на ниво второстепенна версия.
• Точен диапазон — >=1.2.0 <2.0.0 — изричен запис, даващ пълен контрол. Полезен за сложни ограничения, например при използване на множество версии на транзитивни зависимости.

След изпълнение на dart pub get, pub генерира файла pubspec.lock, който фиксира точните версии на всички разрешени пакети (директни и транзитивни). Този файл трябва да бъде включен в системата за контрол на версиите, за да се осигурят възпроизводими изграждания на всички машини. При изпълнение на dart pub upgrade, lock файлът се актуализира до най-новите съвместими версии в рамките на зададените ограничения.

Грешката dependency conflict възниква, когато два пакета изискват неприпокриващи се диапазони на една и съща зависимост. pub съобщава кои пакети са влезли в конфликт и по каква причина. Решение: актуализирайте единия от конфликтните пакети до съвместима версия, използвайте dependency_overrides (временна мярка) или заменете пакета с алтернатива.

Основни команди на pub

Всички операции на pub се изпълняват чрез унифициран CLI интерфейс. В Dart SDK се използва командата dart pub, във Flutter SDK — еквивалентната flutter pub (допълнително взема предвид Flutter SDK зависимости и плъгини). По-долу са основните команди:

• dart pub get — изтегля всички зависимости, посочени в pubspec.yaml, разрешава версии и създава/актуализира pubspec.lock. Изпълнява се при първото клониране на проекта или след промяна на зависимости.
• dart pub upgrade — актуализира всички зависимости до най-новите версии в рамките на ограниченията на pubspec.yaml и презаписва pubspec.lock. Може да актуализира отделен пакет: dart pub upgrade http.
• dart pub add <package> — добавя нова зависимост в pubspec.yaml и веднага изпълнява pub get. Пример: dart pub add dio ще добави последната версия на пакета dio.
• dart pub remove <package> — премахва зависимост от pubspec.yaml и рестартира разрешаването на графа.
• dart pub cache repair — презарежда всички кеширани пакети. Помага при повреда на локалния кеш или грешки на контролна сума.
• dart pub deps — показва дървото на зависимостите в четим текстов формат. Полезно за анализ на транзитивни зависимости и намиране на дублирания.
• dart pub publish — публикува текущия пакет на pub.dev. Преди публикуване проверява коректността на pubspec.yaml, лиценза и описанието.
• dart pub outdated — показва списък на остарели зависимости с текуща, желана и последна налична версия. Аналог на npm outdated.

Всички команди са достъпни и в съкратена форма: dart pub get като dart pub g (не всички съкращения). В Flutter проекти пред командите на pub се добавя префиксът flutter: flutter pub get, flutter pub add и така нататък. Flutter версията допълнително проверява съвместимостта на плъгините с целевата платформа.

Публикуване на pub.dev

pub.dev — централният регистър на пакети на екосистемата Dart и Flutter. Към януари 2025 г. там са публикувани над 50 000 пакета, общо изтеглени над 10 милиарда пъти. Всеки пакет има страница с описание, документация, оценки на популярност (Popularity), точки Pub Points и версии.

Pub Points — автоматична система за оценка на качеството на пакета от 0 до 130 точки. Вземат се предвид: наличие на лиценз, описание, примери, съвместимост с последната стабилна версия на Dart, липса на уязвимости, покритие на тестове, коректност на форматирането. Високият резултат повишава видимостта на пакета в търсенето и доверието на потребителите.

Процесът на публикуване включва няколко стъпки:

1. Проверете pubspec.yaml: наличие на name, description, version, license (препоръчва се посочване на SPDX идентификатор, напр. MIT).
2. Изпълнете dart pub publish --dry-run — симулация на публикуване без изпращане до сървъра, показва всички файлове, които ще бъдат включени в пакета, и възможни грешки.
3. Авторизирайте се чрез Google акаунт при първото публикуване: dart pub publish ще отвори браузър за OAuth удостоверяване.
4. Потвърдете публикуването в терминала. След успешно изпращане, пакетът се появява на pub.dev в рамките на няколко минути.

Важни правила: могат да се публикуват само пакети с уникално име; веднъж публикувана версия не може да бъде изтрита (може само да бъде скрита — dart pub unpublish — в рамките на 7 дни); за големи актуализации трябва да се следват правилата на Semantic Versioning, да не се нарушава публичния API без промяна на основната версия.