Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mapstruct/mapstruct

An annotation processor for generating type-safe bean mappers
https://github.com/mapstruct/mapstruct

annotation-processor bean-mapping java javabeans mapping mapstruct no-reflection

Last synced: 9 days ago
JSON representation

An annotation processor for generating type-safe bean mappers

Host: GitHub
URL: https://github.com/mapstruct/mapstruct
Owner: mapstruct
License: other
Created: 2012-05-28T12:42:42.000Z (over 12 years ago)
Default Branch: main
Last Pushed: 2024-10-18T22:49:29.000Z (17 days ago)
Last Synced: 2024-10-24T17:53:15.555Z (11 days ago)
Topics: annotation-processor, bean-mapping, java, javabeans, mapping, mapstruct, no-reflection
Language: Java
Homepage: https://mapstruct.org/
Size: 10.9 MB
Stars: 7,103
Watchers: 139
Forks: 952
Open Issues: 472
Metadata Files:
- Readme: readme.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.txt

Awesome Lists containing this project

awesome-tech - MapStruct - Code generator that simplifies mappings between different bean types, based on a convention-over-configuration approach. (Solutions / Bean Mapping)
awesome - mapstruct/mapstruct - An annotation processor for generating type-safe bean mappers (Java)
awesome-java - MapStruct - Code generator that simplifies mappings between different bean types, based on a convention-over-configuration approach. (Projects / Bean Mapping)
awesome-list - mapstruct/mapstruct - An annotation processor for generating type-safe bean mappers (Java)
awesome-java-zh - MapStruct - 代码生成器，它基于约定配置方法简化了不同bean类型之间的映射。 (项目 / Bean映射)
awesome-java - MapStruct - Code generator that simplifies mappings between different bean types, based on a convention-over-configuration approach. (Projects / Bean Mapping)

README

        # MapStruct - Java bean mappings, the easy way!

