1. Overview

1.概述

In this tutorial, we’ll see how to use multiple source objects with MapStruct.

在本教程中，我们将看到如何用MapStruct使用多个源对象。

2. Single Source Object

2.单一来源对象

The most common use case for MapStruct is to map one object to another. Let’s assume we have a Customer class:

MapStruct最常见的用例是将一个对象映射到另一个对象。让我们假设我们有一个Customer类。

class Customer {

    private String firstName;
    private String lastName;

    // getters and setters

}

Let’s further assume that there’s a corresponding CustomerDto:

让我们进一步假设有一个相应的CustomerDto。

class CustomerDto {

    private String forename;
    private String surname;

    // getters and setters

}

We can now define a mapper that maps a Customer object to a CustomerDto object:

我们现在可以定义一个映射器，将Customer对象映射到CustomerDto对象。

@Mapper
public interface CustomerDtoMapper {

    @Mapping(source = "firstName", target = "forename")
    @Mapping(source = "lastName", target = "surname")
    CustomerDto from(Customer customer);

}

3. Multiple Source Objects

3.多个源对象

Sometimes we want the target object having properties from multiple source objects. Let’s imagine we write a shopping application.

有时我们希望目标对象具有来自多个源对象的属性。让我们设想一下，我们写一个购物应用程序。

We need to construct a delivery address to ship our goods:

我们需要构建一个送货地址来运送我们的货物。

class DeliveryAddress {

    private String forename;
    private String surname;
    private String street;
    private String postalcode;
    private String county;

    // getters and setters

}

Each customer can have multiple addresses. One can be a home address. Another can be a work address:

每个客户可以有多个地址。一个可以是家庭地址。另一个可以是工作地址。

class Address {

    private String street;
    private String postalcode;
    private String county;

    // getters and setters

}

We now need a mapper which creates the delivery address out of a customer and one of its addresses. MapStruct supports this by having multiple source objects:

我们现在需要一个映射器，它可以从一个客户和它的一个地址中创建送货地址。MapStruct通过拥有多个源对象来支持这一点。

@Mapper
interface DeliveryAddressMapper {

    @Mapping(source = "customer.firstName", target = "forename")
    @Mapping(source = "customer.lastName", target = "surname")
    @Mapping(source = "address.street", target = "street")
    @Mapping(source = "address.postalcode", target = "postalcode")
    @Mapping(source = "address.county", target = "county")
    DeliveryAddress from(Customer customer, Address address);

}

Let’s see this in action by writing a small test:

让我们通过写一个小测试来看看这一点的作用。

// given a customer
Customer customer = new Customer().setFirstName("Max")
  .setLastName("Powers");

// and some address
Address homeAddress = new Address().setStreet("123 Some Street")
  .setCounty("Nevada")
  .setPostalcode("89123");

// when calling DeliveryAddressMapper::from
DeliveryAddress deliveryAddress = deliveryAddressMapper.from(customer, homeAddress);

// then a new DeliveryAddress is created, based on the given customer and his home address
assertEquals(deliveryAddress.getForename(), customer.getFirstName());
assertEquals(deliveryAddress.getSurname(), customer.getLastName());
assertEquals(deliveryAddress.getStreet(), homeAddress.getStreet());
assertEquals(deliveryAddress.getCounty(), homeAddress.getCounty());
assertEquals(deliveryAddress.getPostalcode(), homeAddress.getPostalcode());

When we have more than one parameter, we can address them with dot-notation within the @Mapping annotation. For instance, to address the property firstName of the parameter named customer we simply write “customer.firstName“.

当我们有一个以上的参数时，我们可以在@Mapping注解中用点状注解来处理它们。例如，为了解决名为customer的参数的属性firstName，我们只需写”customer.firstName“。

However, we are not limited to two source objects. Any number will do.

然而，我们并不局限于两个源对象。任何数字都可以。

4. Update Existing Objects with @MappingTarget

4.用@MappingTarget更新现有对象

Till now, we had mappers that create new instances of the target class. With multiple source objects, we can now also provide an instance to be updated.

到现在为止，我们的映射器都是创建目标类的新实例。对于多个源对象，我们现在也可以提供一个实例来进行更新。

For example, let’s assume that we want to update the customer-related properties of a delivery address. All we need is to have one of the parameters be the same type as returned by the method and annotate it with @MappingTarget:

例如，让我们假设我们想更新一个送货地址的客户相关属性。我们只需要让其中一个参数与方法返回的类型相同，并且用@MappingTarget来注释它。

@Mapper
interface DeliveryAddressMapper {

    @Mapping(source = "address.postalcode", target = "postalcode")
    @Mapping(source = "address.county", target = "county")
    DeliveryAddress updateAddress(@MappingTarget DeliveryAddress deliveryAddress, Address address);

}

So, let’s go ahead and do a quick test with an instance of DeliveryAddress:

所以，让我们继续用DeliveryAddress的一个实例做一个快速测试。

// given a delivery address
DeliveryAddress deliveryAddress = new DeliveryAddress().setForename("Max")
  .setSurname("Powers")
  .setStreet("123 Some Street")
  .setCounty("Nevada")
  .setPostalcode("89123");

// and some new address
Address newAddress = new Address().setStreet("456 Some other street")
  .setCounty("Arizona")
  .setPostalcode("12345");

// when calling DeliveryAddressMapper::updateAddress
DeliveryAddress updatedDeliveryAddress = deliveryAddressMapper.updateAddress(deliveryAddress, newAddress);

// then the *existing* delivery address is updated
assertSame(deliveryAddress, updatedDeliveryAddress);

assertEquals(deliveryAddress.getStreet(), newAddress.getStreet());
assertEquals(deliveryAddress.getCounty(), newAddress.getCounty());
assertEquals(deliveryAddress.getPostalcode(), newAddress.getPostalcode());

5. Conclusion

5.总结

MapStruct allows us to pass more than one source parameter to mapping methods. For example, this comes handy when we want to combine multiple entities into one.

MapStruct允许我们向映射方法传递一个以上的源参数。例如，当我们想把多个实体合并成一个实体时，这就很方便了。

Another use case is to have the target object itself being one of the source parameters. Using the @MappingTarget annotation the given object can be updated in place.

另一个用例是让目标对象本身成为源参数之一。使用@MappingTarget注解，给定的对象可以被就地更新。

Make sure to check out all these samples over on GitHub.

请务必在GitHub上查看所有这些样本，。