对象映射 (Object Mapping) _ Spring Data MongoDB 4.3.1 中文文档(官方文档中文翻译) —

丰富的映射支持由 . 转换器包含一个元数据模型，该模型提供完整的功能集，用于将域对象映射到 MongoDB 文档。映射元数据模型是通过在域对象上使用注释来填充的。但是，基础结构并不局限于使用注释作为元数据信息的唯一来源。还允许您按照一组约定将对象映射到文档，而无需提供任何其他元数据。MappingMongoConverterMappingMongoConverterSpring中文文档

本节介绍的功能，包括基础知识、如何使用约定将对象映射到文档，以及如何使用基于注释的映射元数据覆盖这些约定。MappingMongoConverterSpring中文文档

对象映射基础知识

本节介绍了 Spring Data 对象映射、对象创建、字段和属性访问、可变性和不可变性的基础知识。请注意，本节仅适用于不使用底层数据存储（如 JPA）的对象映射的 Spring Data 模块。此外，请务必查阅特定于存储的部分，了解特定于存储的对象映射，例如索引、自定义列或字段名称等。Spring中文文档

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

使用公开的构造函数之一创建实例。Spring中文文档
实例填充，用于具体化所有公开的属性。Spring中文文档

对象创建

Spring Data 会自动尝试检测用于具体化该类型对象的持久实体的构造函数。解析算法的工作原理如下：Spring中文文档

如果有一个静态工厂方法注释，则使用它。@PersistenceCreatorSpring中文文档
如果存在单个构造函数，则使用该构造函数。Spring中文文档
如果有多个构造函数，并且恰好有一个构造函数用注释，则使用它。@PersistenceCreatorSpring中文文档
如果类型是 Java，则使用规范构造函数。RecordSpring中文文档
如果存在无参数构造函数，则使用它。其他构造函数将被忽略。Spring中文文档

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

可以使用 Spring Framework 的值注释和特定于存储的 SpEL 表达式来自定义值解析。有关更多详细信息，请参阅有关商店特定映射的部分。@ValueSpring中文文档

对象创建内部

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

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

我们将在运行时创建一个语义上等同于此的工厂类：Spring中文文档

class PersonObjectInstantiator implements ObjectInstantiator {

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

这为我们提供了 10% 的性能提升。要使域类符合此类优化的条件，它需要遵守一组约束：Spring中文文档

它不能是私有类Spring中文文档
它不能是非静态的内部类Spring中文文档
它不能是 CGLib 代理类Spring中文文档
Spring Data 要使用的构造函数不能是私有的Spring中文文档

如果这些条件中的任何一个匹配，Spring Data 将通过反射回退到实体实例化。Spring中文文档

物业人口

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

如果属性是不可变的，但公开了一个方法（见下文），我们将使用该方法创建一个具有新属性值的新实体实例。with…with…Spring中文文档
如果定义了属性访问（即通过 getter 和 setter 的访问），我们将调用 setter 方法。Spring中文文档
如果属性是可变的，我们直接设置字段。Spring中文文档
如果该属性是不可变的，我们将使用持久性操作使用的构造函数（请参阅对象创建）来创建实例的副本。Spring中文文档
默认情况下，我们直接设置字段值。Spring中文文档

物业人口内部结构

与对象构造的优化类似，我们也使用 Spring Data 运行时生成的访问器类与实体实例进行交互。Spring中文文档

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;
  }
}

生成的属性访问器

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 保存基础对象的可变实例。这是为了启用其他不可变属性的突变。
2	默认情况下，Spring Data 使用字段访问来读取和写入属性值。根据字段的可见性规则，用于与字段交互。`privateMethodHandles`
3	该类公开用于设置标识符的方法，例如，当实例插入数据存储并生成标识符时。调用将创建一个新对象。所有后续突变都将在新实例中发生，而前一个实例保持不变。`withId(…)withId(…)Person`
4	使用属性访问允许直接调用方法，而无需使用。`MethodHandles`

这为我们提供了 25% 的性能提升。要使域类符合此类优化的条件，它需要遵守一组约束：Spring中文文档

类型不得驻留在默认值中或包下。javaSpring中文文档
类型及其构造函数必须是publicSpring中文文档
作为内部类的类型必须是。staticSpring中文文档
使用的 Java 运行时必须允许在原始 .Java 9 和更高版本施加了某些限制。ClassLoaderSpring中文文档

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

让我们看一下以下实体：Spring中文文档

示例实体

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, this.age);
  }

  void setRemarks(String remarks) {                                         (5)
    this.remarks = remarks;
  }
}

1	标识符属性是最终属性，但在构造函数中设置为。该类公开用于设置标识符的方法，例如，当实例插入数据存储并生成标识符时。创建新实例时，原始实例保持不变。相同的模式通常应用于存储管理的其他属性，但可能需要更改持久性操作。 wither 方法是可选的，因为持久性构造函数（参见 6）实际上是一个复制构造函数，并且设置属性将转换为使用应用新标识符值创建新实例。`nullwithId(…)Person`
2	和属性是可能通过 getter 公开的普通不可变属性。`firstnamelastname`
3	该属性是不可变的，但派生自该属性。在所示的设计中，数据库值将优先于默认值，因为 Spring Data 使用唯一声明的构造函数。即使意图是计算应该是首选，也很重要的是，此构造函数也必须将其作为参数（以可能忽略它），否则属性填充步骤将尝试设置年龄字段并失败，因为它是不可变的，并且不存在任何方法。`agebirthdayagewith…`
4	该属性是可变的，通过直接设置其字段来填充。`comment`
5	该属性是可变的，并通过调用 setter 方法进行填充。`remarks`
6	该类公开用于创建对象的工厂方法和构造函数。这里的核心思想是使用工厂方法而不是其他构造函数，以避免需要通过来消除构造函数的歧义。相反，属性的默认值是在工厂方法中处理的。如果希望 Spring Data 使用工厂方法进行对象实例化，请使用 .`@PersistenceCreator@PersistenceCreator`

一般建议

尝试坚持使用不可变对象 — 不可变对象很容易创建，因为具体化对象只需调用其构造函数即可。此外，这样还可以避免域对象充斥着允许客户端代码操作对象状态的 setter 方法。如果需要这些，最好将它们设置为包保护，以便它们只能由有限数量的共置类型调用。仅构造函数的实现速度比属性填充快 30%。Spring中文文档
提供 all-args 构造函数 — 即使不能或不想将实体建模为不可变值，提供将实体的所有属性作为参数（包括可变属性）的构造函数仍然有价值，因为这允许对象映射跳过属性填充以获得最佳性能。Spring中文文档
使用工厂方法而不是重载构造函数来避免@PersistenceCreator — 由于需要全参数构造函数来获得最佳性能，我们通常希望公开更多特定于应用程序用例的构造函数，这些构造函数省略了自动生成的标识符等内容。使用静态工厂方法来公开 all-args 构造函数的这些变体是一种既定模式。Spring中文文档
确保遵守允许使用生成的实例化器和属性访问器类的约束 —Spring中文文档
对于要生成的标识符，仍将 final 字段与全参数持久性构造函数（首选）或 with... 方法结合使用 —Spring中文文档
使用 Lombok 来避免样板代码 — 由于持久化操作通常需要构造函数获取所有参数，因此它们的声明会成为对字段赋值的样板参数的乏味重复，而使用 Lombok 的 .@AllArgsConstructorSpring中文文档

