MapStruct في Java: دليل شامل مع أمثلة عملية

ما هو MapStruct ولماذا تحتاجه؟

MapStruct هو مولد أكواد للغة Java يقوم تلقائيًا بإنشاء تطبيقات المحولات (Mappers) بين الكائنات من أنواع مختلفة. في تطوير Java الحديث، غالبًا ما نحتاج لتحويل كائن إلى آخر: Entity إلى DTO، DTO إلى VO، أو تحويل استجابة API إلى نموذج آخر. كتابة هذا الكود يدويًا هي مهمة مملة، تستغرق وقتًا طويلاً، وعرضة للأخطاء. MapStruct يحل هذه المشكلة عن طريق توليد كل الكود التكراري (boilerplate) في مرحلة الترجمة (compile-time).

المزايا الرئيسية لـ MapStruct:

• الأداء العالي: توليد الكود في مرحلة الترجمة. لا يوجد استخدام للـ Reflection، ولا فقدان في الأداء أثناء التشغيل. MapStruct يعمل بنفس سرعة الكود المكتوب يدويًا.
• أمان الأنواع (Type Safety): جميع الأخطاء (عدم تطابق الأنواع، الحقول المفقودة) تُكتشف في مرحلة الترجمة، وليس أثناء التشغيل.
• البساطة: الحد الأدنى من الإعدادات. يكفي تعريف واجهة (Interface) أو كلاس مجرد (Abstract Class) مع دوال التحويل، وسيقوم MapStruct بتوليد التطبيق تلقائيًا.
• المرونة: دعم التحويلات المعقدة، تحويل الأنواع، استخدام التعبيرات، استدعاء الدوال، والتكامل مع المكتبات الأخرى (Lombok، Spring، وغيرها).
• نظافة الكود: فصل كود التحويل عن منطق الأعمال، مما يجعل الكود أكثر قابلية للقراءة والصيانة.

MapStruct مفيد بشكل خاص في التطبيقات متعددة الطبقات (Controller-Service-Repository)، حيث يتطلب الأمر تحويل الكائنات بين الطبقات بشكل متكرر.

تثبيت MapStruct

MapStruct لا يتم تثبيته عبر pip أو npm، لأنه مكتبة خاصة بلغة Java. لربط MapStruct بمشروعك، يتم استخدام نظام بناء Maven أو Gradle.

التثبيت عبر Maven

أضف التبعيات التالية إلى ملف pom.xml الخاص بك:

<dependencies>
    <!-- المكتبة الأساسية لـ MapStruct -->
    <dependency>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct</artifactId>
        <version>1.5.5.Final</version>
    </dependency>

    <!-- معالج التعليقات التوضيحية (لتوليد الكود) -->
    <dependency>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct-processor</artifactId>
        <version>1.5.5.Final</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

التثبيت عبر Gradle

لـ Gradle، أضف إلى ملف build.gradle:

dependencies {
    implementation 'org.mapstruct:mapstruct:1.5.5.Final'
    annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.5.Final'
}

هام: تأكد من تطابق إصدار mapstruct-processor مع إصدار mapstruct. بعد إضافة التبعيات، قم ببناء المشروع (مثلًا: mvn clean compile) ليتمكن MapStruct من توليد تطبيقات المحولات.

بداية سريعة مع مثال برمجي

لنقم بإنشاء محول بسيط يقوم بتحويل كائن Car (Entity) إلى كائن CarDto (DTO).

الخطوة 1: تعريف الكلاسات المصدر والهدف

// Car.java
public class Car {
    private String make;
    private int numberOfSeats;
    private CarType type;

    // المنشئات، الدوال الجالبة (Getters) والدوال الضابطة (Setters)
    public Car() {}

    public Car(String make, int numberOfSeats, CarType type) {
        this.make = make;
        this.numberOfSeats = numberOfSeats;
        this.type = type;
    }

    public String getMake() { return make; }
    public void setMake(String make) { this.make = make; }
    public int getNumberOfSeats() { return numberOfSeats; }
    public void setNumberOfSeats(int numberOfSeats) { this.numberOfSeats = numberOfSeats; }
    public CarTy