Spring Data Object Mapping Fundamentals

本节介绍 Spring Data 对象映射、对象创建、字段和属性访问、可变性和不可变性的基础知识。

This section covers the fundamentals of Spring Data object mapping, object creation, field and property access, mutability and immutability.

Spring Data 对象映射的核心职责是创建域对象实例并将存储本地数据结构映射到这些实例上。这意味着我们需要两个基本步骤：

Core responsibility of the Spring Data object mapping is to create instances of domain objects and map the store-native data structures onto those. This means we need two fundamental steps:

  1. Instance creation by using one of the constructors exposed.

  2. Instance population to materialize all exposed properties.

Object creation

Spring Data 自动尝试检测一个持久实体的构造函数，以便用于实现该类型的对象。解决算法的工作方式如下：

Spring Data automatically tries to detect a persistent entity’s constructor to be used to materialize objects of that type. The resolution algorithm works as follows:

  1. If there is a no-argument constructor, it will be used. Other constructors will be ignored.

  2. If there is a single constructor taking arguments, it will be used.

  3. If there are multiple constructors taking arguments, the one to be used by Spring Data will have to be annotated with @PersistenceCreator.

值解析假定构造函数参数名称与实体的属性名称匹配，即，执行解析就像填充属性一样，包括映射中的所有自定义项（不同的数据存储列或字段名称等）。这也要求类文件中提供参数名称信息或构造函数上存在 @ConstructorProperties 注释。

The value resolution assumes constructor argument names to match the property names of the entity, i.e. the resolution will be performed as if the property was to be populated, including all customizations in mapping (different datastore column or field name etc.). This also requires either parameter names information available in the class file or an @ConstructorProperties annotation being present on the constructor.

Object creation internals

为了避免反射时间开销，Spring Data 对象创建在默认情况下使用在运行时生成的工厂类，该类将直接调用领域类的构造函数。对于以下示例类型：

To avoid the overhead of reflection, Spring Data object creation uses a factory class generated at runtime by default, which will call the domain classes constructor directly. I.e. for this example type:

class Person {
  Person(String firstname, String lastname) { … }
}

我们将在运行时为这个类创建一个语义上等价的工厂类：

we will create a factory class semantically equivalent to this one at runtime:

class PersonObjectInstantiator implements ObjectInstantiator {

  Object newInstance(Object... args) {
    return new Person((String) args[0], (String) args[1]);
  }
}

这给了我们超过反射 10% 的迂回式性能提升。为了使领域类适用于这种优化，它需要遵守一组约束：

This gives us a roundabout 10% performance boost over reflection. For the domain class to be eligible for such optimization, it needs to adhere to a set of constraints:

  • it must not be a private class

  • it must not be a non-static inner class

  • it must not be a CGLib proxy class

  • the constructor to be used by Spring Data must not be private

如果符合上述任何一个标准，Spring Data 将回退到通过反射进行实体实例化。

If any of these criteria match, Spring Data will fall back to entity instantiation via reflection.

Property population

在创建了该实体的一个实例之后，Spring Data 填充该类的所有剩余的持久属性。除非已通过实体的构造函数填充（即通过其构造函数参数列表消耗），否则将首先填充标识符属性，以允许解析循环对象引用。在此之后，所有尚未被构造函数填充的非瞬态属性都会在实体实例上设置。为此，我们使用以下算法：

Once an instance of the entity has been created, Spring Data populates all remaining persistent properties of that class. Unless already populated by the entity’s constructor (i.e. consumed through its constructor argument list), the identifier property will be populated first to allow the resolution of cyclic object references. After that, all non-transient properties that have not already been populated by the constructor are set on the entity instance. For that we use the following algorithm:

  1. If the property is immutable but exposes a wither method (see below), we use the wither to create a new entity instance with the new property value.

  2. If property access (i.e. access through getters and setters) is defined, we are invoking the setter method.

  3. By default, we set the field value directly.

Property population internals

与我们的 [对象构建中的优化，映射。基础知识。对象创建。详细信息] 类似，我们还使用 Spring Data 运行时生成的访问器类来与实体实例交互。

Similarly to our mapping.fundamentals.object-creation.details we also use Spring Data runtime generated accessor classes to interact with the entity instance.

class Person {

  private final Long id;
  private String firstname;
  private @AccessType(Type.PROPERTY) String lastname;

  Person() {
    this.id = null;
  }

  Person(Long id, String firstname, String lastname) {
    // Field assignments
  }

  Person withId(Long id) {
    return new Person(id, this.firstname, this.lastame);
  }