覆盖属性

Java 允许灵活地设计域类，其中子类可以定义已在其超类中声明的相同名称的属性。请看以下示例：Spring中文文档

public class SuperType {

   private CharSequence field;

   public SuperType(CharSequence field) {
      this.field = field;
   }

   public CharSequence getField() {
      return this.field;
   }

   public void setField(CharSequence field) {
      this.field = field;
   }
}

public class SubType extends SuperType {

   private String field;

   public SubType(String field) {
      super(field);
      this.field = field;
   }

   @Override
   public String getField() {
      return this.field;
   }

   public void setField(String field) {
      this.field = field;

      // optional
      super.setField(field);
   }
}

这两个类都定义一个使用可分配的类型。然而阴影. 根据类设计，使用构造函数可能是设置的唯一默认方法。或者，调用 setter 可以设置 in . 所有这些机制在某种程度上都会产生冲突，因为这些属性共享相同的名称，但可能表示两个不同的值。如果类型不可赋值，Spring Data 会跳过超类型属性。也就是说，重写属性的类型必须可分配给其超类型属性类型才能注册为重写，否则超类型属性将被视为瞬态属性。我们通常建议使用不同的属性名称。fieldSubTypeSuperType.fieldSuperType.fieldsuper.setField(…)fieldSuperTypeSpring中文文档

Spring Data 模块通常支持包含不同值的覆盖属性。从编程模型的角度来看，有几件事需要考虑：Spring中文文档

应保留哪个属性（默认为所有声明的属性）？您可以通过使用对属性进行批注来排除这些属性。@TransientSpring中文文档
如何表示数据存储中的属性？对不同的值使用相同的字段/列名称通常会导致数据损坏，因此应使用显式字段/列名称至少批注一个属性。Spring中文文档
不能使用，因为通常不能在不对 setter 实现进行任何进一步假设的情况下设置超属性。@AccessType(PROPERTY)Spring中文文档

Kotlin 支持

Spring Data 调整了 Kotlin 的细节，以允许对象创建和更改。Spring中文文档

Kotlin 对象创建

支持实例化 Kotlin 类，默认情况下所有类都是不可变的，并且需要显式属性声明来定义可变属性。Spring中文文档

Spring Data 会自动尝试检测用于具体化该类型对象的持久实体的构造函数。解析算法的工作原理如下：Spring中文文档

如果存在用注释的构造函数，则使用该构造函数。@PersistenceCreatorSpring中文文档
如果类型是 Kotlin 数据类，则使用主构造函数。Spring中文文档
如果有一个静态工厂方法注释，则使用它。@PersistenceCreatorSpring中文文档
如果存在单个构造函数，则使用该构造函数。Spring中文文档
如果有多个构造函数，并且恰好有一个构造函数用注释，则使用它。@PersistenceCreatorSpring中文文档
如果类型是 Java，则使用规范构造函数。RecordSpring中文文档
如果存在无参数构造函数，则使用它。其他构造函数将被忽略。Spring中文文档

考虑以下类：dataPersonSpring中文文档

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

上面的类编译为具有显式构造函数的典型类。我们可以通过添加另一个构造函数来自定义这个类，并用它进行注释以指示构造函数首选项：@PersistenceCreatorSpring中文文档

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

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

Kotlin 支持参数可选性，允许在未提供参数时使用默认值。当 Spring Data 检测到参数默认值的构造函数时，如果数据存储没有提供值（或只是返回），则这些参数不存在，因此 Kotlin 可以应用参数默认值。请考虑以下应用参数默认值的类nullnameSpring中文文档

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

每当参数不是结果的一部分或其值为时，默认值为。namenullnameunknownSpring中文文档

Kotlin 数据类的属性填充

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

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

此类实际上是不可变的。它允许创建新实例，因为 Kotlin 会生成一个创建新对象实例的方法，从现有对象复制所有属性值，并将作为参数提供的属性值应用于该方法。copy(…)Spring中文文档

Kotlin 覆盖属性

Kotlin 允许声明属性覆盖以更改子类中的属性。Spring中文文档

open class SuperType(open var field: Int)

class SubType(override var field: Int = 1) :
	SuperType(field) {
}

这样的排列呈现两个名称为的属性。 Kotlin 为每个类中的每个属性生成属性访问器（getter 和 setter）。实际上，代码如下所示：fieldSpring中文文档

public class SuperType {

   private int field;

   public SuperType(int field) {
      this.field = field;
   }

   public int getField() {
      return this.field;
   }

   public void setField(int field) {
      this.field = field;
   }
}

public final class SubType extends SuperType {

   private int field;

   public SubType(int field) {
      super(field);
      this.field = field;
   }

   public int getField() {
      return this.field;
   }

   public void setField(int field) {
      this.field = field;
   }
}

Getters 和 Setters 只在片场而不是 . 在这样的安排中，使用构造函数是设置的唯一默认方法。可以添加 to set via 的方法，但超出了支持的约定。属性重写在某种程度上会产生冲突，因为属性共享相同的名称，但可能表示两个不同的值。我们通常建议使用不同的属性名称。SubTypeSubType.fieldSuperType.fieldSuperType.fieldSubTypeSuperType.fieldthis.SuperType.field = …Spring中文文档

Spring Data 模块通常支持包含不同值的覆盖属性。从编程模型的角度来看，有几件事需要考虑：Spring中文文档

应保留哪个属性（默认为所有声明的属性）？您可以通过使用对属性进行批注来排除这些属性。@TransientSpring中文文档
如何表示数据存储中的属性？对不同的值使用相同的字段/列名称通常会导致数据损坏，因此应使用显式字段/列名称至少批注一个属性。Spring中文文档
不能使用，因为无法设置超级属性。@AccessType(PROPERTY)Spring中文文档

Kotlin 值类

Kotlin 值类专为更具表现力的领域模型而设计，以明确基本概念。 Spring Data 可以读取和写入使用值类定义属性的类型。Spring中文文档

请考虑以下域模型：Spring中文文档

@JvmInline
value class EmailAddress(val theAddress: String)                                    (1)

data class Contact(val id: String, val name:String, val emailAddress: EmailAddress) (2)

1	具有不可为 null 值类型的简单值类。
2	数据类使用 value 类定义属性。`EmailAddress`

使用非基元值类型的不可为 null 属性在 compiled 类中展平为值类型。可为 null 的基元值类型或可为 null 的值中值类型用其包装器类型表示，这会影响值类型在数据库中的表示方式。

