mirror of
https://github.com/mapstruct/mapstruct.git
synced 2025-07-12 00:00:08 +08:00
#787 Giving some love to the readme.md
This commit is contained in:
parent
ba28a64986
commit
9f76af7e3d
57
readme.md
57
readme.md
@ -3,37 +3,58 @@
|
||||
[](http://search.maven.org/#search%7Cga%7C1%7Cg%3Aorg.mapstruct%20AND%20v%3A1.*.Final)
|
||||
[](http://search.maven.org/#search%7Cga%7C1%7Cg%3Aorg.mapstruct)
|
||||
|
||||
* [What is MapStruct?](#what-is-mapstruct)
|
||||
* [Requirements](#requirements)
|
||||
* [Using MapStruct](#using-mapstruct)
|
||||
* [Maven](#maven)
|
||||
* [Gradle](#gradle)
|
||||
* [Documentation and getting help](#documentation-and-getting-help)
|
||||
* [Licensing](#licensing)
|
||||
* [Building from Source](#building-from-source)
|
||||
* [Links](#links)
|
||||
|
||||
## What is MapStruct?
|
||||
|
||||
MapStruct is a Java [annotation processor](http://docs.oracle.com/javase/6/docs/technotes/guides/apt/index.html) for the generation of type-safe bean mapping classes.
|
||||
MapStruct is a Java [annotation processor](http://docs.oracle.com/javase/6/docs/technotes/guides/apt/index.html) for the generation of type-safe and performant mappers for Java bean classes.
|
||||
|
||||
All you have to do is to define a mapper interface which declares any required mapping methods. During compilation, MapStruct will generate an implementation of this interface. This implementation uses plain Java method invocations for mapping between source and target objects, i.e. no reflection or similar.
|
||||
To create a mapping between two types, declare a mapper class like this:
|
||||
|
||||
Compared to writing mapping code from hand, MapStruct saves time by generating code which is tedious and error-prone to write. Following a convention over configuration approach, MapStruct uses sensible defaults but steps out of your way when it comes to configuring or implementing special behavior.
|
||||
```java
|
||||
@Mapper
|
||||
public interface CarMapper {
|
||||
|
||||
Compared to dynamic mapping frameworks, MapStruct offers the following advantages:
|
||||
CarMapper INSTANCE = Mappers.getMapper( CarMapper.class );
|
||||
|
||||
@Mapping(source = "numberOfSeats", target = "seatCount")
|
||||
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. there is no reflection involved. By default, properties are mapped if they have the same name in source and target, but this and many other aspects can be controlled using `@Mapping` and a handful of other annotations.
|
||||
|
||||
MapStruct 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, 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 entities or attributes can't be mapped
|
||||
* Clear error-reports at build time if mappings are incorrect and incomplete
|
||||
* Mapping code is easy to debug (or edited by hand e.g. in case of a bug in the generator)
|
||||
|
||||
MapStruct works in command line builds (plain javac, via Maven, Gradle, Ant etc.) and IDEs. For Eclipse, there is a dedicated plug-in under development (see https://github.com/mapstruct/mapstruct-eclipse) which goes beyond what's possible with an annotation processor, providing content assist for annotation attributes, quick fixes and more.
|
||||
|
||||
## Documentation and getting help
|
||||
|
||||
To learn more about MapStruct in two minutes, refer to the [project homepage](http://mapstruct.org). The [reference documentation](http://mapstruct.org/documentation) covers all provided functionality in detail. If you need help, come and join the [mapstruct-users](https://groups.google.com/forum/?hl=en#!forum/mapstruct-users) group.
|
||||
|
||||
## Requirements
|
||||
|
||||
MapStruct requires Java 1.6 or later.
|
||||
|
||||
## Using MapStruct
|
||||
|
||||
MapStruct is a Java annotation processor based on [JSR 269](https://jcp.org/en/jsr/detail?id=269) and as such can be used within command line builds (javac, Ant, Maven etc.) as well as from within your IDE.
|
||||
MapStruct works in command line builds (plain javac, via Maven, Gradle, Ant etc.) and IDEs.
|
||||
|
||||
For Maven based projects add the following to your POM file in order to use MapStruct (the dependencies can be obtained from Maven Central):
|
||||
For Eclipse, there is a dedicated plug-in under development (see https://github.com/mapstruct/mapstruct-eclipse) which goes beyond what's possible with an annotation processor, providing content assist for annotation attributes, quick fixes and more.
|
||||
|
||||
### Maven
|
||||
|
||||
For Maven-based projects add the following to your POM file in order to use MapStruct (the dependencies can be obtained from Maven Central):
|
||||
|
||||
```xml
|
||||
...
|
||||
@ -72,6 +93,8 @@ For Maven based projects add the following to your POM file in order to use MapS
|
||||
...
|
||||
```
|
||||
|
||||
### Gradle
|
||||
|
||||
For Gradle, you need something along the following lines:
|
||||
|
||||
```groovy
|
||||
@ -88,7 +111,11 @@ dependencies {
|
||||
...
|
||||
```
|
||||
|
||||
Alternatively, a distribution bundle is available from SourceForge.
|
||||
If you don't work with a dependency management tool you can obtain a distribution bundle from [SourceForge](https://sourceforge.net/projects/mapstruct/files/).
|
||||
|
||||
## Documentation and getting help
|
||||
|
||||
To learn more about MapStruct, refer to the [project homepage](http://mapstruct.org). The [reference documentation](http://mapstruct.org/documentation) covers all provided functionality in detail. If you need help, come and join the [mapstruct-users](https://groups.google.com/forum/?hl=en#!forum/mapstruct-users) group.
|
||||
|
||||
## Licensing
|
||||
|
||||
@ -96,7 +123,7 @@ MapStruct is licensed under the Apache License, Version 2.0 (the "License"); you
|
||||
|
||||
## Building from Source
|
||||
|
||||
MapStruct uses Maven for its build. To build the complete project run
|
||||
MapStruct uses Maven for its build. Java 8 is required for building MapStruct from source. To build the complete project run
|
||||
|
||||
mvn clean install
|
||||
|
||||
|
Loading…
x
Reference in New Issue
Block a user