  void setLastname(String lastname) {
    this.lastname = lastname;
  }
}
Example 1. A generated Property Accessor
class PersonPropertyAccessor implements PersistentPropertyAccessor {

  private static final MethodHandle firstname;              2

  private Person person;                                    1

  public void setProperty(PersistentProperty property, Object value) {

    String name = property.getName();

    if ("firstname".equals(name)) {
      firstname.invoke(person, (String) value);             2
    } else if ("id".equals(name)) {
      this.person = person.withId((Long) value);            3
    } else if ("lastname".equals(name)) {
      this.person.setLastname((String) value);              4
    }
  }
}
1 PropertyAccessor’s hold a mutable instance of the underlying object. This is, to enable mutations of otherwise immutable properties.
2 By default, Spring Data uses field-access to read and write property values. As per visibility rules of private fields, MethodHandles are used to interact with fields.
3 The class exposes a withId(…) method that’s used to set the identifier, e.g. when an instance is inserted into the datastore and an identifier has been generated. Calling withId(…) creates a new Vertex object. All subsequent mutations will take place in the new instance leaving the previous untouched.
4 Using property-access allows direct method invocations without using MethodHandles.

这给了我们超过反射 25% 的迂回式性能提升。为了使领域类适用于这种优化，它需要遵守一组约束：

This gives us a roundabout 25% performance boost over reflection. For the domain class to be eligible for such optimization, it needs to adhere to a set of constraints:

  • Types must not reside in the default or under the java package.

  • Types and their constructors must be public

  • Types that are inner classes must be static.

  • The used Java Runtime must allow for declaring classes in the originating ClassLoader. Java 9 and newer impose certain limitations.

在默认情况下，Spring Data 尝试使用生成的属性访问器，如果检测到限制，则回退到基于反射的属性访问器。

By default, Spring Data attempts to use generated property accessors and falls back to reflection-based ones if a limitation is detected.

让我们看看以下实体：

Let’s have a look at the following entity:

Example 2. A sample entity
class Person {

  private final @Id Long id;                                                1
  private final String firstname, lastname;                                 2
  private final LocalDate birthday;
  private final int age; 3

  private String comment;                                                   4
  private @AccessType(Type.PROPERTY) String remarks;                        5

  static Person of(String firstname, String lastname, LocalDate birthday) { 6

    return new Person(null, firstname, lastname, birthday,
      Period.between(birthday, LocalDate.now()).getYears());
  }

  Person(Long id, String firstname, String lastname, LocalDate birthday, int age) { 6

    this.id = id;
    this.firstname = firstname;
    this.lastname = lastname;
    this.birthday = birthday;
    this.age = age;
  }

  Person withId(Long id) {                                                  1
    return new Person(id, this.firstname, this.lastname, this.birthday);
  }

  void setRemarks(String remarks) {                                         5
    this.remarks = remarks;
  }
}
1 The identifier property is final but set to null in the constructor. The class exposes a withId(…) method that’s used to set the identifier, e.g. when an instance is inserted into the datastore and an identifier has been generated. The original Vertex instance stays unchanged as a new one is created. The same pattern is usually applied for other properties that are store managed but might have to be changed for persistence operations.
2 The firstname and lastname properties are ordinary immutable properties potentially exposed through getters.
3 The age property is an immutable but derived one from the birthday property. With the design shown, the database value will trump the defaulting as Spring Data uses the only declared constructor. Even if the intent is that the calculation should be preferred, it’s important that this constructor also takes age as parameter (to potentially ignore it) as otherwise the property population step will attempt to set the age field and fail due to it being immutable and no wither being present.
4 The comment property is mutable is populated by setting its field directly.
5 The remarks properties are mutable and populated by setting the comment field directly or by invoking the setter method for
6 The class exposes a factory method and a constructor for object creation. The core idea here is to use factory methods instead of additional constructors to avoid the need for constructor disambiguation through @PersistenceCreator. Instead, defaulting of properties is handled within the factory method.