1	PropertyAccessor 保存基础对象的可变实例。这是为了启用其他不可变属性的突变。
2	默认情况下，Spring Data 使用字段访问来读取和写入属性值。根据字段的可见性规则，用于与字段交互。`privateMethodHandles`
3	该类公开用于设置标识符的方法，例如，当实例插入数据存储并生成标识符时。调用将创建一个新对象。所有后续突变都将在新实例中发生，而前一个实例保持不变。`withId(…)withId(…)Person`
4	使用属性访问允许直接调用方法，而无需使用。`MethodHandles`

1	标识符属性是最终属性，但在构造函数中设置为。该类公开用于设置标识符的方法，例如，当实例插入数据存储并生成标识符时。创建新实例时，原始实例保持不变。相同的模式通常应用于存储管理的其他属性，但可能需要更改持久性操作。 wither 方法是可选的，因为持久性构造函数（参见 6）实际上是一个复制构造函数，并且设置属性将转换为使用应用新标识符值创建新实例。`nullwithId(…)Person`
2	和属性是可能通过 getter 公开的普通不可变属性。`firstnamelastname`
3	该属性是不可变的，但派生自该属性。在所示的设计中，数据库值将优先于默认值，因为 Spring Data 使用唯一声明的构造函数。即使意图是计算应该是首选，也很重要的是，此构造函数也必须将其作为参数（以可能忽略它），否则属性填充步骤将尝试设置年龄字段并失败，因为它是不可变的，并且不存在任何方法。`agebirthdayagewith…`
4	该属性是可变的，通过直接设置其字段来填充。`comment`
5	该属性是可变的，并通过调用 setter 方法进行填充。`remarks`
6	该类公开用于创建对象的工厂方法和构造函数。这里的核心思想是使用工厂方法而不是其他构造函数，以避免需要通过来消除构造函数的歧义。相反，属性的默认值是在工厂方法中处理的。如果希望 Spring Data 使用工厂方法进行对象实例化，请使用 .`@PersistenceCreator@PersistenceCreator`

1	具有不可为 null 值类型的简单值类。
2	数据类使用 value 类定义属性。`EmailAddress`

基于约定的映射

MappingMongoConverter有一些约定，用于在未提供其他映射元数据时将对象映射到文档。约定是：Spring中文文档

短 Java 类名按以下方式映射到集合名称。该类映射到集合名称。com.bigbank.SavingsAccountsavingsAccountSpring中文文档
所有嵌套对象都作为嵌套对象存储在文档中，而不是作为 DBRefs。Spring中文文档
转换器使用在其注册的任何 Spring Converter 来覆盖对象属性到文档字段和值的默认映射。Spring中文文档
对象的字段用于在文档中的字段之间进行转换。不使用公共属性。JavaBeanSpring中文文档
如果有一个非零参数构造函数，其构造函数参数名称与文档的顶级字段名称匹配，则使用该构造函数。否则，将使用零参数构造函数。如果存在多个非零参数构造函数，则会引发异常。Spring中文文档

如何在映射图层中处理字段。`_id`

MongoDB要求你有一个所有文档的字段。如果未提供，驱动程序将分配具有生成值的 ObjectId。该字段可以是除数组以外的任何类型，只要它是唯一的。驱动程序自然支持所有基元类型和 Dates。使用时，有一些规则来控制如何将 Java 类中的属性映射到字段。_id_idMappingMongoConverter_idSpring中文文档

下面概述了将映射到文档字段的字段：_idSpring中文文档

用（）注释的字段将映射到该字段。
此外，可以通过注释自定义文档字段的名称，在这种情况下，文档将不包含字段。@Idorg.springframework.data.annotation.Id_id@Field_idSpring中文文档
没有注释但已命名的字段将映射到该字段。id_idSpring中文文档