[![Latest Stable Version](https://img.shields.io/badge/Latest%20Stable%20Version-1.6.0-blue.svg)](https://central.sonatype.com/search?q=g:org.mapstruct%20v:1.6.0)

[![Latest Version](https://img.shields.io/maven-central/v/org.mapstruct/mapstruct-processor.svg?maxAge=3600&label=Latest%20Release)](https://central.sonatype.com/search?q=g:org.mapstruct)

[![License](https://img.shields.io/badge/License-Apache%202.0-yellowgreen.svg)](https://github.com/mapstruct/mapstruct/blob/main/LICENSE.txt)

[![Build Status](https://github.com/mapstruct/mapstruct/workflows/CI/badge.svg?branch=main)](https://github.com/mapstruct/mapstruct/actions?query=branch%3Amain+workflow%3ACI)

[![Coverage Status](https://img.shields.io/codecov/c/github/mapstruct/mapstruct.svg)](https://codecov.io/gh/mapstruct/mapstruct/tree/main)

* [What is MapStruct?](#what-is-mapstruct)

* [Requirements](#requirements)

* [Using MapStruct](#using-mapstruct)

 * [Maven](#maven)

 * [Gradle](#gradle)

* [Documentation and getting help](#documentation-and-getting-help)

* [Building from Source](#building-from-source)

* [Links](#links)

* [Licensing](#licensing)

## What is MapStruct?

MapStruct is a Java [annotation processor](https://docs.oracle.com/javase/6/docs/technotes/guides/apt/index.html) for the generation of type-safe and performant mappers for Java bean classes. It saves you from writing mapping code by hand, which is a tedious and error-prone task. The generator comes with sensible defaults and many built-in type conversions, but it steps out of your way when it comes to configuring or implementing special behavior.

Compared to mapping frameworks working at runtime, MapStruct offers the following advantages:

* **Fast execution** by using plain method invocations instead of reflection

* **Compile-time type safety**. Only objects and attributes mapping to each other can be mapped, so there's no accidental mapping of an order entity into a customer DTO, etc.

* **Self-contained code**—no runtime dependencies

* **Clear error reports** at build time if:

  * mappings are incomplete (not all target properties are mapped)

  * mappings are incorrect (cannot find a proper mapping method or type conversion)

* **Easily debuggable mapping code** (or editable by hand—e.g. in case of a bug in the generator)

To create a mapping between two types, declare a mapper interface like this:

```java

@Mapper

public interface CarMapper {

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

    @Mapping(target = "seatCount", source = "numberOfSeats")

    CarDto carToCarDto(Car car);

}

```

At compile time MapStruct will generate an implementation of this interface. The generated implementation uses plain Java method invocations for mapping between source and target objects, i.e. no reflection is involved. By default, properties are mapped if they have the same name in source and target, but you can control this and many other aspects using `@Mapping` and a handful of other annotations.

## Requirements

MapStruct requires Java 1.8 or later.

## Using MapStruct

MapStruct works in command line builds (plain javac, via Maven, Gradle, Ant, etc.) and IDEs.

For Eclipse, a dedicated plug-in is in development (see https://github.com/mapstruct/mapstruct-eclipse). It goes beyond what's possible with an annotation processor, providing content assist for annotation attributes, quick fixes and more.

For IntelliJ the plug-in is available within the IntelliJ marketplace (see https://plugins.jetbrains.com/plugin/10036-mapstruct-support).

### Maven

For Maven-based projects, add the following to your POM file in order to use MapStruct (the dependencies are available at Maven Central):

```xml

...

    1.6.0

...

    

        org.mapstruct

        mapstruct

        ${org.mapstruct.version}

    

...

    

        

            org.apache.maven.plugins

            maven-compiler-plugin

            3.13.0

            

                17

                17

                

                    

                        org.mapstruct

                        mapstruct-processor

                        ${org.mapstruct.version}

                    

                

            

        

    

...

```

### Gradle

For Gradle, you need something along the following lines:

```groovy

plugins {

    ...

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

}

dependencies {

    ...

    implementation 'org.mapstruct:mapstruct:1.6.0'

    annotationProcessor 'org.mapstruct:mapstruct-processor:1.6.0'

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

}

...

```

If you don't work with a dependency management tool, you can obtain a distribution bundle from [Releases page](https://github.com/mapstruct/mapstruct/releases).

## Documentation and getting help

To learn more about MapStruct, refer to the [project homepage](https://mapstruct.org). The [reference documentation](https://mapstruct.org/documentation/reference-guide/) covers all provided functionality in detail. If you need help please ask it in the [Discussions](https://github.com/mapstruct/mapstruct/discussions).

## Building from Source

MapStruct uses Maven for its build. Java 11 is required for building MapStruct from source. To build the complete project, run

    ./mvnw clean install

from the root of the project directory. To skip the distribution module, run 

    ./mvnw clean install -DskipDistribution=true

    

## Importing into IDE

MapStruct uses the gem annotation processor to generate mapping gems for its own annotations.

Therefore, for seamless integration within an IDE annotation processing needs to be enabled.

### IntelliJ 

Make sure that you have at least IntelliJ 2018.2.x (needed since support for `annotationProcessors` from the `maven-compiler-plugin` is from that version).

Enable annotation processing in IntelliJ (Build, Execution, Deployment -> Compiler -> Annotation Processors)

### Eclipse

Make sure that you have the [m2e_apt](https://marketplace.eclipse.org/content/m2e-apt) plugin installed.

## Links

* [Homepage](https://mapstruct.org)

* [Source code](https://github.com/mapstruct/mapstruct/)

* [Downloads](https://github.com/mapstruct/mapstruct/releases)

* [Issue tracker](https://github.com/mapstruct/mapstruct/issues)

* [User group](https://groups.google.com/forum/?hl=en#!forum/mapstruct-users)

* [CI build](https://github.com/mapstruct/mapstruct/actions/)

## Licensing

MapStruct is licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0.