أدوات البناء والوحدات

أفضل ممارسات إدارة التبعيات

15 دقيقة الدرس 9 من 13

أفضل ممارسات إدارة التبعيات

إضافة تبعية إلى ملف البناء أمر يستغرق ثوانٍ. أما فهم ما تجلبه معها — والحفاظ على بناء يمكن التنبؤ به بعد ستة أشهر — فهو يتطلّب انضباطًا متعمّدًا. يتناول هذا الدرس ثلاثة ركائز يجب على كل فريق Java محترف إتقانها: تشخيص تعارضات الإصدارات وحلّها، وإتقان استخدام قائمة المواد (BOM) لمركزة إدارة الإصدارات، وترسيخ عادات تضمن بنيات قابلة للإعادة.

المشكلة: تعارضات الإصدارات

تنشأ تعارضات الإصدارات حين تتطلّب تبعيتان أو أكثر على مسار الكلاسات (classpath) إصدارات مختلفة من المكتبة نفسها. لا تُحمِّل JVM إلا إصدارًا واحدًا، لذا سيعمل أحد المستهلكين مع إصدار لم يُختبَر معه قطّ. تتراوح الأعراض بين أخطاء سلوكية خفية وأخطاء NoSuchMethodError أو ClassNotFoundException أثناء التشغيل — وهي أخطاء يصعب تشخيصها دون فهم جذورها.

تصوّر مشروعًا يعتمد على مكتبة A (التي تتطلّب jackson-databind:2.14) ومكتبة B (التي تتطلّب jackson-databind:2.17). يحسم Maven هذا التعارض عبر قاعدة أقرب تعريف يفوز: يُطبَّق الإصدار الأقرب إلى POM الجذر. أما Gradle فيستخدم استراتيجية مختلفة افتراضيًا: الأحدث يفوز. كلتا القاعدتين قد تُنتجان ملف JAR يكون أحد المستهلكين غير متوافق معه.

تشخيص التعارضات في Maven

هدف dependency:tree هو أداتك التشخيصية الأساسية. شغّله وأمرّ مخرجاته عبر بحث لإيجاد إصدارات متعددة من مكتبة ما:

mvn dependency:tree -Dverbose | grep jackson-databind

تطبع علامة -Dverbose جميع المرشّحين، بما فيهم من أُسقِطوا بسبب حل التعارض، مع التعليق عليهم بـ (version managed) أو (omitted for conflict). يُخبرك هذا التعليق بالضبط عن المسار الانتقالي الذي أحضر الإصدار الخاسر، مما يجعل الإصلاح واضحًا.

لإجبار إصدار محدّد بصرف النظر عن ما تطلبه التبعيات الانتقالية، أعلِن إدخالًا صريحًا في <dependencyManagement> بملف POM الخاص بك:

<dependencyManagement>
    <dependencies>
        <!-- تثبيت jackson-databind على 2.17.2 عبر جميع الاستدعاءات الانتقالية -->
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.17.2</version>
        </dependency>
    </dependencies>
</dependencyManagement>

الإدخال في <dependencyManagement> لا يُضيف التبعية إلى مسار الكلاسات — بل يتحكّم في الإصدار فقط إن ظهرت تلك القطعة في أي مكان بالرسم البياني للتبعيات.

تشخيص التعارضات في Gradle

يوفّر Gradle مهمّة dependencies ومهمّة dependencyInsight للتحقيق الأعمق:

# عرض شجرة التبعيات الكاملة لإعداد runtimeClasspath
./gradlew dependencies --configuration runtimeClasspath

# معرفة سبب اختيار إصدار محدّد
./gradlew dependencyInsight \
    --dependency jackson-databind \
    --configuration runtimeClasspath

يعرض تقرير المعلومات الإصدارَ الفائز وقاعدة الحل المطبَّقة وكل مسار طلب التبعية. لإجبار إصدار في Gradle استخدم استراتيجية الحل:

configurations.all {
    resolutionStrategy {
        force("com.fasterxml.jackson.core:jackson-databind:2.17.2")
    }
}