表 1.字段定义转换示例`_id`
字段定义	MongoDB 中生成的 id-fieldname
`String`同上Spring中文文档	`_id`Spring中文文档
`@Field` `String`同上Spring中文文档	`_id`Spring中文文档
`@Field("x")` `String`同上Spring中文文档	`x`Spring中文文档
`@Id` `String`xSpring中文文档	`_id`Spring中文文档
`@Field("x")` `@Id` `String`ySpring中文文档	`_id` (`@Field(name)`被忽略，优先）`@Id`Spring中文文档

下面概述了将对映射到 _id 文档字段的属性执行的类型转换（如果有）。Spring中文文档

如果在 Java 类中将 Named 字段声明为 String 或 BigInteger，则如果可能，它将转换为 ObjectId 并存储为 ObjectId。 ObjectId 作为字段类型也有效。如果在应用程序中指定值，则 MongoDB 驱动程序将完成到 ObjectId 的转换。如果指定的值无法转换为 ObjectId，则该值将按原样存储在文档的字段中。如果字段使用注释，这也适用。ididid_id@IdSpring中文文档
如果一个字段在 Java 类中被注释，它将被转换为并使用其实际类型进行存储。除非声明所需的字段类型，否则不会发生进一步的转换。如果未为该字段提供任何值，则将创建一个新字段并将其转换为属性类型。@MongoId@MongoIdidObjectIdSpring中文文档
如果在 Java 类中注释了字段，则将尝试将该值转换为声明的。如果未为该字段提供任何值，则将创建一个新字段并将其转换为声明的类型。@MongoId(FieldType.…)FieldTypeidObjectIdSpring中文文档
如果 Java 类中未将 Named 声明为 String、BigInteger 或 ObjectID，则应在应用程序中为其分配一个值，以便它可以“按原样”存储在文档的字段中。id_idSpring中文文档
如果 Java 类中不存在命名的字段，则驱动程序将生成一个隐式文件，但不会映射到 Java 类的属性或字段。id_idSpring中文文档

查询和更新时，将使用转换器处理与上述保存文档规则相对应的和对象的转换，以便查询中使用的字段名称和类型能够与域类中的内容匹配。MongoTemplateQueryUpdateSpring中文文档

表 1.字段定义转换示例`_id`
字段定义	MongoDB 中生成的 id-fieldname
`String`同上Spring中文文档	`_id`Spring中文文档
`@Field` `String`同上Spring中文文档	`_id`Spring中文文档
`@Field("x")` `String`同上Spring中文文档	`x`Spring中文文档
`@Id` `String`xSpring中文文档	`_id`Spring中文文档
`@Field("x")` `@Id` `String`ySpring中文文档	`_id` (`@Field(name)`被忽略，优先）`@Id`Spring中文文档

数据映射和类型转换

Spring Data MongoDB支持所有可以表示为BSON（MongoDB的内部文档格式）的类型。除了这些类型之外，Spring Data MongoDB还提供了一组内置转换器来映射其他类型。您可以提供自己的转换器来调整类型转换。有关更多详细信息，请参阅自定义转换 - 覆盖默认映射。Spring中文文档

内置类型转换：

表 2.类型
类型	类型转换	样本
`String`Spring中文文档	本地Spring中文文档	`{"firstname" : "Dave"}`Spring中文文档
`double`, , ,`DoublefloatFloat`Spring中文文档	本地Spring中文文档	`{"weight" : 42.5}`Spring中文文档
`int`, , ,`IntegershortShort`Spring中文文档	本机 32 位整数Spring中文文档	`{"height" : 42}`Spring中文文档
`long`,`Long`Spring中文文档	本机 64 位整数Spring中文文档	`{"height" : 42}`Spring中文文档
`Date`,`Timestamp`Spring中文文档	本地Spring中文文档	`{"date" : ISODate("2019-11-12T23:00:00.809Z")}`Spring中文文档
`byte[]`Spring中文文档	本地Spring中文文档	`{"bin" : { "$binary" : "AQIDBA==", "$type" : "00" }}`Spring中文文档
`java.util.UUID`（旧版 UUID）Spring中文文档	本地Spring中文文档	`{"uuid" : { "$binary" : "MEaf1CFQ6lSphaa3b9AtlA==", "$type" : "03" }}`Spring中文文档
`Date`Spring中文文档	本地Spring中文文档	`{"date" : ISODate("2019-11-12T23:00:00.809Z")}`Spring中文文档
`ObjectId`Spring中文文档	本地Spring中文文档	`{"_id" : ObjectId("5707a2690364aba3136ab870")}`Spring中文文档
数组`ListBasicDBList`Spring中文文档	本地Spring中文文档	`{"cookies" : [ … ]}`Spring中文文档
`boolean`,`Boolean`Spring中文文档	本地Spring中文文档	`{"active" : true}`Spring中文文档
`null`Spring中文文档	本地Spring中文文档	`{"value" : null}`Spring中文文档
`Document`Spring中文文档	本地Spring中文文档	`{"value" : { … }}`Spring中文文档
`Decimal128`Spring中文文档	本地Spring中文文档	`{"value" : NumberDecimal(…)}`Spring中文文档
`AtomicInteger` 在实际转换之前调用`get()`Spring中文文档	转换器 32 位整数Spring中文文档	`{"value" : "741" }`Spring中文文档
`AtomicLong` 在实际转换之前调用`get()`Spring中文文档	转换器 64 位整数Spring中文文档	`{"value" : "741" }`Spring中文文档
`BigInteger`Spring中文文档	转炉 `String`Spring中文文档	`{"value" : "741" }`Spring中文文档
`BigDecimal`Spring中文文档	转炉 `String`Spring中文文档	`{"value" : "741.99" }`Spring中文文档
`URL`Spring中文文档	转炉Spring中文文档	`{"website" : "https://spring.io/projects/spring-data-mongodb/" }`Spring中文文档
`Locale`Spring中文文档	转炉Spring中文文档	`{"locale : "en_US" }`Spring中文文档
`char`,`Character`Spring中文文档	转炉Spring中文文档	`{"char" : "a" }`Spring中文文档
`NamedMongoScript`Spring中文文档	转炉 `Code`Spring中文文档	`{"_id" : "script name", value: (some javascript code)`}Spring中文文档
`java.util.Currency`Spring中文文档	转炉Spring中文文档	`{"currencyCode" : "EUR"}`Spring中文文档
`Instant` （爪哇 8）Spring中文文档	本地Spring中文文档	`{"date" : ISODate("2019-11-12T23:00:00.809Z")}`Spring中文文档
`Instant` （Joda，JSR310-BackPort）Spring中文文档	转炉Spring中文文档	`{"date" : ISODate("2019-11-12T23:00:00.809Z")}`Spring中文文档
`LocalDate` （Joda、Java 8、JSR310-BackPort）Spring中文文档	转换器 / 原生（Java8）^[1]Spring中文文档	`{"date" : ISODate("2019-11-12T00:00:00.000Z")}`Spring中文文档
`LocalDateTime`，（Joda， Java 8， JSR310-BackPort）`LocalTime`Spring中文文档	转换器 / 原生（Java8）^[2]Spring中文文档	`{"date" : ISODate("2019-11-12T23:00:00.809Z")}`Spring中文文档
`DateTime`（城田）Spring中文文档	转炉Spring中文文档	`{"date" : ISODate("2019-11-12T23:00:00.809Z")}`Spring中文文档
`ZoneId`（Java 8，JSR310-BackPort）Spring中文文档	转炉Spring中文文档	`{"zoneId" : "ECT - Europe/Paris"}`Spring中文文档
`Box`Spring中文文档	转炉Spring中文文档	`{"box" : { "first" : { "x" : 1.0 , "y" : 2.0} , "second" : { "x" : 3.0 , "y" : 4.0}}`Spring中文文档
`Polygon`Spring中文文档	转炉Spring中文文档	`{"polygon" : { "points" : [ { "x" : 1.0 , "y" : 2.0} , { "x" : 3.0 , "y" : 4.0} , { "x" : 4.0 , "y" : 5.0}]}}`Spring中文文档
`Circle`Spring中文文档	转炉Spring中文文档	`{"circle" : { "center" : { "x" : 1.0 , "y" : 2.0} , "radius" : 3.0 , "metric" : "NEUTRAL"}}`Spring中文文档
`Point`Spring中文文档	转炉Spring中文文档	`{"point" : { "x" : 1.0 , "y" : 2.0}}`Spring中文文档
`GeoJsonPoint`Spring中文文档	转炉Spring中文文档	`{"point" : { "type" : "Point" , "coordinates" : [3.0 , 4.0] }}`Spring中文文档
`GeoJsonMultiPoint`Spring中文文档	转炉Spring中文文档	`{"geoJsonLineString" : {"type":"MultiPoint", "coordinates": [ [ 0 , 0 ], [ 0 , 1 ], [ 1 , 1 ] ] }}`Spring中文文档
`Sphere`Spring中文文档	转炉Spring中文文档	`{"sphere" : { "center" : { "x" : 1.0 , "y" : 2.0} , "radius" : 3.0 , "metric" : "NEUTRAL"}}`Spring中文文档
`GeoJsonPolygon`Spring中文文档	转炉Spring中文文档	`{"polygon" : { "type" : "Polygon", "coordinates" : [[ [ 0 , 0 ], [ 3 , 6 ], [ 6 , 1 ], [ 0 , 0 ] ]] }}`Spring中文文档
`GeoJsonMultiPolygon`Spring中文文档	转炉Spring中文文档	`{"geoJsonMultiPolygon" : { "type" : "MultiPolygon", "coordinates" : [ [ [ [ -73.958 , 40.8003 ] , [ -73.9498 , 40.7968 ] ] ], [ [ [ -73.973 , 40.7648 ] , [ -73.9588 , 40.8003 ] ] ] ] }}`Spring中文文档
`GeoJsonLineString`Spring中文文档	转炉Spring中文文档	`{ "geoJsonLineString" : { "type" : "LineString", "coordinates" : [ [ 40 , 5 ], [ 41 , 6 ] ] }}`Spring中文文档
`GeoJsonMultiLineString`Spring中文文档	转炉Spring中文文档	`{"geoJsonLineString" : { "type" : "MultiLineString", coordinates: [ [ [ -73.97162 , 40.78205 ], [ -73.96374 , 40.77715 ] ], [ [ -73.97880 , 40.77247 ], [ -73.97036 , 40.76811 ] ] ] }}`Spring中文文档

集合处理

集合处理取决于 MongoDB 返回的实际值。Spring中文文档

如果文档不包含映射到集合的字段，则映射不会更新该属性。这意味着该值将保留为 java 默认值或在对象创建期间设置的任何值。nullSpring中文文档
如果文档包含要映射的字段，但该字段包含一个值（如：），则属性值将设置为。null{ 'list' : null }nullSpring中文文档
如果文档包含要映射到集合的字段，而该字段不是（如：），则该集合将填充映射的值。null{ 'list' : [ … ] }Spring中文文档

通常，如果使用构造函数创建，则可以获取要设置的值。如果查询响应未提供属性值，则属性填充可以使用默认初始化值。Spring中文文档

表 2.类型
类型	类型转换	样本
`String`Spring中文文档	本地Spring中文文档	`{"firstname" : "Dave"}`Spring中文文档
`double`, , ,`DoublefloatFloat`Spring中文文档	本地Spring中文文档	`{"weight" : 42.5}`Spring中文文档
`int`, , ,`IntegershortShort`Spring中文文档	本机 32 位整数Spring中文文档	`{"height" : 42}`Spring中文文档
`long`,`Long`Spring中文文档	本机 64 位整数Spring中文文档	`{"height" : 42}`Spring中文文档
`Date`,`Timestamp`Spring中文文档	本地Spring中文文档	`{"date" : ISODate("2019-11-12T23:00:00.809Z")}`Spring中文文档
`byte[]`Spring中文文档	本地Spring中文文档	`{"bin" : { "$binary" : "AQIDBA==", "$type" : "00" }}`Spring中文文档
`java.util.UUID`（旧版 UUID）Spring中文文档	本地Spring中文文档	`{"uuid" : { "$binary" : "MEaf1CFQ6lSphaa3b9AtlA==", "$type" : "03" }}`Spring中文文档
`Date`Spring中文文档	本地Spring中文文档	`{"date" : ISODate("2019-11-12T23:00:00.809Z")}`Spring中文文档
`ObjectId`Spring中文文档	本地Spring中文文档	`{"_id" : ObjectId("5707a2690364aba3136ab870")}`Spring中文文档
数组`ListBasicDBList`Spring中文文档	本地Spring中文文档	`{"cookies" : [ … ]}`Spring中文文档
`boolean`,`Boolean`Spring中文文档	本地Spring中文文档	`{"active" : true}`Spring中文文档
`null`Spring中文文档	本地Spring中文文档	`{"value" : null}`Spring中文文档
`Document`Spring中文文档	本地Spring中文文档	`{"value" : { … }}`Spring中文文档
`Decimal128`Spring中文文档	本地Spring中文文档	`{"value" : NumberDecimal(…)}`Spring中文文档
`AtomicInteger` 在实际转换之前调用`get()`Spring中文文档	转换器 32 位整数Spring中文文档	`{"value" : "741" }`Spring中文文档
`AtomicLong` 在实际转换之前调用`get()`Spring中文文档	转换器 64 位整数Spring中文文档	`{"value" : "741" }`Spring中文文档
`BigInteger`Spring中文文档	转炉 `String`Spring中文文档	`{"value" : "741" }`Spring中文文档
`BigDecimal`Spring中文文档	转炉 `String`Spring中文文档	`{"value" : "741.99" }`Spring中文文档
`URL`Spring中文文档	转炉Spring中文文档	`{"website" : "https://spring.io/projects/spring-data-mongodb/" }`Spring中文文档
`Locale`Spring中文文档	转炉Spring中文文档	`{"locale : "en_US" }`Spring中文文档
`char`,`Character`Spring中文文档	转炉Spring中文文档	`{"char" : "a" }`Spring中文文档
`NamedMongoScript`Spring中文文档	转炉 `Code`Spring中文文档	`{"_id" : "script name", value: (some javascript code)`}Spring中文文档
`java.util.Currency`Spring中文文档	转炉Spring中文文档	`{"currencyCode" : "EUR"}`Spring中文文档
`Instant` （爪哇 8）Spring中文文档	本地Spring中文文档	`{"date" : ISODate("2019-11-12T23:00:00.809Z")}`Spring中文文档
`Instant` （Joda，JSR310-BackPort）Spring中文文档	转炉Spring中文文档	`{"date" : ISODate("2019-11-12T23:00:00.809Z")}`Spring中文文档
`LocalDate` （Joda、Java 8、JSR310-BackPort）Spring中文文档	转换器 / 原生（Java8）^[1]Spring中文文档	`{"date" : ISODate("2019-11-12T00:00:00.000Z")}`Spring中文文档
`LocalDateTime`，（Joda， Java 8， JSR310-BackPort）`LocalTime`Spring中文文档	转换器 / 原生（Java8）^[2]Spring中文文档	`{"date" : ISODate("2019-11-12T23:00:00.809Z")}`Spring中文文档
`DateTime`（城田）Spring中文文档	转炉Spring中文文档	`{"date" : ISODate("2019-11-12T23:00:00.809Z")}`Spring中文文档
`ZoneId`（Java 8，JSR310-BackPort）Spring中文文档	转炉Spring中文文档	`{"zoneId" : "ECT - Europe/Paris"}`Spring中文文档
`Box`Spring中文文档	转炉Spring中文文档	`{"box" : { "first" : { "x" : 1.0 , "y" : 2.0} , "second" : { "x" : 3.0 , "y" : 4.0}}`Spring中文文档
`Polygon`Spring中文文档	转炉Spring中文文档	`{"polygon" : { "points" : [ { "x" : 1.0 , "y" : 2.0} , { "x" : 3.0 , "y" : 4.0} , { "x" : 4.0 , "y" : 5.0}]}}`Spring中文文档
`Circle`Spring中文文档	转炉Spring中文文档	`{"circle" : { "center" : { "x" : 1.0 , "y" : 2.0} , "radius" : 3.0 , "metric" : "NEUTRAL"}}`Spring中文文档
`Point`Spring中文文档	转炉Spring中文文档	`{"point" : { "x" : 1.0 , "y" : 2.0}}`Spring中文文档
`GeoJsonPoint`Spring中文文档	转炉Spring中文文档	`{"point" : { "type" : "Point" , "coordinates" : [3.0 , 4.0] }}`Spring中文文档
`GeoJsonMultiPoint`Spring中文文档	转炉Spring中文文档	`{"geoJsonLineString" : {"type":"MultiPoint", "coordinates": [ [ 0 , 0 ], [ 0 , 1 ], [ 1 , 1 ] ] }}`Spring中文文档
`Sphere`Spring中文文档	转炉Spring中文文档	`{"sphere" : { "center" : { "x" : 1.0 , "y" : 2.0} , "radius" : 3.0 , "metric" : "NEUTRAL"}}`Spring中文文档
`GeoJsonPolygon`Spring中文文档	转炉Spring中文文档	`{"polygon" : { "type" : "Polygon", "coordinates" : [[ [ 0 , 0 ], [ 3 , 6 ], [ 6 , 1 ], [ 0 , 0 ] ]] }}`Spring中文文档
`GeoJsonMultiPolygon`Spring中文文档	转炉Spring中文文档	`{"geoJsonMultiPolygon" : { "type" : "MultiPolygon", "coordinates" : [ [ [ [ -73.958 , 40.8003 ] , [ -73.9498 , 40.7968 ] ] ], [ [ [ -73.973 , 40.7648 ] , [ -73.9588 , 40.8003 ] ] ] ] }}`Spring中文文档
`GeoJsonLineString`Spring中文文档	转炉Spring中文文档	`{ "geoJsonLineString" : { "type" : "LineString", "coordinates" : [ [ 40 , 5 ], [ 41 , 6 ] ] }}`Spring中文文档
`GeoJsonMultiLineString`Spring中文文档	转炉Spring中文文档	`{"geoJsonLineString" : { "type" : "MultiLineString", coordinates: [ [ [ -73.97162 , 40.78205 ], [ -73.96374 , 40.77715 ] ], [ [ -73.97880 , 40.77247 ], [ -73.97036 , 40.76811 ] ] ] }}`Spring中文文档

