Maven والملفات JAR المحلية: 5 أخطاء قاتلة وحلولها

لماذا "مجرد نسخ JAR إلى مجلد" لا يعمل؟

كل مطور Java واجه Maven مرة واحدة على الأقل، سيجد نفسه عاجلاً أم آجلاً أمام حائط: "أحتاج إلى ربط مكتبة قديمة غير موجودة في Maven Central. ماذا أفعل؟". تبحث في Google، تجد سؤالاً على Stack Overflow بآلاف المشاهدات، تجرب أول نصيحة - وتتلقى ClassNotFoundException أو Missing artifact.

هل هذا مألوف؟ في هذه المقالة، سنستعرض أهم الأخطاء عند إضافة ملفات JAR المحلية إلى مشروع Maven والأهم من ذلك، كيفية تجنبها. ستتعلم ليس فقط النظرية، بل سترى أيضاً كوداً عملياً يمكنك تطبيقه فوراً في مشروعك بلغة Java.

الخطأ رقم 1: نطاق system بدون systemPath

أكثر فخ شائع للمبتدئين هو إضافة تبعية باستخدام <scope>system</scope> ولكن نسيان تحديد <systemPath>. يحاول Maven بأمانة العثور على ملف JAR، لكنه لا يعرف مكان وجوده.

كيف يبدو الخطأ

[ERROR] Failed to execute goal on project my-app: \nCould not resolve dependencies for project com.example:my-app:jar:1.0: \nThe following artifacts could not be resolved: \ncom.example:my-custom-lib:jar:1.0 (absent)

الكود الخاطئ

<dependency>\n    <groupId>com.example</groupId>\n    <artifactId>my-custom-lib</artifactId>\n    <version>1.0</version>\n    <scope>system</scope>\n    <!-- systemPath مفقود! -->\n</dependency>

الحل الصحيح

حدد دائماً المسار الكامل لملف JAR باستخدام <systemPath>. يُفضل استخدام مسار نسبي من جذر المشروع لتجنب الارتباط بجهاز مطور معين.

<dependency>\n    <groupId>com.example</groupId>\n    <artifactId>my-custom-lib</artifactId>\n    <version>1.0</version>\n    <scope>system</scope>\n    <systemPath>${project.basedir}/libs/my-custom-lib-1.0.jar</systemPath>\n</dependency>

هام: يجب أن يكون ملف JAR موجوداً في مجلد libs/ داخل مشروعك. أنشئه إذا لم تكن قد فعلت ذلك بعد.

الخطأ رقم 2: نسيان install-file للمشاريع متعددة الوحدات

لنفترض أنك أضفت ملف JAR محلياً باستخدام system scope، وكل شيء يعمل محلياً. ولكن عندما تحاول بناء المشروع على خادم CI (Jenkins, GitLab CI) - يفشل البناء. لماذا؟ لأن نطاق system لا يُنقل بشكل متعدٍ (transitively) ولا يدخل إلى المستودع المحلي لـ Maven.

النهج الصحيح: تثبيت JAR في المستودع المحلي

استخدم الأمر mvn install:install-file. سيؤدي هذا إلى إضافة ملف JAR الخاص بك إلى ~/.m2/repository، وسيكون متاحاً لجميع وحدات المشروع ولعمليات البناء على CI.

mvn install:install-file \\\n   -Dfile=libs/my-custom-lib-1.0.jar \\\n   -DgroupId=com.example \\\n   -DartifactId=my-custom-lib \\\n   -Dversion=1.0 \\\n   -Dpackaging=jar \\\n   -DgeneratePom=true

بعد ذلك، في pom.xml يمكنك تحديد تبعية عادية بدون systemPath:

<dependency>\n    <groupId>com.example</groupId>\n    <artifactId>my-custom-lib</artifactId>\n    <version>1.0</version>\n</dependency>

الخطأ رقم 3: استخدام رابط file:// في المستودعات

يحاول بعض المطورين "خداع" Maven بإضافة مجلد محلي كمستودع عبر <repository> باستخدام رابط file://. تقنياً، هذا يعمل، لكنه يخلق مجموعة من المشاكل:

\n
• عدم قابلية النقل: المسار /home/user/project/libs لن يعمل على جهاز آخر.
\n
• الخلط بين الإصدارات: