pub: mga pangunahing konsepto, tagapamahala ng package ng Dart at pubspec.yaml

Ano ang pub?

pub (Package Universal Browser) — nakapaloob na tagapamahala ng package na kasama ng Dart SDK. Pinamamahalaan nito ang mga panlabas na library, nilulutas ang mga conflict ng bersyon, dina-download ang mga transitive dependency, at nagki-cache ng mga package nang lokal. Sa Flutter ecosystem, ang pub ay ginagamit bilang pangunahing kasangkapan para sa pagkonekta ng mga plugin sa navigation, HTTP client, state manager at iba pang mga component.

Ang mga pangunahing function ng pub ay kinabibilangan ng: pag-install ng mga dependency mula sa pub.dev registry, mga lokal na path (path dependency) at mga git repository; pagresolba ng mga bersyon ayon sa mga tuntunin ng semantic versioning; pag-cache ng mga na-download na package sa system directory; pag-publish ng sariling mga package sa bukas na registry. Lahat ng operasyong ito ay available sa pamamagitan ng CLI command na dart pub o katumbas na flutter pub.

Ang arkitektura ng pub ay batay sa isang saradong graph ng dependency: ang tagapamahala ay bumubuo ng isang puno kung saan ang bawat package ay lilitaw nang eksaktong isang beses. Kung ang dalawang library ay nangangailangan ng magkaibang bersyon ng parehong package, susubukan ng pub na maghanap ng katugmang saklaw o mag-uulat ng error sa conflict. Ito ay naiiba sa approach ng npm, kung saan pinapayagan ang maramihang bersyon ng parehong package sa iba't ibang node ng puno.

Istraktura ng pubspec.yaml

Ang file na pubspec.yaml — ang sentral na configuration file ng anumang Dart o Flutter na proyekto. Ito ay nakasulat sa YAML format at naglalaman ng metadata, dependencies, configuration ng build at mga limitasyon ng SDK. Nasa ibaba ang isang tipikal na halimbawa para sa isang Flutter application:

name: my_app
description: Halimbawa ng Flutter app
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/

Mga pangunahing field ng pubspec.yaml: name — natatanging pangalan ng package (Latin lamang, underscore, numero); description — maikling paglalarawan (kinakailangan para sa pag-publish); version — semantic na bersyon na may opsyonal na build number pagkatapos ng plus sign; environment — pinakamababang bersyon ng Dart SDK at Flutter SDK; dependencies — mga pangunahing dependency ng application; dev_dependencies — mga dependency para sa pag-develop at pag-test lamang; flutter — seksyon ng configuration ng Flutter (assets, fonts, plugins).

Ang field na publish_to ay kumokontrol sa availability ng pag-publish: ang value na none ay nagbabawal sa pag-publish (tipikal para sa mga application), ang default na value ay https://pub.dev. Ang field na dependency_overrides ay nagpapahintulot na pilit na i-override ang bersyon ng isang package sa sitwasyon ng conflict — gamitin nang may pag-iingat, pansamantala lamang.

Mga dependency at mga uri nito

Ang pub ay sumusuporta sa apat na uri ng dependency, bawat isa ay tinutukoy gamit ang sariling syntax sa loob ng pubspec.yaml:

Registry (hosted)

Karaniwang uri — ang package ay dina-download mula sa registry na pub.dev o ibang katugmang registry. Ang pangalan ng package at bersyon ay tinutukoy. Halimbawa: http: ^1.1.0 ay dadaan-download ng pinakabagong katugmang bersyon mula sa saklaw na >=1.1.0 at <2.0.0 ayon sa mga tuntunin ng caret versioning.

Mga dependency ng SDK

Ginagamit para sa pagkonekta ng Flutter SDK o Dart SDK. Syntax: flutter: sdk: flutter. Ang package ay kinukuha mula sa lokal na pag-install ng Flutter SDK, hindi mula sa registry. Ang mga dependency ng SDK ay hindi nbe-version — ang kanilang bersyon ay tinutukoy ng kasalukuyang naka-install na bersyon ng Flutter.

