pub: əsas anlayışlar, Dart paket meneceri və pubspec.yaml

Pub nədir?

pub (Package Universal Browser) — Dart SDK ilə birlikdə gələn daxili paket meneceri. O, xarici kitabxanaları idarə edir, versiya münaqişələrini həll edir, tranzitiv asılılıqları yükləyir və paketləri lokal olaraq keşləyir. Flutter ekosistemində pub naviqasiya plaginləri, HTTP müştəriləri, state menecerləri və digər komponentləri qoşmaq üçün əsas vasitə kimi istifadə olunur.

Pub-un əsas funksiyaları: pub.dev reyestrindən asılılıqların quraşdırılması, lokal yollar (path-asılılıqları) və git-repozitoriyaları; semantik versiyalama qaydalarına uyğun versiyaların həlli; yüklənmiş paketlərin sistem kataloqunda keşlənməsi; öz paketlərinizin açıq reyestrdə nəşri. Bütün bu əməliyyatlar CLI əmri dart pub və ya ekvivalent flutter pub vasitəsilə əlçatandır.

Pub-un arxitekturası qapalı asılılıq qrafikinə əsaslanır: menecer hər bir paketin dəqiq bir dəfə mövcud olduğu ağac qurur. Əgər iki kitabxana eyni paketin müxtəlif versiyalarını tələb edərsə, pub uyğun diapazon tapmağa çalışır və ya münaqişə xətası bildirir. Bu, ağacın müxtəlif qovşaqlarında eyni paketin çoxsaylı versiyalarına icazə verən npm yanaşmasından fərqlənir.

pubspec.yaml strukturu

pubspec.yaml faylı — istənilən Dart və ya Flutter layihəsinin mərkəzi konfiqurasiya faylıdır. O, YAML formatında yazılır və metadata, asılılıqlar, qurma konfiqurasiyası və SDK məhdudiyyətlərini ehtiva edir. Aşağıda Flutter tətbiqi üçün tipik nümunə verilmişdir:

name: my_app
description: Flutter tətbiqi nümunəsi
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-in əsas sahələri: name — paketin unikal adı (yalnız latın hərfləri, alt xətt, rəqəmlər); description — qısa təsvir (nəşr üçün məcburi); version — artı işarəsindən sonra opsional qurma nömrəsi ilə semantik versiya; environment — Dart SDK və Flutter SDK-nın minimal versiyaları; dependencies — tətbiqin əsas asılılıqları; dev_dependencies — yalnız inkişaf və test üçün asılılıqlar; flutter — Flutter konfiqurasiya bölməsi (assets, fonts, plugins).

publish_to sahəsi nəşrin əlçatanlığını idarə edir: none dəyəri nəşri qadağan edir (tətbiqlər üçün tipik), standart dəyər — https://pub.dev. dependency_overrides sahəsi münaqişə vəziyyətində paket versiyasını məcburi şəkildə dəyişməyə imkan verir — ehtiyatla, yalnız müvəqqəti həll üçün istifadə edin.

Asılılıqlar və onların növləri

pub dörd növ asılılığı dəstəkləyir, hər biri pubspec.yaml daxilində öz sintaksisi ilə göstərilir:

Reyestr (hosted)

Standart tip — paket pub.dev və ya digər uyğun reyestrdən yüklənir. Paket adı və versiyası göstərilir. Nümunə: http: ^1.1.0 caret-versiyalama qaydalarına uyğun olaraq >=1.1.0 və <2.0.0 diapazonundan ən son uyğun versiyanı yükləyəcək.

SDK asılılıqları

Flutter SDK və ya Dart SDK-nı qoşmaq üçün istifadə olunur. Sintaksis: flutter: sdk: flutter. Paket reyestrdən deyil, Flutter SDK-nın lokal quraşdırmasından götürülür. SDK asılılıqları versiyalanmır — onların versiyası cari quraşdırılmış Flutter versiyası ilə müəyyən edilir.

Yol (path)