إجبار إصدار يحمل مسؤولية. أنت تؤكّد أن كودك وجميع مستهلكيه الانتقاليين يعملون بشكل صحيح مع الإصدار المثبَّت. تحقّق دائمًا من سجل تغييرات المكتبة للكشف عن تغييرات جذرية بين الإصدارات المتعارضة قبل إجبار خفض الإصدار.

قوائم المواد (BOMs)

BOM هو ملف POM خاص غرضه الوحيد هو إعلان مجموعة منسّقة ومختبرة من إصدارات التبعيات. حين تستورد BOM تحصل على جميع قيود الإصدارات دفعةً واحدة — دون إضافة كل مكتبة إلى مسار الكلاسات الخاص بك. النتيجة بناء تكون فيه المكتبات المرتبطة متوافقة دائمًا.

من أشهر BOMs: spring-boot-dependencies وjackson-bom وjunit-bom. إليك طريقة استيراد Jackson BOM في Maven:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.fasterxml.jackson</groupId>
            <artifactId>jackson-bom</artifactId>
            <version>2.17.2</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<!-- الآن تُضيف وحدات Jackson دون تحديد الإصدارات -->
<dependencies>
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
    </dependency>
    <dependency>
        <groupId>com.fasterxml.jackson.datatype</groupId>
        <artifactId>jackson-datatype-jsr310</artifactId>
    </dependency>
</dependencies>

الفهم الجوهري هنا هو أن جميع وحدات Jackson تتشارك دورة إصدار واحدة — استخدام jackson-databind:2.17.2 مع jackson-datatype-jsr310:2.14.0 خطأ شائع يُسبّب أخطاء تسلسل دقيقة. يُلغي BOM هذا النوع من الأخطاء بالكامل.

في Gradle، استورد BOM باستخدام تبعية platform():

dependencies {
    implementation(platform("com.fasterxml.jackson:jackson-bom:2.17.2"))
    implementation("com.fasterxml.jackson.core:jackson-databind")            // بدون إصدار
    implementation("com.fasterxml.jackson.datatype:jackson-datatype-jsr310") // بدون إصدار
}

مستخدمو Spring Boot يستخدمون BOM بالفعل. حين تضبط POM الوالد لـ Spring Boot أو تستورد spring-boot-dependencies، ترث إصدارات مُدارة لمئات المكتبات. لهذا السبب تكاد مشاريع Spring Boot الاعتيادية لا تحدّد إصدارات للتبعيات الشائعة — إذ إنها مثبَّتة كلّها في BOM.

البنيات القابلة للإعادة

البناء القابل للإعادة هو الذي يُنتج نفس الكود المصدري، حين يُبنى بالأداة نفسها، مخرجاتٍ متطابقة تمامًا في كل مرة — بصرف النظر عمّن يشغّله ومتى. حتى إن لم تكن تستهدف هذا المستوى من الدقة، فإن الممارسات الكامنة وراءه ضرورية لأي مشروع احترافي:

ثبّت كل إصدار صراحةً. لا تستخدم نطاقات الإصدارات أبدًا (مثل [1.0,2.0) في Maven أو latest.release في Gradle). تُسبّب النطاقات ترقيات صامتة تغيّر البناء يوم الثلاثاء قياسًا بيوم الاثنين.
الزم ملف القفل (lock file) في التحكّم بالإصدارات. يُنشئ Gradle ملف gradle/verification-metadata.xml ويدعم واجهة برمجة Lockfile. لا يمتلك Maven ملف قفل أصليًا لكنّه يُحقّق التثبيت عبر dependencyManagement وملفات BOM. كلا الأسلوبين ينبغي إدراجه في التحكّم بالإصدارات.
ثبّت أداة البناء ذاتها. استخدم Maven Wrapper (ملف mvnw) أو Gradle Wrapper (ملف gradlew) والزم ملف الـ wrapper وملف الخصائص. يُحدّد ملف الـ wrapper إصدارًا دقيقًا من أداة البناء، لذا يستخدم كل مطوّر وكل عميل CI نفس ملف Maven أو Gradle الثنائي.
ثبّت JDK. حدّد إصدار Java في ملف البناء ووثّق إصدار JDK المطلوب في README المشروع. الكود الثنائي الصادر عن Java 21 قد يختلف عن الصادر عن Java 17 حتى للكود المصدري ذاته.