Path (landas)

Tumutukoy sa isang lokal na direktoryo na may package. Kapaki-pakinabang sa pag-develop ng library at pag-test nang walang pag-publish. Syntax:

dependencies:
  my_local_lib:
    path: ../my_local_lib

Ang mga path dependency ay hindi naitala sa pubspec.lock — ang bawat update ay nire-resolba muli mula sa tinukoy na landas.

Mga dependency ng Git

Nagbibigay-daan na kumonekta ng package nang direkta mula sa isang git repository. Ang mga branch, tag at commit ay sinusuportahan:

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

Ang mga dependency ng Git ay maginhawa para sa mga fork, hindi nai-publish na pag-aayos o trabaho sa Pull Request. Inirerekomenda na tukuyin ang isang partikular na tag o commit sa halip na branch, upang maiwasan ang hindi inaasahang pagbabago sa build.

Versioning at mga saklaw

Ang pub ay mahigpit na sumusunod sa Semantic Versioning 2.0: ang format na MAJOR.MINOR.PATCH, kung saan MAJOR — mga hindi katugmang pagbabago, MINOR — mga pagdaragdag na katugma pabalik, PATCH — mga pag-aayos na katugma pabalik. Batay sa iskema na ito, tinutukoy ng pub ang compatibility ng mga package at nilulutas ang mga conflict.

Para sa pagtukoy ng mga bersyon, tatlong pangunahing operator ang ginagamit sa pubspec.yaml:

• Caret (^) — ^1.2.3 ay katumbas ng >=1.2.3 at <2.0.0. Ang pinakakaraniwang operator, dahil ipinapalagay nito ang compatibility sa loob ng major na bersyon. Para sa mga package na may major version na 0 (sero) — ^0.1.2 ay nangangahulugang >=0.1.2 at <0.2.0, na tumutugma sa mga tuntunin ng SemVer para sa hindi matatag na mga bersyon.
• Tilde (~) — ~1.2.3 ay katumbas ng >=1.2.3 at <1.3.0. Inaayos ang minor na bersyon, pinapayagan lamang ang mga patch update. Mas madalas ginagamit, pangunahin kapag alam ang hindi pagkakatugma sa antas ng minor.
• Eksaktong saklaw — >=1.2.0 <2.0.0 — tahasang notasyon na nagbibigay ng buong kontrol. Kapaki-pakinabang para sa mga kumplikadong limitasyon, halimbawa kapag gumagamit ng maraming bersyon ng transitive dependency.

Pagkatapos isagawa ang dart pub get, ang pub ay bubuo ng file na pubspec.lock na nagtatakda ng eksaktong bersyon ng lahat ng naresolbang package (direkta at transitive). Ang file na ito ay dapat isama sa version control system upang matiyak ang reproducible na build sa lahat ng makina. Kapag isinasagawa ang dart pub upgrade, ang lock file ay ina-update sa pinakabagong katugmang mga bersyon sa loob ng mga itinakdang limitasyon.

Ang error na dependency conflict ay nangyayari kapag ang dalawang package ay nangangailangan ng hindi nag-o-overlap na mga saklaw ng parehong dependency. Ang pub ay nag-uulat kung aling mga package ang nagka-conflict at sa anong dahilan. Solusyon: i-update ang isa sa mga nagkakasalungatang package sa isang katugmang bersyon, gamitin ang dependency_overrides (pansamantalang hakbang) o palitan ang package ng alternatibo.

Mga pangunahing utos ng pub

Lahat ng operasyon ng pub ay isinasagawa sa pamamagitan ng pinag-isang CLI interface. Sa Dart SDK ginagamit ang utos na dart pub, sa Flutter SDK — ang katumbas na flutter pub (isinasaalang-alang din ang mga dependency ng Flutter SDK at plugin). Nasa ibaba ang mga pangunahing utos:

• dart pub get — dina-download ang lahat ng dependency na tinukoy sa pubspec.yaml, nire-resolba ang mga bersyon at ginagawa/in-a-update ang pubspec.lock. Isinasagawa sa unang pag-clone ng proyekto o pagkatapos baguhin ang mga dependency.
• dart pub upgrade — ina-update ang lahat ng dependency sa pinakabagong mga bersyon sa loob ng mga limitasyon ng pubspec.yaml at ino-overwrite ang pubspec.lock. Maaaring mag-update ng isang package: dart pub upgrade http.
• dart pub add <package> — nagdaragdag ng bagong dependency sa pubspec.yaml at agad na isinasagawa ang pub get. Halimbawa: dart pub add dio ay magdaragdag ng pinakabagong bersyon ng package na dio.
• dart pub remove <package> — nag-aalis ng dependency mula sa pubspec.yaml at muling sinisimulan ang pagresolba ng graph.
• dart pub cache repair — muling nilo-load ang lahat ng naka-cache na package. Tumutulong sa pagkasira ng lokal na cache o mga error sa checksum.
• dart pub deps — nagpapakita ng dependency tree sa nababasang text format. Kapaki-pakinabang para sa pagsusuri ng transitive dependency at paghahanap ng mga duplicate.
• dart pub publish — nag-publish ng kasalukuyang package sa pub.dev. Bago mag-publish, sinusuri ang kawastuhan ng pubspec.yaml, lisensya at paglalarawan.
• dart pub outdated — nagpapakita ng listahan ng mga lumang dependency na may kasalukuyan, ninanais at pinakabagong available na bersyon. Kahalintulad ng npm outdated.

Lahat ng utos ay available din sa pinaikling anyo: dart pub get bilang dart pub g (hindi lahat ng pagpapaikli). Sa mga proyekto ng Flutter, ang prefix na flutter ay idinaragdag sa mga utos ng pub: flutter pub get, flutter pub add at iba pa. Ang bersyon ng Flutter ay karagdagang sinusuri ang compatibility ng mga plugin sa target na platform.

Pag-publish sa pub.dev

pub.dev — ang sentral na registry ng package ng ecosystem ng Dart at Flutter. Noong Enero 2025, mahigit 50,000 package ang nai-publish doon, na may kabuuang pag-download na mahigit 10 bilyong beses. Ang bawat package ay may pahina na may paglalarawan, dokumentasyon, mga rating ng kasikatan (Popularity), mga puntos ng Pub Points at mga bersyon.

Pub Points — isang awtomatikong sistema ng pagsusuri ng kalidad ng package mula 0 hanggang 130 puntos. Isinasaalang-alang: pagkakaroon ng lisensya, paglalarawan, mga halimbawa, compatibility sa pinakabagong stable na bersyon ng Dart, kawalan ng mga vulnerability, saklaw ng test, kawastuhan ng formatting. Ang mataas na marka ay nagpapataas ng visibility ng package sa paghahanap at tiwala ng mga user.

Ang proseso ng pag-publish ay may ilang hakbang:

1. Suriin ang pubspec.yaml: pagkakaroon ng name, description, version, license (inirerekomenda na tukuyin ang SPDX identifier, hal. MIT).
2. Isagawa ang dart pub publish --dry-run — simulation ng pag-publish nang hindi ipinapadala sa server, ipinapakita ang lahat ng file na isasama sa package at mga posibleng error.
Mag-authorize sa pamamagitan ng Google account sa unang pag-publish: dart pub publish ay magbubukas ng browser para sa OAuth authentication.
3. Kumpirmahin ang pag-publish sa terminal. Pagkatapos ng matagumpay na pagpapadala, lilitaw ang package sa pub.dev sa loob ng ilang minuto.

Mahahalagang tuntunin: tanging mga package na may natatanging pangalan ang maaaring i-publish; ang isang beses nang nai-publish na bersyon ay hindi maaaring tanggalin (maaari lamang itago — dart pub unpublish — sa loob ng 7 araw); para sa malalaking update, dapat sundin ang mga tuntunin ng Semantic Versioning, huwag sirain ang public API nang hindi binabago ang major na bersyon.