mapstruct

MapStruct - Pemetaan kacang Java, cara mudah!

• Apa itu MapStruct?
• Persyaratan
• Menggunakan MapStruct
• Maven
• Gradle
• Dokumentasi dan mendapatkan bantuan
• Membangun dari Sumber
• Tautan
• Perizinan

Apa itu MapStruct?

MapStruct adalah pemroses anotasi Java yang dirancang untuk menghasilkan pembuat pemetaan yang aman untuk tipe dan berkinerja tinggi untuk kelas kacang Java, termasuk dukungan untuk catatan Java 16+. Dengan mengotomatiskan pembuatan pemetaan, MapStruct menghilangkan kebutuhan akan pengkodean manual yang membosankan dan rawan kesalahan. Generator menyediakan default yang masuk akal dan konversi tipe bawaan, memungkinkannya menangani pemetaan standar dengan mudah, sekaligus menawarkan fleksibilitas untuk konfigurasi khusus atau perilaku pemetaan khusus. Dengan integrasi yang mulus ke dalam proyek Java modern, MapStruct dapat memetakan antara kacang konvensional, catatan, dan bahkan hierarki yang kompleks, menjadikannya alat yang dapat beradaptasi untuk beragam aplikasi Java.

Dibandingkan dengan kerangka pemetaan yang bekerja saat runtime, MapStruct menawarkan keuntungan sebagai berikut:

• Eksekusi cepat dengan menggunakan pemanggilan metode biasa, bukan refleksi
• Keamanan tipe waktu kompilasi . Hanya pemetaan objek dan atribut satu sama lain yang dapat dipetakan, sehingga tidak ada pemetaan entitas pesanan ke DTO pelanggan yang tidak disengaja, dll.
• Kode mandiri —tidak ada ketergantungan runtime
• Hapus laporan kesalahan pada waktu pembuatan jika:
  • pemetaan tidak lengkap (tidak semua properti target dipetakan)
  • pemetaan salah (tidak dapat menemukan metode pemetaan atau konversi jenis yang tepat)
• Kode pemetaan yang mudah di-debug (atau dapat diedit secara manual—misalnya jika ada bug di generator)

Untuk membuat pemetaan antara dua tipe, deklarasikan antarmuka mapper seperti ini:

 @ Mapper
public interface CarMapper {

    CarMapper INSTANCE = Mappers . getMapper ( CarMapper . class );

    @ Mapping ( target = "seatCount" , source = "numberOfSeats" )
    CarDto carToCarDto ( Car car );
}

Pada waktu kompilasi MapStruct akan menghasilkan implementasi antarmuka ini. Implementasi yang dihasilkan menggunakan pemanggilan metode Java biasa untuk pemetaan antara objek sumber dan target, yaitu tidak ada refleksi yang terlibat. Secara default, properti dipetakan jika memiliki nama yang sama dalam sumber dan target, namun Anda dapat mengontrol aspek ini dan banyak aspek lainnya menggunakan @Mapping dan beberapa anotasi lainnya.

Persyaratan

MapStruct memerlukan Java 1.8 atau lebih baru.

Menggunakan MapStruct

MapStruct berfungsi dalam pembuatan baris perintah (javac biasa, melalui Maven, Gradle, Ant, dll.) dan IDE.

Untuk Eclipse, plug-in khusus sedang dalam pengembangan (lihat https://github.com/mapstruct/mapstruct-Eclipse). Ini melampaui apa yang mungkin dilakukan dengan pemroses anotasi, menyediakan bantuan konten untuk atribut anotasi, perbaikan cepat, dan banyak lagi.

Untuk IntelliJ, plug-in tersedia di pasar IntelliJ (lihat https://plugins.jetbrains.com/plugin/10036-mapstruct-support).

Maven

Untuk proyek berbasis Maven, tambahkan yang berikut ini ke file POM Anda untuk menggunakan MapStruct (dependensi tersedia di Maven Central):

...
< properties >
    < org .mapstruct.version>1.6.3</ org .mapstruct.version>
</ properties >
...
< dependencies >
    < dependency >
        < groupId >org.mapstruct</ groupId >
        < artifactId >mapstruct</ artifactId >
        < version >${org.mapstruct.version}</ version >
    </ dependency >
</ dependencies >
...
< build >
    < plugins >
        < plugin >
            < groupId >org.apache.maven.plugins</ groupId >
            < artifactId >maven-compiler-plugin</ artifactId >
            < version >3.13.0</ version >
            < configuration >
                < source >17</ source >
                < target >17</ target >
                < annotationProcessorPaths >
                    < path >
                        < groupId >org.mapstruct</ groupId >
                        < artifactId >mapstruct-processor</ artifactId >
                        < version >${org.mapstruct.version}</ version >
                    </ path >
                </ annotationProcessorPaths >
            </ configuration >
        </ plugin >
    </ plugins >
</ build >
...

Gradle

Untuk Gradle, Anda memerlukan sesuatu seperti berikut:

plugins {
    .. .
    id " com.diffplug.eclipse.apt " version " 3.26.0 " // Only for Eclipse
}

dependencies {
    .. .
    implementation ' org.mapstruct:mapstruct:1.6.3 '

    annotationProcessor ' org.mapstruct:mapstruct-processor:1.6.3 '
    testAnnotationProcessor ' org.mapstruct:mapstruct-processor:1.6.3 ' // if you are using mapstruct in test code
}
.. .

Jika Anda tidak menggunakan alat manajemen ketergantungan, Anda bisa mendapatkan paket distribusi dari halaman Rilis.

Dokumentasi dan mendapatkan bantuan

Untuk mempelajari lebih lanjut tentang MapStruct, lihat beranda proyek. Dokumentasi referensi mencakup semua fungsi yang disediakan secara rinci. Jika Anda memerlukan bantuan silakan tanyakan di Diskusi.

Membangun dari Sumber

MapStruct menggunakan Maven untuk pembuatannya. Java 11 diperlukan untuk membangun MapStruct dari sumber. Untuk membangun proyek yang lengkap, jalankan

 ./mvnw clean install

dari root direktori proyek. Untuk melewati modul distribusi, jalankan

 ./mvnw clean install -DskipDistribution=true

Mengimpor ke IDE

MapStruct menggunakan pemroses anotasi permata untuk menghasilkan permata pemetaan untuk anotasinya sendiri. Oleh karena itu, untuk integrasi yang lancar dalam pemrosesan anotasi IDE perlu diaktifkan.

IntelliJ

Pastikan Anda memiliki setidaknya IntelliJ 2018.2.x (diperlukan karena dukungan untuk annotationProcessors dari maven-compiler-plugin berasal dari versi tersebut). Aktifkan pemrosesan anotasi di IntelliJ (Build, Execution, Deployment -> Compiler -> Annotation Processors)

Gerhana

Pastikan Anda telah menginstal plugin m2e_apt.

Tautan

• Beranda
• Kode sumber
• Unduhan
• Pelacak masalah
• Kelompok pengguna
• membangun CI

Perizinan

MapStruct dilisensikan di bawah Lisensi Apache, Versi 2.0 ("Lisensi"); Anda tidak boleh menggunakan proyek ini kecuali sesuai dengan Lisensi. Anda dapat memperoleh salinan Lisensi di https://www.apache.org/licenses/LICENSE-2.0.