Paket ilə lokal kataloqu göstərir. Kitabxana hazırlayarkən və nəşr etmədən test edərkən faydalıdır. Sintaksis:

dependencies:
  my_local_lib:
    path: ../my_local_lib

Yol asılılıqları pubspec.lock-da qeyd olunmur — hər yeniləmə göstərilən yoldan yenidən həll edilir.

Git asılılıqları

Paketi birbaşa git-repozitoriyadan qoşmağa imkan verir. Budaqlar, teqlər və commitlər dəstəklənir:

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

Git asılılıqları fork-lar, dərc olunmamış düzəlişlər və ya Pull Request üzərində iş üçün əlverişlidir. Qurma zamanı gözlənilməz dəyişikliklərin qarşısını almaq üçün budaq əvəzinə konkret teq və ya commit göstərilməsi tövsiyə olunur.

Versiyalama və diapazonlar

pub Semantic Versioning 2.0-a ciddi şəkildə əməl edir: format MAJOR.MINOR.PATCH, burada MAJOR — uyğun olmayan dəyişikliklər, MINOR — geriyə uyğun əlavələr, PATCH — geriyə uyğun düzəlişlər. Bu sxem əsasında pub paketlərin uyğunluğunu müəyyən edir və münaqişələri həll edir.

Versiyaları təyin etmək üçün pubspec.yaml-də üç əsas operator istifadə olunur:

• Caret (^) — ^1.2.3 >=1.2.3 və <2.0.0-a ekvivalentdir. Ən geniş yayılmış operator, çünki əsas versiya daxilində uyğunluğu nəzərdə tutur. Əsas versiyası 0 (sıfır) olan paketlər üçün — ^0.1.2 >=0.1.2 və <0.2.0 deməkdir, bu, qeyri-sabit versiyalar üçün SemVer qaydalarına uyğundur.
• Tilde (~) — ~1.2.3 >=1.2.3 və <1.3.0-a ekvivalentdir. Kiçik versiyanı fiksasiya edir, yalnız patch yeniləmələrinə icazə verir. Daha az istifadə olunur, əsasən kiçik versiya səviyyəsində uyğunsuzluq məlum olduqda.
• Dəqiq diapazon — >=1.2.0 <2.0.0 — tam nəzarət verən açıq yazılış. Mürəkkəb məhdudiyyətlər üçün faydalıdır, məsələn, tranzitiv asılılıqların bir neçə versiyasından istifadə edərkən.

dart pub get yerinə yetirildikdən sonra pub bütün həll edilmiş paketlərin (birbaşa və tranzitiv) dəqiq versiyalarını müəyyən edən pubspec.lock faylı yaradır. Bu fayl bütün maşınlarda təkrarlana bilən qurmaları təmin etmək üçün versiyaya nəzarət sisteminə daxil edilməlidir. dart pub upgrade yerinə yetirildikdə lock-fayl müəyyən edilmiş məhdudiyyətlər çərçivəsində ən son uyğun versiyalara yenilənir.

dependency conflict xətası iki paket eyni asılılığın üst-üstə düşməyən diapazonlarını tələb etdikdə yaranır. pub hansı paketlərin münaqişəyə girdiyini və hansı səbəbdən olduğunu bildirir. Həll: münaqişə edən paketlərdən birini uyğun versiyaya yeniləmək, dependency_overrides istifadə etmək (müvəqqəti tədbir) və ya paketi alternativlə əvəz etmək.

Pub-un əsas əmrləri

Bütün pub əməliyyatları vahid CLI interfeysi vasitəsilə yerinə yetirilir. Dart SDK-da dart pub əmri, Flutter SDK-da — ekvivalent flutter pub (əlavə olaraq Flutter SDK asılılıqlarını və plaginləri nəzərə alır) istifadə olunur. Aşağıda əsas əmrlər verilmişdir:

• dart pub get — pubspec.yaml-də göstərilən bütün asılılıqları yükləyir, versiyaları həll edir və pubspec.lock yaradır/yeniləyir. Layihə ilk dəfə klonlanarkən və ya asılılıqlar dəyişdirildikdə icra olunur.
• dart pub upgrade — bütün asılılıqları pubspec.yaml məhdudiyyətləri çərçivəsində ən son versiyalara yeniləyir və pubspec.lock-u yenidən yazır. Tək paketi yeniləmək olar: dart pub upgrade http.
• dart pub add <package> — pubspec.yaml-ə yeni asılılıq əlavə edir və dərhal pub get icra edir. Nümunə: dart pub add dio dio paketinin ən son versiyasını əlavə edəcək.
• dart pub remove <package> — asılılığı pubspec.yaml-dən silir və qrafikin həllini yenidən başladır.
• dart pub cache repair — bütün keşlənmiş paketləri yenidən yükləyir. Lokal keşin zədələnməsi və ya yoxlama cəmi xətaları zamanı kömək edir.
• dart pub deps — asılılıq ağacını rahat mətn formatında göstərir. Tranzitiv asılılıqları təhlil etmək və təkrarlanmaları tapmaq üçün faydalıdır.
• dart pub publish — cari paketi pub.dev-də dərc edir. Nəşrdən əvvəl pubspec.yaml-in düzgünlüyünü, lisenziyanı və təsviri yoxlayır.
• dart pub outdated — cari, arzu olunan və ən son mövcud versiyanı göstərən köhnəlmiş asılılıqların siyahısını göstərir. npm outdated analoqu.

Bütün əmrlər həmçinin qısaldılmış formada mövcuddur: dart pub get — dart pub g kimi (bütün qısaltmalar deyil). Flutter layihələrində pub əmrlərindən əvvəl flutter prefiksi əlavə olunur: flutter pub get, flutter pub add və s. Flutter versiyası əlavə olaraq plaginlərin hədəf platforma ilə uyğunluğunu yoxlayır.

pub.dev-də nəşr

pub.dev — Dart və Flutter ekosisteminin mərkəzi paket reyestridir. 2025-ci ilin yanvarına olan məlumata görə, orada 50 000-dən çox paket dərc edilmiş, ümumilikdə 10 milyard dəfədən çox yüklənmişdir. Hər bir paketin təsvir, sənədləşmə, populyarlıq reytinqləri (Popularity), Pub Points balları və versiyaları olan səhifəsi var.

Pub Points — 0-dan 130-dək bal ilə paket keyfiyyətinin avtomatik qiymətləndirmə sistemi. Nəzərə alınır: lisenziyanın mövcudluğu, təsvir, nümunələr, Dart-ın son sabit versiyası ilə uyğunluq, zəifliklərin olmaması, testlərin əhatəsi, formatlamanın düzgünlüyü. Yüksək bal paketin axtarışda görünməsini və istifadəçi etibarını artırır.

Nəşr prosesi bir neçə addımı əhatə edir:

1. pubspec.yaml-i yoxlayın: name, description, version, license (SPDX identifikatoru göstərilməsi tövsiyə olunur, məs. MIT).
2. dart pub publish --dry-run icra edin — serverə göndərmədən nəşrin simulyasiyası, paketə daxil ediləcək bütün faylları və mümkün xətaları göstərir.
3. İlk nəşrdə Google hesabı ilə avtorizasiyadan keçin: dart pub publish brauzeri OAuth autentifikasiyası üçün açacaq.
4. Terminalda nəşri təsdiqləyin. Uğurlu göndərmədən sonra paket bir neçə dəqiqə ərzində pub.dev-də görünür.

Vacib qaydalar: yalnız unikal ada malik paketlər dərc edilə bilər; bir dəfə dərc edilmiş versiyanı silmək olmaz (yalnız gizlətmək olar — dart pub unpublish — 7 gün ərzində); böyük yeniləmələr üçün Semantic Versioning qaydalarına əməl edilməli, əsas versiyanı dəyişmədən ictimai API pozulmamalıdır.