General recommendations

  • Try to stick to immutable objects — Immutable objects are straightforward to create as materializing an object is then a matter of calling its constructor only. Also, this prevents your domain objects from being littered with setter methods that allow client code to manipulate the objects state. If you need those, prefer to make them package protected so that they can only be invoked by a limited amount of co-located types. Constructor-only materialization is up to 30% faster than properties population.

  • Provide an all-args constructor — Even if you cannot or don’t want to model your entities as immutable values, there’s still value in providing a constructor that takes all properties of the entity as arguments, including the mutable ones, as this allows the object mapping to skip the property population for optimal performance.

  • Use factory methods instead of overloaded constructors to avoid `@PersistenceCreator` — With an all-argument constructor needed for optimal performance, we usually want to expose more application use case specific constructors that omit things like auto-generated identifiers etc. It’s an established pattern to rather use static factory methods to expose these variants of the all-args constructor.

  • Make sure you adhere to the constraints that allow the generated instantiator and property accessor classes to be used

  • For identifiers to be generated, still use a final field in combination with a wither method

  • Use Lombok to avoid boilerplate code — As persistence operations usually require a constructor taking all arguments, their declaration becomes a tedious repetition of boilerplate parameter to field assignments that can best be avoided by using Lombok’s @AllArgsConstructor.

A note on immutable mapping

虽然我们建议尽可能使用不可变映射和构造，但在映射时会有一些限制。假设 A 对 B 具有构造函数引用并且 B 对 A 具有引用或更复杂的情况下的双向关系。这种情况对于 Spring Data Neo4j 来说是无法解决的。在 A 实例化期间，它迫切需要完全实例化的 B，而另一方面，它需要 A 的一个实例（准确地说，是 相同 的实例）。一般来说，SDN 允许这样的模型，但如果从数据库返回的数据包含上面描述的星座，它将在运行时抛出 MappingException。在这种情况下或在无法预见返回数据的样貌的情况下，你更适合为关系使用可变字段。

Although we recommend to use immutable mapping and constructs wherever possible, there are some limitations when it comes to mapping. Given a bidirectional relationship where A has a constructor reference to B and B has a reference to A, or a more complex scenario. This hen/egg situation is not solvable for Spring Data Neo4j. During the instantiation of A it eagerly needs to have a fully instantiated B, which on the other hand requires an instance (to be precise, the same instance) of A. SDN allows such models in general, but will throw a MappingException at runtime if the data that gets returned from the database contains such constellation as described above. In such cases or scenarios, where you cannot foresee what the data that gets returned looks like, you are better suited with a mutable field for the relationships.

Kotlin support

Spring Data 适应 Kotlin 的特殊性，允许创建和更改对象。

Spring Data adapts specifics of Kotlin to allow object creation and mutation.

Kotlin object creation

支持对 Kotlin 类进行实例化，默认情况下所有类都是不可变的，并且需要显式属性声明来定义可变属性。考虑以下 data 类 Vertex：

Kotlin classes are supported to be instantiated , all classes are immutable by default and require explicit property declarations to define mutable properties. Consider the following data class Vertex:

data class Person(val id: String, val name: String)

上面的类编译为具有显式构造函数的典型类。我们可以通过添加另一个构造函数并使用 @PersistenceCreator 对其进行注释来定制此类，以指示构造函数偏好：

The class above compiles to a typical class with an explicit constructor. We can customize this class by adding another constructor and annotate it with @PersistenceCreator to indicate a constructor preference:

data class Person(var id: String, val name: String) {

    @PersistenceCreator
    constructor(id: String) : this(id, "unknown")
}

Kotlin 支持参数可选择性，允许在不提供参数的情况下使用默认值。当 Spring Data 检测到带有参数默认值的构造函数时，如果数据存储不提供值（或仅返回 null），它会将这些参数保留为缺失，以便 Kotlin 可以应用参数默认值。考虑以下为 name 应用参数默认值的类：

Kotlin supports parameter optionality by allowing default values to be used if a parameter is not provided. When Spring Data detects a constructor with parameter defaulting, then it leaves these parameters absent if the data store does not provide a value (or simply returns null) so Kotlin can apply parameter defaulting. Consider the following class that applies parameter defaulting for name

data class Person(var id: String, val name: String = "unknown")

每次当 name 参数既不属于结果的一部分或其值为 null，则 name 将默认为 unknown。

Every time the name parameter is either not part of the result or its value is null, then the name defaults to unknown.

Property population of Kotlin data classes

在 Kotlin 中，默认情况下所有类都是不可变的，并且需要显式属性声明来定义可变属性。考虑以下 data 类 Vertex：

In Kotlin, all classes are immutable by default and require explicit property declarations to define mutable properties. Consider the following data class Vertex:

data class Person(val id: String, val name: String)

这个类实际上是不可变的。它允许创建新的实例，因为 Kotlin 生成了一个 copy(…) 方法，该方法创建新的对象实例，复制所有属性值（从现有对象）并将作为参数提供给该方法的属性值应用进来。

This class is effectively immutable. It allows creating new instances as Kotlin generates a copy(…) method that creates new object instances copying all property values from the existing object and applying property values provided as arguments to the method.