pub: المفاهيم الأساسية، مدير حزم Dart و pubspec.yaml

ما هو pub؟

pub (Package Universal Browser) — مدير حزم مدمج يأتي مع Dart SDK. يدير المكتبات الخارجية، ويحل تعارضات الإصدارات، ويحمل التبعيات المتعدية، ويخزن الحزم مؤقتاً محلياً. في نظام Flutter البيئي، يُستخدم pub كأداة رئيسية لتوصيل إضافات التنقل، عملاء HTTP، مديري الحالة ومكونات أخرى.

الوظائف الأساسية لـ pub تشمل: تثبيت التبعيات من سجل pub.dev، المسارات المحلية (تبعيات المسار) و مستودعات 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 — إصدار دلالي مع رقم بناء اختياري بعد علامة الزائد؛ environment — إصدارات الحد الأدنى لـ Dart SDK و Flutter SDK؛ dependencies — التبعيات الرئيسية للتطبيق؛ dev_dependencies — تبعيات التطوير والاختبار فقط؛ flutter — قسم تكوين Flutter (الأصول، الخطوط، الإضافات).

حقل 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 versioning.

تبعيات 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 Requests. يُوصى بتحديد وسم أو التزام معين بدلاً من فرع لتجنب التغييرات غير المتوقعة أثناء البناء.

الإصدارات والنطاقات

يتبع 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، تُسبق الأوامر بـ flutter: flutter pub get، flutter pub add وهكذا. إصدار Flutter يتحقق بالإضافة إلى ذلك من توافق الإضافات مع النظام الأساسي المستهدف.

النشر على pub.dev

pub.dev — سجل الحزم المركزي لنظام Dart و Flutter البيئي. اعتباراً من يناير 2025، تم نشر أكثر من 50,000 حزمة هناك، بإجمالي تحميلات يتجاوز 10 مليارات. كل حزمة لها صفحة مع وصف وتوثيق ودرجات شعبية ونقاط 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 العامة دون تغيير الإصدار الرئيسي.