# Gradle wrapper — يثبّت Gradle 8.8 لكل بيئة بناء
# gradle/wrapper/gradle-wrapper.properties
distributionUrl=https\://services.gradle.org/distributions/gradle-8.8-bin.zip

# Maven wrapper — يثبّت Maven 3.9.6
# .mvn/wrapper/maven-wrapper.properties
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.6/apache-maven-3.9.6-bin.zip

فعّل التحقّق من تبعيات Gradle للمشاريع الحساسة أمنيًا. شغّل ./gradlew --write-verification-metadata sha256 لتوليد gradle/verification-metadata.xml، ثم الزمه في التحكّم بالإصدارات. سيتحقّق Gradle من بصمة SHA-256 لكل قطعة مُنزَّلة في البنيات اللاحقة، مما يكشف هجمات سلسلة التوريد أو التنزيلات التالفة قبل وصولها إلى بيئة التشغيل.

الحفاظ على صحة التبعيات بمرور الوقت

تبعية مثبَّتة لا تُحدَّث أبدًا تصبح ثغرة أمنية مع الوقت. الهدف ليس تجميد التبعيات للأبد بل تحديثها بشكل مقصود:

استخدم إضافة Maven versions:display-dependency-updates أو مهمّة Gradle dependencyUpdates (عبر إضافة ben-manes/versions) للحصول على تقرير التحديثات المتاحة ضمن روتينك الأسبوعي أو بين كل سبرينت.
فعّل Dependabot أو Renovate في مستودعك على GitHub أو GitLab. تفتح هذه الأدوات طلبات سحب (pull requests) آلية لتحديثات التبعيات، تختبرها خطوط CI تلقائيًا — منحًا إياك تحديثات مع شبكة أمان.
عامل تنبيه CVE (الثغرات والمخاطر الشائعة) كأولوية من الدرجة الأولى. حين تحمل تبعية انتقالية ثغرة معروفة، ثبّت الإصدار المُصلَح في <dependencyManagement> أو resolutionStrategy فورًا، حتى قبل أن تُصدر التبعية المباشرة تحديثًا.
احذف بشكل دوري التبعيات غير المستخدمة. يُدرج هدف Maven dependency:analyze القطع المُعلَنة لكن غير المستخدمة والمستخدمة لكن غير المُعلَنة. التبعيات الانتقالية غير المُعلَنة التي تعتمد عليها مباشرةً ساعةٌ على وشك الانفجار — قد تختفي حين تغيّر المكتبة المُعلِنة تبعياتها الخاصة.

# Maven: سرد التبعيات القديمة
mvn versions:display-dependency-updates

# Maven: تحليل المُعلَن مقابل المستخدم فعليًا
mvn dependency:analyze

# Gradle: سرد التبعيات القديمة (تتطلّب إضافة ben-manes)
./gradlew dependencyUpdates -Drevision=release

الخلاصة

تُحسَم تعارضات الإصدارات بفهم استراتيجيات Maven (أقرب تعريف يفوز) وGradle (الأحدث يفوز) والتغلّب عليها صراحةً عبر <dependencyManagement> أو resolutionStrategy. تُتيح BOM استيراد مجموعة متوافقة ومختبرة من الإصدارات بإعلان واحد، مُلغيةً التعارضات الإصدارية داخل عائلة مكتبة بأكملها. البنيات القابلة للإعادة تستلزم تثبيت إصدارات الأدوات (الـ wrappers)، وتثبيت إصدارات التبعيات (لا نطاقات)، وإلزام ملف القفل أو كتلة dependencyManagement. الصيانة الدورية — طلبات سحب التحديثات الآلية، ومراقبة CVE، وتحليل التبعيات غير المستخدمة — تُبقي البناء سليمًا دون التضحية بالاستقرار.