最新的稳定版请使用 Spring Data MongoDB 4.3.1! |
最新的稳定版请使用 Spring Data MongoDB 4.3.1! |
丰富的映射支持由 .
转换器包含一个元数据模型,该模型提供完整的功能集,用于将域对象映射到 MongoDB 文档。
映射元数据模型是通过在域对象上使用注释来填充的。
但是,基础结构并不局限于使用注释作为元数据信息的唯一来源。
还允许您按照一组约定将对象映射到文档,而无需提供任何其他元数据。MappingMongoConverter
MappingMongoConverter
本节介绍 的功能,包括基础知识、如何使用约定将对象映射到文档,以及如何使用基于注释的映射元数据覆盖这些约定。MappingMongoConverter
对象映射基础知识
本节介绍了 Spring Data 对象映射、对象创建、字段和属性访问、可变性和不可变性的基础知识。 请注意,本节仅适用于不使用底层数据存储(如 JPA)的对象映射的 Spring Data 模块。 此外,请务必查阅特定于存储的部分,了解特定于存储的对象映射,例如索引、自定义列或字段名称等。
Spring Data 对象映射的核心职责是创建域对象的实例,并将存储原生数据结构映射到这些实例上。 这意味着我们需要两个基本步骤:
-
使用公开的构造函数之一创建实例。
-
实例填充,用于具体化所有公开的属性。
对象创建
Spring Data 会自动尝试检测用于具体化该类型对象的持久实体的构造函数。 解析算法的工作原理如下:
-
如果有一个静态工厂方法注释,则使用它。
@PersistenceCreator
-
如果存在单个构造函数,则使用该构造函数。
-
如果有多个构造函数,并且恰好有一个构造函数用 注释,则使用它。
@PersistenceCreator
-
如果类型是 Java,则使用规范构造函数。
Record
-
如果存在无参数构造函数,则使用它。 其他构造函数将被忽略。
值解析假定构造函数/工厂方法参数名称与实体的属性名称匹配,即解析将像填充属性一样执行,包括映射中的所有自定义项(不同的数据存储列或字段名称等)。
这还需要类文件中提供的参数名称信息或构造函数上存在的注释。@ConstructorProperties
可以使用 Spring Framework 的值注释和特定于存储的 SpEL 表达式来自定义值解析。
有关更多详细信息,请参阅有关商店特定映射的部分。@Value
物业人口
创建实体的实例后,Spring Data 将填充该类的所有剩余持久属性。 除非已由实体的构造函数填充(即通过其构造函数参数列表使用),否则将首先填充标识符属性以允许解析循环对象引用。 之后,将在实体实例上设置尚未由构造函数填充的所有非暂时性属性。 为此,我们使用以下算法:
-
如果属性是不可变的,但公开了一个方法(见下文),我们将使用该方法创建一个具有新属性值的新实体实例。
with…
with…
-
如果定义了属性访问(即通过 getter 和 setter 的访问),我们将调用 setter 方法。
-
如果属性是可变的,我们直接设置字段。
-
如果该属性是不可变的,我们将使用持久性操作使用的构造函数(请参阅对象创建)来创建实例的副本。
-
默认情况下,我们直接设置字段值。
让我们看一下以下实体:
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)实际上是一个复制构造函数,并且设置属性将转换为使用应用新标识符值创建新实例。null withId(…) Person |
2 | 和 属性是可能通过 getter 公开的普通不可变属性。firstname lastname |
3 | 该属性是不可变的,但派生自该属性。
在所示的设计中,数据库值将优先于默认值,因为 Spring Data 使用唯一声明的构造函数。
即使意图是计算应该是首选,也很重要的是,此构造函数也必须将其作为参数(以可能忽略它),否则属性填充步骤将尝试设置年龄字段并失败,因为它是不可变的,并且不存在任何方法。age birthday age with… |
4 | 该属性是可变的,通过直接设置其字段来填充。comment |
5 | 该属性是可变的,并通过调用 setter 方法进行填充。remarks |
6 | 该类公开用于创建对象的工厂方法和构造函数。
这里的核心思想是使用工厂方法而不是其他构造函数,以避免需要通过 来消除构造函数的歧义。
相反,属性的默认值是在工厂方法中处理的。
如果希望 Spring Data 使用工厂方法进行对象实例化,请使用 .@PersistenceCreator @PersistenceCreator |
一般建议
-
尝试坚持使用不可变对象 — 不可变对象很容易创建,因为具体化对象只需调用其构造函数即可。 此外,这样还可以避免域对象充斥着允许客户端代码操作对象状态的 setter 方法。 如果需要这些,最好将它们设置为包保护,以便它们只能由有限数量的共置类型调用。 仅构造函数的实现速度比属性填充快 30%。
-
提供 all-args 构造函数 — 即使不能或不想将实体建模为不可变值,提供将实体的所有属性作为参数(包括可变属性)的构造函数仍然有价值,因为这允许对象映射跳过属性填充以获得最佳性能。
-
使用工厂方法而不是重载构造函数来避免
@PersistenceCreator
— 由于需要全参数构造函数来获得最佳性能,我们通常希望公开更多特定于应用程序用例的构造函数,这些构造函数省略了自动生成的标识符等内容。 使用静态工厂方法来公开 all-args 构造函数的这些变体是一种既定模式。 -
确保遵守允许使用生成的实例化器和属性访问器类的约束 —
-
对于要生成的标识符,仍将 final 字段与全参数持久性构造函数(首选)或
with...
方法结合使用 — -
使用 Lombok 来避免样板代码 — 由于持久化操作通常需要构造函数获取所有参数,因此它们的声明会成为对字段赋值的样板参数的乏味重复,而使用 Lombok 的 .
@AllArgsConstructor
覆盖属性
Java 允许灵活地设计域类,其中子类可以定义已在其超类中声明的相同名称的属性。 请看以下示例:
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 会跳过超类型属性。
也就是说,重写属性的类型必须可分配给其超类型属性类型才能注册为重写,否则超类型属性将被视为瞬态属性。
我们通常建议使用不同的属性名称。field
SubType
SuperType.field
SuperType.field
super.setField(…)
field
SuperType
Spring Data 模块通常支持包含不同值的覆盖属性。 从编程模型的角度来看,有几件事需要考虑:
-
应保留哪个属性(默认为所有声明的属性)? 您可以通过使用 对属性进行批注来排除这些属性。
@Transient
-
如何表示数据存储中的属性? 对不同的值使用相同的字段/列名称通常会导致数据损坏,因此应使用显式字段/列名称至少批注一个属性。
-
不能使用,因为通常不能在不对 setter 实现进行任何进一步假设的情况下设置超属性。
@AccessType(PROPERTY)
Kotlin 支持
Spring Data 调整了 Kotlin 的细节,以允许对象创建和更改。
Kotlin 对象创建
支持实例化 Kotlin 类,默认情况下所有类都是不可变的,并且需要显式属性声明来定义可变属性。
Spring Data 会自动尝试检测用于具体化该类型对象的持久实体的构造函数。 解析算法的工作原理如下:
-
如果存在用 注释的构造函数,则使用该构造函数。
@PersistenceCreator
-
如果类型是 Kotlin 数据类,则使用主构造函数。
-
如果有一个静态工厂方法注释,则使用它。
@PersistenceCreator
-
如果存在单个构造函数,则使用该构造函数。
-
如果有多个构造函数,并且恰好有一个构造函数用 注释,则使用它。
@PersistenceCreator
-
如果类型是 Java,则使用规范构造函数。
Record
-
如果存在无参数构造函数,则使用它。 其他构造函数将被忽略。
考虑以下类:data
Person
data class Person(val id: String, val name: String)
上面的类编译为具有显式构造函数的典型类。我们可以通过添加另一个构造函数来自定义这个类,并用它进行注释以指示构造函数首选项:@PersistenceCreator
data class Person(var id: String, val name: String) {
@PersistenceCreator
constructor(id: String) : this(id, "unknown")
}
Kotlin 支持参数可选性,允许在未提供参数时使用默认值。
当 Spring Data 检测到参数默认值的构造函数时,如果数据存储没有提供值(或只是返回),则这些参数不存在,因此 Kotlin 可以应用参数默认值。请考虑以下应用参数默认值的类null
name
data class Person(var id: String, val name: String = "unknown")
每当参数不是结果的一部分或其值为 时,默认值为 。name
null
name
unknown
Kotlin 数据类的属性填充
在 Kotlin 中,默认情况下所有类都是不可变的,并且需要显式属性声明来定义可变属性。
考虑以下类:data
Person
data class Person(val id: String, val name: String)
此类实际上是不可变的。
它允许创建新实例,因为 Kotlin 会生成一个创建新对象实例的方法,从现有对象复制所有属性值,并将作为参数提供的属性值应用于该方法。copy(…)
Kotlin 覆盖属性
Kotlin 允许声明属性覆盖以更改子类中的属性。
open class SuperType(open var field: Int)
class SubType(override var field: Int = 1) :
SuperType(field) {
}
这样的排列呈现两个名称为 的属性。
Kotlin 为每个类中的每个属性生成属性访问器(getter 和 setter)。
实际上,代码如下所示:field
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 的方法,但超出了支持的约定。
属性重写在某种程度上会产生冲突,因为属性共享相同的名称,但可能表示两个不同的值。
我们通常建议使用不同的属性名称。SubType
SubType.field
SuperType.field
SuperType.field
SubType
SuperType.field
this.SuperType.field = …
Spring Data 模块通常支持包含不同值的覆盖属性。 从编程模型的角度来看,有几件事需要考虑:
-
应保留哪个属性(默认为所有声明的属性)? 您可以通过使用 对属性进行批注来排除这些属性。
@Transient
-
如何表示数据存储中的属性? 对不同的值使用相同的字段/列名称通常会导致数据损坏,因此应使用显式字段/列名称至少批注一个属性。
-
不能使用,因为无法设置超级属性。
@AccessType(PROPERTY)
Kotlin 值类
Kotlin 值类专为更具表现力的领域模型而设计,以明确基本概念。 Spring Data 可以读取和写入使用值类定义属性的类型。
请考虑以下域模型:
@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 使用字段访问来读取和写入属性值。根据字段的可见性规则,用于与字段交互。private MethodHandles |
3 | 该类公开用于设置标识符的方法,例如,当实例插入数据存储并生成标识符时。调用将创建一个新对象。所有后续突变都将在新实例中发生,而前一个实例保持不变。withId(…) withId(…) Person |
4 | 使用属性访问允许直接调用方法,而无需使用 。MethodHandles |
1 | 标识符属性是最终属性,但在构造函数中设置为。
该类公开用于设置标识符的方法,例如,当实例插入数据存储并生成标识符时。
创建新实例时,原始实例保持不变。
相同的模式通常应用于存储管理的其他属性,但可能需要更改持久性操作。
wither 方法是可选的,因为持久性构造函数(参见 6)实际上是一个复制构造函数,并且设置属性将转换为使用应用新标识符值创建新实例。null withId(…) Person |
2 | 和 属性是可能通过 getter 公开的普通不可变属性。firstname lastname |
3 | 该属性是不可变的,但派生自该属性。
在所示的设计中,数据库值将优先于默认值,因为 Spring Data 使用唯一声明的构造函数。
即使意图是计算应该是首选,也很重要的是,此构造函数也必须将其作为参数(以可能忽略它),否则属性填充步骤将尝试设置年龄字段并失败,因为它是不可变的,并且不存在任何方法。age birthday age with… |
4 | 该属性是可变的,通过直接设置其字段来填充。comment |
5 | 该属性是可变的,并通过调用 setter 方法进行填充。remarks |
6 | 该类公开用于创建对象的工厂方法和构造函数。
这里的核心思想是使用工厂方法而不是其他构造函数,以避免需要通过 来消除构造函数的歧义。
相反,属性的默认值是在工厂方法中处理的。
如果希望 Spring Data 使用工厂方法进行对象实例化,请使用 .@PersistenceCreator @PersistenceCreator |
1 | 具有不可为 null 值类型的简单值类。 |
2 | 数据类使用 value 类定义属性。EmailAddress |
使用非基元值类型的不可为 null 属性在 compiled 类中展平为值类型。 可为 null 的基元值类型或可为 null 的值中值类型用其包装器类型表示,这会影响值类型在数据库中的表示方式。 |
基于约定的映射
MappingMongoConverter
有一些约定,用于在未提供其他映射元数据时将对象映射到文档。
约定是:
-
短 Java 类名按以下方式映射到集合名称。 该类映射到集合名称。
com.bigbank.SavingsAccount
savingsAccount
-
所有嵌套对象都作为嵌套对象存储在文档中,而不是作为 DBRefs。
-
转换器使用在其注册的任何 Spring Converter 来覆盖对象属性到文档字段和值的默认映射。
-
对象的字段用于在文档中的字段之间进行转换。 不使用公共属性。
JavaBean
-
如果有一个非零参数构造函数,其构造函数参数名称与文档的顶级字段名称匹配,则使用该构造函数。否则,将使用零参数构造函数。如果存在多个非零参数构造函数,则会引发异常。
如何在映射图层中处理字段。_id
MongoDB要求你有一个所有文档的字段。如果未提供,驱动程序将分配具有生成值的 ObjectId。该字段可以是除数组以外的任何类型,只要它是唯一的。驱动程序自然支持所有基元类型和 Dates。使用 时,有一些规则来控制如何将 Java 类中的属性映射到字段。_id
_id
MappingMongoConverter
_id
下面概述了将映射到文档字段的字段:_id
-
用 () 注释的字段将映射到该字段。
此外,可以通过注释自定义文档字段的名称,在这种情况下,文档将不包含字段。@Id
org.springframework.data.annotation.Id
_id
@Field
_id
-
没有注释但已命名的字段将映射到该字段。
id
_id
字段定义 | MongoDB 中生成的 id-fieldname |
---|---|
|
|
|
|
|
|
|
|
|
|
下面概述了将对映射到 _id 文档字段的属性执行的类型转换(如果有)。
-
如果在 Java 类中将 Named 字段声明为 String 或 BigInteger,则如果可能,它将转换为 ObjectId 并存储为 ObjectId。 ObjectId 作为字段类型也有效。 如果在应用程序中指定值,则 MongoDB 驱动程序将完成到 ObjectId 的转换。 如果指定的值无法转换为 ObjectId,则该值将按原样存储在文档的字段中。 如果字段使用 注释,这也适用。
id
id
id
_id
@Id
-
如果一个字段在 Java 类中被注释,它将被转换为并使用其实际类型进行存储。 除非声明所需的字段类型,否则不会发生进一步的转换。 如果未为该字段提供任何值,则将创建一个新字段并将其转换为属性类型。
@MongoId
@MongoId
id
ObjectId
-
如果在 Java 类中注释了字段,则将尝试将该值转换为声明的 。 如果未为该字段提供任何值,则将创建一个新字段并将其转换为声明的类型。
@MongoId(FieldType.…)
FieldType
id
ObjectId
-
如果 Java 类中未将 Named 声明为 String、BigInteger 或 ObjectID,则应在应用程序中为其分配一个值,以便它可以“按原样”存储在文档的字段中。
id
_id
-
如果 Java 类中不存在命名的字段,则驱动程序将生成一个隐式文件,但不会映射到 Java 类的属性或字段。
id
_id
查询和更新时,将使用转换器处理与上述保存文档规则相对应的 和 对象的转换,以便查询中使用的字段名称和类型能够与域类中的内容匹配。MongoTemplate
Query
Update
字段定义 | MongoDB 中生成的 id-fieldname |
---|---|
|
|
|
|
|
|
|
|
|
|
数据映射和类型转换
Spring Data MongoDB支持所有可以表示为BSON(MongoDB的内部文档格式)的类型。 除了这些类型之外,Spring Data MongoDB还提供了一组内置转换器来映射其他类型。 您可以提供自己的转换器来调整类型转换。 有关更多详细信息,请参阅自定义转换 - 覆盖默认映射。
内置类型转换:
类型 | 类型转换 | 样本 |
---|---|---|
|
本地 |
|
|
本地 |
|
|
本机 |
|
|
本机 |
|
|
本地 |
|
|
本地 |
|
|
本地 |
|
|
本地 |
|
|
本地 |
|
数组 |
本地 |
|
|
本地 |
|
|
本地 |
|
|
本地 |
|
|
本地 |
|
|
转换器 |
|
|
转换器 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
本地 |
|
|
转炉 |
|
|
转换器 / 原生 (Java8)[1] |
|
|
转换器 / 原生 (Java8)[2] |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
集合处理
集合处理取决于 MongoDB 返回的实际值。
通常,如果使用构造函数创建,则可以获取要设置的值。 如果查询响应未提供属性值,则属性填充可以使用默认初始化值。 |
类型 | 类型转换 | 样本 |
---|---|---|
|
本地 |
|
|
本地 |
|
|
本机 |
|
|
本机 |
|
|
本地 |
|
|
本地 |
|
|
本地 |
|
|
本地 |
|
|
本地 |
|
数组 |
本地 |
|
|
本地 |
|
|
本地 |
|
|
本地 |
|
|
本地 |
|
|
转换器 |
|
|
转换器 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
本地 |
|
|
转炉 |
|
|
转换器 / 原生 (Java8)[1] |
|
|
转换器 / 原生 (Java8)[2] |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
|
转炉 |
|
集合处理
集合处理取决于 MongoDB 返回的实际值。
通常,如果使用构造函数创建,则可以获取要设置的值。 如果查询响应未提供属性值,则属性填充可以使用默认初始化值。 |
映射配置
除非显式配置,否则在创建 .
您可以创建自己的 .
这样做可以让你指定在类路径中的位置可以找到你的领域类,以便Spring Data MongoDB可以提取元数据并构建索引。
此外,通过创建自己的实例,您可以注册 Spring 转换器以将特定类映射到数据库或从数据库映射特定类。MappingMongoConverter
MongoTemplate
MappingMongoConverter
您可以使用基于 Java 或基于 XML 的元数据来配置 well 和 MongoTemplate。
以下示例显示了配置:MappingMongoConverter
com.mongodb.client.MongoClient
-
Java
-
XML
@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.MongoClient
AbstractMongoClientConfiguration
getMappingBasePackage(…)
@Document
您可以通过重写该方法将其他转换器添加到转换器中。
MongoDB 的原生 JSR-310 支持可以通过 启用。
前面的示例中还显示了一个 ,它记录了发布到 Spring 基础结构上的实例。customConversionsConfiguration
MongoConverterConfigurationAdapter.useNativeDriverJavaTimeCodecs()
LoggingEventListener
MongoMappingEvent
ApplicationContextEvent
Java 时间类型
我们建议使用MongoDB的原生JSR-310支持,如上所述,因为它使用基于的方法。
JSR-310 默认支持从 Spring Data Commons 继承的类型使用本地计算机时区作为参考,并且只能用于向后兼容性。 |
AbstractMongoClientConfiguration 创建一个实例,并将其注册到名为 的容器中。MongoTemplate mongoTemplate |
该属性告诉它在哪里扫描带有注释的类。base-package
@org.springframework.data.mongodb.core.mapping.Document
如果您想依靠 Spring Boot 来引导 Data MongoDB,但仍想覆盖配置的某些方面,您可能希望公开该类型的 bean。
对于自定义转换,您可以例如。选择注册一个 Bean 类型,该 Bean 类型将由 Boot 基础结构选取。
要了解更多信息,请务必阅读 Spring Boot 参考文档。 |
1 | 映射基础包定义用于扫描用于预初始化 .
默认情况下,使用配置类包。MappingContext |
2 | 为特定域类型配置其他自定义转换器,将这些类型的默认映射过程替换为自定义实现。 |
Java 时间类型
我们建议使用MongoDB的原生JSR-310支持,如上所述,因为它使用基于的方法。
JSR-310 默认支持从 Spring Data Commons 继承的类型使用本地计算机时区作为参考,并且只能用于向后兼容性。 |
AbstractMongoClientConfiguration 创建一个实例,并将其注册到名为 的容器中。MongoTemplate mongoTemplate |
如果您想依靠 Spring Boot 来引导 Data MongoDB,但仍想覆盖配置的某些方面,您可能希望公开该类型的 bean。
对于自定义转换,您可以例如。选择注册一个 Bean 类型,该 Bean 类型将由 Boot 基础结构选取。
要了解更多信息,请务必阅读 Spring Boot 参考文档。 |
基于元数据的映射
要充分利用Spring Data MongoDB支持中的对象映射功能,您应该使用注释对映射对象进行注释。
尽管映射框架没有必要具有此注释(即使没有任何注释,您的 POJO 也会正确映射),但它允许类路径扫描程序查找并预处理您的域对象以提取必要的元数据。
如果不使用此批注,则应用程序在首次存储域对象时会受到轻微的性能影响,因为映射框架需要构建其内部元数据模型,以便了解域对象的属性以及如何持久化它们。
下面的示例显示了一个域对象:@Document
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 @Indexed createIndex(…) @Document |
默认情况下,自动索引创建处于禁用状态,需要通过配置启用(请参阅索引创建)。 |
映射注释概述
MappingMongoConverter 可以使用元数据来驱动对象到文档的映射。 可以使用以下注释:
-
@Id
:应用于字段级别,以标记用于标识目的的字段。 -
@MongoId
:应用于字段级别,以标记用于标识目的的字段。 接受自定义 id 转换的可选选项。FieldType
-
@Document
:在类级别应用,以指示此类是映射到数据库的候选项。 您可以指定将存储数据的集合的名称。 -
@DBRef
:应用于字段以指示要使用 com.mongodb.DBRef 进行存储。 -
@DocumentReference
:应用于字段以指示将其存储为指向另一个文档的指针。 这可以是单个值(默认为 id),也可以是通过转换器提供的。Document
-
@Indexed
:应用于字段级别,用于描述如何为字段编制索引。 -
@CompoundIndex
(可重复):在类型级别应用于声明复合索引。 -
@GeoSpatialIndexed
:应用于字段级别,用于描述如何对字段进行地理索引。 -
@TextIndexed
:应用于字段级别,以标记要包含在文本索引中的字段。 -
@HashIndexed
:应用于字段级别,用于在哈希索引中用于跨分片集群对数据进行分区。 -
@Language
:在字段级别应用以设置文本索引的语言覆盖属性。 -
@Transient
:默认情况下,所有字段都映射到文档。 此批注将应用它的字段排除在数据库中。 暂时性属性不能在持久性构造函数中使用,因为转换器无法实现构造函数参数的值。 -
@PersistenceConstructor
:标记给定的构造函数 - 甚至是受包保护的构造函数 - 在从数据库实例化对象时使用。 构造函数参数按名称映射到检索到的 Document 中的键值。 -
@Value
:此注解是 Spring 框架的一部分。在映射框架中,它可以应用于构造函数参数。 这允许您使用 Spring Expression Language 语句来转换在数据库中检索到的键的值,然后再将其用于构造域对象。 为了引用给定文档的属性,必须使用如下表达式: 其中引用给定文档的根目录。@Value("#root.myProperty")
root
-
@Field
:应用于字段级别,它允许描述字段的名称和类型,因为它将在 MongoDB BSON 文档中表示,从而允许名称和类型与类的字段名称以及属性类型不同。 -
@Version
:应用于字段级别用于乐观锁定,并检查保存操作的修改。 初始值为 (对于基元类型),每次更新时都会自动提升。zero
one
映射元数据基础结构在一个单独的 spring-data-commons 项目中定义,该项目与技术无关。 MongoDB支持中使用特定的子类来支持基于注释的元数据。 如果有需求,也可以采取其他策略。
下面是一个更复杂的映射示例
@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
}
您甚至可以考虑自己的自定义注释。
|
特殊字段名称
一般来说,MongoDB使用点()字符作为嵌套文档或数组的路径分隔符。
这意味着在查询(或更新语句)中,键(如)以对象结构为目标,如下所述:.
a.b.c
{
'a' : {
'b' : {
'c' : …
}
}
}
因此,在 MongoDB 5.0 之前,字段名称不得包含点 ()。
使用允许通过用另一个字符替换写入点来规避存储结构时的一些限制。.
MappingMongoConverter#setMapKeyDotReplacement
Map
converter.setMapKeyDotReplacement("-");
// ...
source.map = Map.of("key.with.dot", "value")
converter.write(source,...) // -> map : { 'key-with-dot', 'value' }
随着 MongoDB 5.0 的发布,取消了对包含特殊字符的字段名称的限制。
我们强烈建议您阅读 MongoDB 参考中有关在字段名称中使用点的限制的更多信息。
要允许在结构中使用点,请设置 .Document
Map
preserveMapKeys
MappingMongoConverter
使用允许自定义字段名称以以两种方式考虑点。@Field
-
@Field(name = "a.b")
:该名称被视为路径。 操作需要嵌套对象的结构,例如 。{ a : { b : … } }
-
@Field(name = "a.b", fieldNameType = KEY)
:这些名称被视为按原样的名称。 操作需要给定值为{ 'a.b' : ….. }
由于 MongoDB 查询和 update 语句中点字符的特殊性,包含点的字段名称不能直接作为目标,因此被排除在派生查询方法之外。
请考虑以下具有映射到名为 的字段的属性。
它的原始表示将如下所示
由于我们不能直接定位该字段(因为这会被解释为路径),因此我们需要聚合框架的帮助。 查询名称中带有点的字段
更新名称中带有点的字段
上面显示了一个简单示例,其中特殊字段存在于顶级文档级别。 嵌套级别的增加增加了与字段交互所需的聚合表达式的复杂性。 |
客制化对象构造
映射子系统允许通过使用注释注释构造函数来自定义对象构造。
要用于构造函数参数的值按以下方式解析:@PersistenceConstructor
-
如果使用注释对参数进行注释,则对给定的表达式进行计算,并将结果用作参数值。
@Value
-
如果 Java 类型的属性的名称与输入文档的给定字段匹配,则其属性信息用于选择要将输入字段值传递到的相应构造函数参数。 这仅当 java 文件中存在参数名称信息时才有效,这可以通过使用调试信息编译源代码或在 Java 8 中使用用于 javac 的新命令行开关来实现。
.class
-parameters
-
否则,将抛出 a,指示无法绑定给定的构造函数参数。
MappingException
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 表达式将回退到该值。@Value quantity 0 |
有关使用批注的其他示例,请参阅 MappingMongoConverterUnitTests 测试套件。@PersistenceConstructor
注解告诉映射器要将哪个属性用于 MongoDB 属性,注解告诉映射框架调用文档的该属性,从而加快搜索速度。
仅对用 . 批注的类型进行自动索引创建。@Id _id @Indexed createIndex(…) @Document |
默认情况下,自动索引创建处于禁用状态,需要通过配置启用(请参阅索引创建)。 |
您甚至可以考虑自己的自定义注释。
|
由于 MongoDB 查询和 update 语句中点字符的特殊性,包含点的字段名称不能直接作为目标,因此被排除在派生查询方法之外。
请考虑以下具有映射到名为 的字段的属性。
它的原始表示将如下所示
由于我们不能直接定位该字段(因为这会被解释为路径),因此我们需要聚合框架的帮助。 查询名称中带有点的字段
更新名称中带有点的字段
上面显示了一个简单示例,其中特殊字段存在于顶级文档级别。 嵌套级别的增加增加了与字段交互所需的聚合表达式的复杂性。 |
1 | 映射图层负责将属性名称转换为实际字段名称。
在这里使用目标字段名称也是绝对有效的。value |
1 | 映射图层负责将属性名称转换为实际字段名称。
在这里使用目标字段名称也是绝对有效的。value |
如果无法解析给定的属性路径,则参数注释中的 SpEL 表达式将回退到该值。@Value quantity 0 |