集合处理

集合处理取决于 MongoDB 返回的实际值。Spring中文文档

如果文档不包含映射到集合的字段，则映射不会更新该属性。这意味着该值将保留为 java 默认值或在对象创建期间设置的任何值。nullSpring中文文档
如果文档包含要映射的字段，但该字段包含一个值（如：），则属性值将设置为。null{ 'list' : null }nullSpring中文文档
如果文档包含要映射到集合的字段，而该字段不是（如：），则该集合将填充映射的值。null{ 'list' : [ … ] }Spring中文文档

通常，如果使用构造函数创建，则可以获取要设置的值。如果查询响应未提供属性值，则属性填充可以使用默认初始化值。Spring中文文档

映射配置

除非显式配置，否则在创建 . 您可以创建自己的 . 这样做可以让你指定在类路径中的位置可以找到你的领域类，以便Spring Data MongoDB可以提取元数据并构建索引。此外，通过创建自己的实例，您可以注册 Spring 转换器以将特定类映射到数据库或从数据库映射特定类。MappingMongoConverterMongoTemplateMappingMongoConverterSpring中文文档

您可以使用基于 Java 或基于 XML 的元数据来配置 well 和 MongoTemplate。以下示例显示了配置：MappingMongoConvertercom.mongodb.client.MongoClientSpring中文文档

JavaSpring中文文档
XMLSpring中文文档

@Configuration
public class MongoConfig extends AbstractMongoClientConfiguration {

  @Override
  public String getDatabaseName() {
    return "database";
  }

  // the following are optional

  @Override
  public String getMappingBasePackage() { (1)
    return "com.bigbank.domain";
  }

  @Override
  void configureConverters(MongoConverterConfigurationAdapter adapter) { (2)

  	adapter.registerConverter(new org.springframework.data.mongodb.test.PersonReadConverter());
  	adapter.registerConverter(new org.springframework.data.mongodb.test.PersonWriteConverter());
  }

  @Bean
  public LoggingEventListener<MongoMappingEvent> mappingEventsListener() {
    return new LoggingEventListener<MongoMappingEvent>();
  }
}

1	映射基础包定义用于扫描用于预初始化 . 默认情况下，使用配置类包。`MappingContext`
2	为特定域类型配置其他自定义转换器，将这些类型的默认映射过程替换为自定义实现。

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:mongo="http://www.springframework.org/schema/data/mongo"
  xsi:schemaLocation="
    http://www.springframework.org/schema/data/mongo https://www.springframework.org/schema/data/mongo/spring-mongo.xsd
    http://www.springframework.org/schema/beans https://www.springframework.org/schema/beans/spring-beans-3.0.xsd">

  <!-- Default bean name is 'mongo' -->
  <mongo:mongo-client host="localhost" port="27017"/>

  <mongo:db-factory dbname="database" mongo-ref="mongoClient"/>

  <!-- by default look for a Mongo object named 'mongo' - default name used for the converter is 'mappingConverter' -->
  <mongo:mapping-converter base-package="com.bigbank.domain">
    <mongo:custom-converters>
      <mongo:converter ref="readConverter"/>
      <mongo:converter>
        <bean class="org.springframework.data.mongodb.test.PersonWriteConverter"/>
      </mongo:converter>
    </mongo:custom-converters>
  </mongo:mapping-converter>

  <bean id="readConverter" class="org.springframework.data.mongodb.test.PersonReadConverter"/>

  <!-- set the mapping converter to be used by the MongoTemplate -->
  <bean id="mongoTemplate" class="org.springframework.data.mongodb.core.MongoTemplate">
    <constructor-arg name="mongoDbFactory" ref="mongoDbFactory"/>
    <constructor-arg name="mongoConverter" ref="mappingConverter"/>
  </bean>

  <bean class="org.springframework.data.mongodb.core.mapping.event.LoggingEventListener"/>

</beans>

AbstractMongoClientConfiguration要求您实现定义 A 的方法以及提供数据库名称。还有一个名为“可以重写”的方法，以告诉转换器在哪里扫描带有注释的类。com.mongodb.client.MongoClientAbstractMongoClientConfigurationgetMappingBasePackage(…)@DocumentSpring中文文档

您可以通过重写该方法将其他转换器添加到转换器中。 MongoDB 的原生 JSR-310 支持可以通过启用。前面的示例中还显示了一个，它记录了发布到 Spring 基础结构上的实例。customConversionsConfigurationMongoConverterConfigurationAdapter.useNativeDriverJavaTimeCodecs()LoggingEventListenerMongoMappingEventApplicationContextEventSpring中文文档

Java 时间类型

我们建议使用MongoDB的原生JSR-310支持，如上所述，因为它使用基于的方法。 JSR-310 默认支持从 Spring Data Commons 继承的类型使用本地计算机时区作为参考，并且只能用于向后兼容性。MongoConverterConfigurationAdapter.useNativeDriverJavaTimeCodecs()UTCjava.timeSpring中文文档

AbstractMongoClientConfiguration创建一个实例，并将其注册到名为的容器中。MongoTemplatemongoTemplate

该属性告诉它在哪里扫描带有注释的类。base-package@org.springframework.data.mongodb.core.mapping.DocumentSpring中文文档

如果您想依靠 Spring Boot 来引导 Data MongoDB，但仍想覆盖配置的某些方面，您可能希望公开该类型的 bean。对于自定义转换，您可以例如。选择注册一个 Bean 类型，该 Bean 类型将由 Boot 基础结构选取。要了解更多信息，请务必阅读 Spring Boot 参考文档。MongoCustomConversionsSpring中文文档

1	映射基础包定义用于扫描用于预初始化 . 默认情况下，使用配置类包。`MappingContext`
2	为特定域类型配置其他自定义转换器，将这些类型的默认映射过程替换为自定义实现。

Java 时间类型

AbstractMongoClientConfiguration创建一个实例，并将其注册到名为的容器中。MongoTemplatemongoTemplate

基于元数据的映射

要充分利用Spring Data MongoDB支持中的对象映射功能，您应该使用注释对映射对象进行注释。尽管映射框架没有必要具有此注释（即使没有任何注释，您的 POJO 也会正确映射），但它允许类路径扫描程序查找并预处理您的域对象以提取必要的元数据。如果不使用此批注，则应用程序在首次存储域对象时会受到轻微的性能影响，因为映射框架需要构建其内部元数据模型，以便了解域对象的属性以及如何持久化它们。下面的示例显示了一个域对象：@DocumentSpring中文文档

例 1.示例域对象

package com.mycompany.domain;

@Document
public class Person {

  @Id
  private ObjectId id;

  @Indexed
  private Integer ssn;

  private String firstName;

  @Indexed
  private String lastName;
}

注解告诉映射器要将哪个属性用于 MongoDB 属性，注解告诉映射框架调用文档的该属性，从而加快搜索速度。仅对用 . 批注的类型进行自动索引创建。@Id_id@IndexedcreateIndex(…)@Document

默认情况下，自动索引创建处于禁用状态，需要通过配置启用（请参阅索引创建）。

映射注释概述

MappingMongoConverter 可以使用元数据来驱动对象到文档的映射。可以使用以下注释：Spring中文文档

@Id：应用于字段级别，以标记用于标识目的的字段。Spring中文文档
@MongoId：应用于字段级别，以标记用于标识目的的字段。接受自定义 id 转换的可选选项。FieldTypeSpring中文文档
@Document：在类级别应用，以指示此类是映射到数据库的候选项。您可以指定将存储数据的集合的名称。Spring中文文档
@DBRef：应用于字段以指示要使用 com.mongodb.DBRef 进行存储。Spring中文文档
@DocumentReference：应用于字段以指示将其存储为指向另一个文档的指针。这可以是单个值（默认为 id），也可以是通过转换器提供的。DocumentSpring中文文档
@Indexed：应用于字段级别，用于描述如何为字段编制索引。Spring中文文档
@CompoundIndex（可重复）：在类型级别应用于声明复合索引。Spring中文文档
@GeoSpatialIndexed：应用于字段级别，用于描述如何对字段进行地理索引。Spring中文文档
@TextIndexed：应用于字段级别，以标记要包含在文本索引中的字段。Spring中文文档
@HashIndexed：应用于字段级别，用于在哈希索引中用于跨分片集群对数据进行分区。Spring中文文档
@Language：在字段级别应用以设置文本索引的语言覆盖属性。Spring中文文档
@Transient：默认情况下，所有字段都映射到文档。此批注将应用它的字段排除在数据库中。暂时性属性不能在持久性构造函数中使用，因为转换器无法实现构造函数参数的值。Spring中文文档
@PersistenceConstructor：标记给定的构造函数 - 甚至是受包保护的构造函数 - 在从数据库实例化对象时使用。构造函数参数按名称映射到检索到的 Document 中的键值。Spring中文文档
@Value：此注解是 Spring 框架的一部分。在映射框架中，它可以应用于构造函数参数。这允许您使用 Spring Expression Language 语句来转换在数据库中检索到的键的值，然后再将其用于构造域对象。为了引用给定文档的属性，必须使用如下表达式：其中引用给定文档的根目录。@Value("#root.myProperty")rootSpring中文文档
@Field：应用于字段级别，它允许描述字段的名称和类型，因为它将在 MongoDB BSON 文档中表示，从而允许名称和类型与类的字段名称以及属性类型不同。Spring中文文档
@Version：应用于字段级别用于乐观锁定，并检查保存操作的修改。初始值为（对于基元类型），每次更新时都会自动提升。zerooneSpring中文文档

映射元数据基础结构在一个单独的 spring-data-commons 项目中定义，该项目与技术无关。 MongoDB支持中使用特定的子类来支持基于注释的元数据。如果有需求，也可以采取其他策略。Spring中文文档

下面是一个更复杂的映射示例

@Document
@CompoundIndex(name = "age_idx", def = "{'lastName': 1, 'age': -1}")
public class Person<T extends Address> {

  @Id
  private String id;

  @Indexed(unique = true)
  private Integer ssn;

  @Field("fName")
  private String firstName;

  @Indexed
  private String lastName;

  private Integer age;

  @Transient
  private Integer accountTotal;

  @DBRef
  private List<Account> accounts;

  private T address;

  public Person(Integer ssn) {
    this.ssn = ssn;
  }

  @PersistenceConstructor
  public Person(Integer ssn, String firstName, String lastName, Integer age, T address) {
    this.ssn = ssn;
    this.firstName = firstName;
    this.lastName = lastName;
    this.age = age;
    this.address = address;
  }

  public String getId() {
    return id;
  }

  // no setter for Id.  (getter is only exposed for some unit testing)

  public Integer getSsn() {
    return ssn;
  }

// other getters/setters omitted
}

@Field(targetType=…)当映射基础设施推断的原生 MongoDB 类型与预期类型不匹配时，可以派上用场。就像 for 一样，它被表示为而不是，只是因为早期版本的 MongoDB Server 不支持它。BigDecimalStringDecimal128Spring中文文档

public class Balance {

  @Field(targetType = DECIMAL128)
  private BigDecimal value;

  // ...
}

您甚至可以考虑自己的自定义注释。Spring中文文档

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Field(targetType = FieldType.DECIMAL128)
public @interface Decimal128 { }

// ...

public class Balance {

  @Decimal128
  private BigDecimal value;

  // ...
}

特殊字段名称

一般来说，MongoDB使用点（）字符作为嵌套文档或数组的路径分隔符。这意味着在查询（或更新语句）中，键（如）以对象结构为目标，如下所述：.a.b.cSpring中文文档

{
    'a' : {
        'b' : {
            'c' : …
        }
    }
}

因此，在 MongoDB 5.0 之前，字段名称不得包含点（）。
使用允许通过用另一个字符替换写入点来规避存储结构时的一些限制。.MappingMongoConverter#setMapKeyDotReplacementMapSpring中文文档

converter.setMapKeyDotReplacement("-");
// ...

source.map = Map.of("key.with.dot", "value")
converter.write(source,...) // -> map : { 'key-with-dot', 'value' }

随着 MongoDB 5.0 的发布，取消了对包含特殊字符的字段名称的限制。我们强烈建议您阅读 MongoDB 参考中有关在字段名称中使用点的限制的更多信息。
要允许在结构中使用点，请设置 .DocumentMappreserveMapKeysMappingMongoConverterSpring中文文档

使用允许自定义字段名称以以两种方式考虑点。@FieldSpring中文文档

@Field(name = "a.b")：该名称被视为路径。操作需要嵌套对象的结构，例如。{ a : { b : … } }Spring中文文档
@Field(name = "a.b", fieldNameType = KEY)：这些名称被视为按原样的名称。操作需要给定值为{ 'a.b' : ….. }Spring中文文档

由于 MongoDB 查询和 update 语句中点字符的特殊性，包含点的字段名称不能直接作为目标，因此被排除在派生查询方法之外。请考虑以下具有映射到名为的字段的属性。ItemcategoryIdcat.idSpring中文文档

public class Item {

	@Field(name = "cat.id", fieldNameType = KEY)
	String categoryId;

	// ...
}

它的原始表示将如下所示Spring中文文档

{
    'cat.id' : "5b28b5e7-52c2",
    ...
}

由于我们不能直接定位该字段（因为这会被解释为路径），因此我们需要聚合框架的帮助。cat.idSpring中文文档

查询名称中带有点的字段

template.query(Item.class)
    // $expr : { $eq : [ { $getField : { input : '$$CURRENT', 'cat.id' }, '5b28b5e7-52c2' ] }
    .matching(expr(ComparisonOperators.valueOf(ObjectOperators.getValueOf("value")).equalToValue("5b28b5e7-52c2"))) (1)
    .all();

1	映射图层负责将属性名称转换为实际字段名称。在这里使用目标字段名称也是绝对有效的。`value`

更新名称中带有点的字段

template.update(Item.class)
    .matching(where("id").is("r2d2"))
    // $replaceWith: { $setField : { input: '$$CURRENT', field : 'cat.id', value : 'af29-f87f4e933f97' } }
    .apply(AggregationUpdate.newUpdate(ReplaceWithOperation.replaceWithValue(ObjectOperators.setValueTo("value", "af29-f87f4e933f97")))) (1)
    .first();

1	映射图层负责将属性名称转换为实际字段名称。在这里使用目标字段名称也是绝对有效的。`value`

上面显示了一个简单示例，其中特殊字段存在于顶级文档级别。嵌套级别的增加增加了与字段交互所需的聚合表达式的复杂性。Spring中文文档

客制化对象构造

映射子系统允许通过使用注释注释构造函数来自定义对象构造。要用于构造函数参数的值按以下方式解析：@PersistenceConstructorSpring中文文档

如果使用注释对参数进行注释，则对给定的表达式进行计算，并将结果用作参数值。@ValueSpring中文文档
如果 Java 类型的属性的名称与输入文档的给定字段匹配，则其属性信息用于选择要将输入字段值传递到的相应构造函数参数。这仅当 java 文件中存在参数名称信息时才有效，这可以通过使用调试信息编译源代码或在 Java 8 中使用用于 javac 的新命令行开关来实现。.class-parametersSpring中文文档
否则，将抛出 a，指示无法绑定给定的构造函数参数。MappingExceptionSpring中文文档

class OrderItem {

  private @Id String id;
  private int quantity;
  private double unitPrice;

  OrderItem(String id, @Value("#root.qty ?: 0") int quantity, double unitPrice) {
    this.id = id;
    this.quantity = quantity;
    this.unitPrice = unitPrice;
  }

  // getters/setters ommitted
}

Document input = new Document("id", "4711");
input.put("unitPrice", 2.5);
input.put("qty",5);
OrderItem item = converter.read(OrderItem.class, input);

如果无法解析给定的属性路径，则参数注释中的 SpEL 表达式将回退到该值。@Valuequantity0

有关使用批注的其他示例，请参阅 MappingMongoConverterUnitTests 测试套件。@PersistenceConstructorSpring中文文档

映射框架事件

事件在映射过程的整个生命周期中触发。这在生命周期事件部分进行了介绍。Spring中文文档

在 Spring ApplicationContext 中声明这些 Bean 会导致每当调度事件时调用它们。Spring中文文档

默认情况下，自动索引创建处于禁用状态，需要通过配置启用（请参阅索引创建）。

public class Balance {

  @Field(targetType = DECIMAL128)
  private BigDecimal value;

  // ...
}

您甚至可以考虑自己的自定义注释。Spring中文文档

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Field(targetType = FieldType.DECIMAL128)
public @interface Decimal128 { }

// ...

public class Balance {

  @Decimal128
  private BigDecimal value;

  // ...
}

public class Item {

	@Field(name = "cat.id", fieldNameType = KEY)
	String categoryId;

	// ...
}

它的原始表示将如下所示Spring中文文档

{
    'cat.id' : "5b28b5e7-52c2",
    ...
}

由于我们不能直接定位该字段（因为这会被解释为路径），因此我们需要聚合框架的帮助。cat.idSpring中文文档

查询名称中带有点的字段

template.query(Item.class)
    // $expr : { $eq : [ { $getField : { input : '$$CURRENT', 'cat.id' }, '5b28b5e7-52c2' ] }
    .matching(expr(ComparisonOperators.valueOf(ObjectOperators.getValueOf("value")).equalToValue("5b28b5e7-52c2"))) (1)
    .all();

1	映射图层负责将属性名称转换为实际字段名称。在这里使用目标字段名称也是绝对有效的。`value`

更新名称中带有点的字段

template.update(Item.class)
    .matching(where("id").is("r2d2"))
    // $replaceWith: { $setField : { input: '$$CURRENT', field : 'cat.id', value : 'af29-f87f4e933f97' } }
    .apply(AggregationUpdate.newUpdate(ReplaceWithOperation.replaceWithValue(ObjectOperators.setValueTo("value", "af29-f87f4e933f97")))) (1)
    .first();

1	映射图层负责将属性名称转换为实际字段名称。在这里使用目标字段名称也是绝对有效的。`value`

上面显示了一个简单示例，其中特殊字段存在于顶级文档级别。嵌套级别的增加增加了与字段交互所需的聚合表达式的复杂性。Spring中文文档

1	映射图层负责将属性名称转换为实际字段名称。在这里使用目标字段名称也是绝对有效的。`value`

1	映射图层负责将属性名称转换为实际字段名称。在这里使用目标字段名称也是绝对有效的。`value`

如果无法解析给定的属性路径，则参数注释中的 SpEL 表达式将回退到该值。@Valuequantity0

1. 使用 UTC 区域偏移量。通过 MongoConverterConfigurationAdapter 进行配置

2. 使用 UTC 区域偏移量。通过 MongoConverterConfigurationAdapter 进行配置

对象映射基础知识

对象创建

物业人口

一般建议

覆盖属性

Kotlin 支持

Kotlin 对象创建

Kotlin 数据类的属性填充

Kotlin 覆盖属性

Kotlin 值类

基于约定的映射

如何在映射图层中处理字段。_id

数据映射和类型转换

映射配置

基于元数据的映射

映射注释概述

特殊字段名称

客制化对象构造

映射框架事件

如何在映射图层中处理字段。`_id`