跳到主要内容
版本:6.1.1

实体建模

Doubao 中英对照 Modeling Entities

本章介绍如何对实体建模,并说明这些实体在 Couchbase Server 中对应的表示形式。

对象映射基础​

本节介绍 Spring Data 对象映射的基础知识,包括对象创建、字段与属性访问、可变性与不可变性。请注意,本节仅适用于不使用底层数据存储对象映射的 Spring Data 模块(如 JPA)。另外,请务必查阅特定存储部分,以了解特定存储的对象映射,例如索引、列名或字段名的自定义等。

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

  1. 通过使用所暴露的某个构造函数来创建实例。

  2. 实例填充,以具体化所有暴露的属性。

对象创建​

Spring Data 会自动尝试检测持久化实体的构造函数,用于具体化该类型的对象。解析算法的工作方式如下:

  1. 如果存在唯一一个标注了 @PersistenceCreator 的静态工厂方法,则使用它。

  2. 如果只有一个构造函数,则使用它。

  3. 如果存在多个构造函数,且恰好有一个标注了 @PersistenceCreator,则使用它。

  4. 如果该类型是 Java Record,则使用规范构造函数。

  5. 如果存在无参构造函数,则使用它。其他构造函数将被忽略。

值解析假定构造函数/工厂方法的参数名与实体的属性名相匹配,也就是说,解析过程会像要填充该属性一样进行,包括映射中的所有自定义设置(不同的数据存储列名或字段名等)。这还要求类文件中包含参数名信息,或者构造函数上存在 @ConstructorProperties 注解。

值解析可以通过使用 Spring Framework 的 @Value 注解并配合特定存储的 SpEL 表达式来自定义。有关更多详细信息,请参阅特定存储映射一节。

Object creation internals

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

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

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

属性填充​

一旦创建了实体实例,Spring Data 就会填充该类所有剩余的持久化属性。除非已经由实体构造函数填充过(即通过其构造函数参数列表消耗掉),否则会先填充标识符属性,以便解析循环对象引用。此后,所有尚未由构造函数填充的非瞬态属性都会被设置到实体实例上。为此,我们使用以下算法:

  1. 如果属性是不可变的,但暴露了 with… 方法(见下文),我们会使用该 with… 方法创建一个带有新属性值的新实体实例。

  2. 如果定义了属性访问(即通过 getter 和 setter 访问),我们会调用 setter 方法。

  3. 如果属性是可变的,我们直接设置该字段。

  4. 如果属性是不可变的,我们会使用持久化操作所用的构造函数(请参阅 对象创建)创建该实例的副本。

  5. 默认情况下,我们直接设置字段值。

Property population internals

Similarly to our optimizations in object construction 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.lastname);
}

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
}
}
}
  • PropertyAccessor’s hold a mutable instance of the underlying object. This is, to enable mutations of otherwise immutable properties.

  • 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.

  • 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 Person object. All subsequent mutations will take place in the new instance leaving the previous untouched.

  • Using property-access allows direct method invocations without using MethodHandles.

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.

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

让我们看一下下面这个实体:

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
private @Transient String summary; 6

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

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

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

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;
}
}
  • 标识符属性是 final 的,但在构造函数中被设为 null。该类暴露了一个 withId(…) 方法,用于设置标识符,例如当一个实例被插入数据存储并已生成标识符时。由于会创建一个新实例,原始的 Person 实例保持不变。对于其他由存储管理、但可能需要在持久化操作中更改的属性,通常也采用同样的模式。wither 方法是可选的,因为持久化构造函数(见 6)实际上是一个复制构造函数,设置该属性会被转换为创建一个应用了新标识符值的全新实例。

  • firstname 和 lastname 属性是普通的不可变属性,可能通过 getter 暴露。

  • age 属性是不可变的,但它是由 birthday 属性派生而来。在所示的设计中,由于 Spring Data 使用唯一声明的构造函数,数据库中的值会优先于默认值。即使本意是优先采用计算值,也必须让该构造函数同时接受 age 参数(以便可能忽略它),否则属性填充步骤会尝试设置 age 字段,并由于该字段不可变且没有 with… 方法而失败。

  • comment 属性是可变的,通过直接设置其字段来填充。

  • remarks 属性是可变的,通过调用 setter 方法来填充。

  • summary 属性是瞬态的,由于标注了 @Transient,它不会被持久化。Spring Data 不使用 Java 的 transient 关键字来排除属性的持久化,因为 transient 是 Java 序列化框架的一部分。请注意,该属性可以配合持久化构造函数使用,但其值将默认为 null(如果属性类型是基本类型,则为相应的基本类型初始值)。

  • 该类暴露了一个工厂方法和一个构造函数用于对象创建。这里的核心思想是使用工厂方法而非额外的构造函数,以避免通过 @PersistenceCreator 进行构造函数消歧。取而代之的是,属性的默认值在工厂方法内部处理。如果您希望 Spring Data 使用该工厂方法进行对象实例化,请用 @PersistenceCreator 标注它。

通用建议​

  • 尽量坚持使用不可变对象 — 不可变对象创建起来很直接,因为具体化一个对象只需调用其构造函数即可。此外,这还避免了在领域对象上散布 setter 方法(这些方法会让客户端代码操纵对象状态)。如果确实需要 setter,最好将其设为包级保护,使其只能被有限的同包类型调用。仅通过构造函数具体化对象比属性填充快达 30%。

  • 提供全参构造函数 — 即使您不能或不想将实体建模为不可变值,提供一个接收实体所有属性(包括可变属性)作为参数的构造函数仍然是有价值的,因为这能让对象映射跳过属性填充,从而获得最佳性能。

  • 使用工厂方法而非重载构造函数,以避免 @PersistenceCreator — 为获得最佳性能而需要全参构造函数时,我们通常还希望暴露更多针对应用用例、省略自动生成标识符等内容的构造函数。一个成熟的做法是改用静态工厂方法来暴露这些全参构造函数的变体。

  • 确保遵守那些允许使用生成的实例化器和属性访问器类的约束 —

  • 对于要生成的标识符,仍应使用 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);
}
}

两个类都使用可赋值类型定义了 field。然而 SubType 遮蔽了 SuperType.field。根据类设计的不同,使用构造函数可能是设置 SuperType.field 的唯一默认方式。或者,在 setter 中调用 super.setField(…) 也可以设置 SuperType 中的 field。所有这些机制在某种程度上都会产生冲突,因为这些属性同名,却可能代表两个不同的值。如果类型不可赋值,Spring Data 会跳过超类属性。也就是说,被覆盖属性的类型必须能够赋值给其超类属性的类型,才会被注册为覆盖;否则该超类属性会被视为瞬态。我们通常建议使用不同的属性名。

Spring Data 各模块通常支持持有不同值的被覆盖属性。从编程模型的角度来看,有以下几点需要考虑:

  1. 应当持久化哪个属性(默认为所有已声明的属性)?您可以通过用 @Transient 标注属性来将其排除。

  2. 如何在数据存储中表示这些属性?对不同的值使用相同的字段/列名通常会导致数据损坏,因此您至少应当用显式的字段/列名标注其中一个属性。

  3. 不能使用 @AccessType(PROPERTY),因为在不对 setter 实现做进一步假设的情况下,通常无法设置该超类属性。

Kotlin 支持​

Spring Data 适配了 Kotlin 的特性,以支持对象创建与变更。

Kotlin 对象创建​

Spring Data 支持实例化 Kotlin 类。Kotlin 中所有类默认都是不可变的,需要显式声明属性才能定义可变属性。

Spring Data 会自动尝试检测持久化实体的构造函数,用于具体化该类型的对象。解析算法的工作方式如下:

  1. 如果存在一个标注了 @PersistenceCreator 的构造函数,则使用它。

  2. 如果该类型是 Kotlin 数据类,则使用主构造函数。

  3. 如果存在唯一一个标注了 @PersistenceCreator 的静态工厂方法,则使用它。

  4. 如果只有一个构造函数,则使用它。

  5. 如果存在多个构造函数,且恰好有一个标注了 @PersistenceCreator,则使用它。

  6. 如果该类型是 Java Record,则使用规范构造函数。

  7. 如果存在无参构造函数,则使用它。其他构造函数将被忽略。

请看下述 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 检测到一个带有参数默认值的构造函数时,如果数据存储未提供值(或直接返回 null),它会让这些参数缺席,以便 Kotlin 应用参数默认值。请看下述为 name 应用参数默认值的类:

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

每当 name 参数不在结果中、或其值为 null 时,name 都会默认为 unknown。

备注

Spring Data 不支持委托属性。映射元数据会为 Kotlin 数据类过滤委托属性。在所有其他情况下,您可以通过用 @Transient 标注属性来排除委托属性的合成字段。

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) {
}

这样的安排会产生两个名为 field 的属性。Kotlin 会为每个类中的每个属性生成属性访问器(getter 和 setter)。实际上,代码如下所示:

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

SubType 上的 getter 和 setter 只会设置 SubType.field,而不会设置 SuperType.field。在这样的安排中,使用构造函数是设置 SuperType.field 的唯一默认方式。向 SubType 添加一个通过 this.SuperType.field = … 来设置 SuperType.field 的方法虽然可行,但超出了受支持的约定范围。属性覆盖在某种程度上会产生冲突,因为这些属性同名,却可能代表两个不同的值。我们通常建议使用不同的属性名。

Spring Data 各模块通常支持持有不同值的被覆盖属性。从编程模型的角度来看,有以下几点需要考虑:

  1. 应当持久化哪个属性(默认为所有已声明的属性)?您可以通过用 @Transient 标注属性来将其排除。

  2. 如何在数据存储中表示这些属性?对不同的值使用相同的字段/列名通常会导致数据损坏,因此您至少应当用显式的字段/列名标注其中一个属性。

  3. 不能使用 @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
  • 一个带有非空值类型的简单值类。

  • 使用 EmailAddress 值类定义属性的数据类。

备注

使用非基本类型值类型的非空属性,在编译后的类中会被扁平化处理为该值类型。可空的基本类型值类型或可空的“值中值”类型会用其包装类型表示,这会影响值类型在数据库中的表示方式。

文档与字段​

所有实体都应当标注 @Document 注解,但这并非必需。

此外,实体中的每个字段都应当标注 @Field 注解。严格来说这虽是可选的,但它有助于减少边界情况,并清晰地表明实体的意图与设计。它还可用于以不同名称存储该字段。

另外还有一个特殊的 @Id 注解,它必须始终存在。最佳实践是将该属性也命名为 id。

下面是一个非常简单的 User 实体:

示例 1. 带字段的简单文档

import org.springframework.data.annotation.Id;
import org.springframework.data.couchbase.core.mapping.Field;
import org.springframework.data.couchbase.core.mapping.Document;

@Document
public class User {

@Id
private String id;

@Field
private String firstname;

@Field
private String lastname;

public User(String id, String firstname, String lastname) {
this.id = id;
this.firstname = firstname;
this.lastname = lastname;
}

public String getId() {
return id;
}

public String getFirstname() {
return firstname;
}

public String getLastname() {
return lastname;
}
}

Couchbase Server 支持文档的自动过期。本库通过 @Document 注解实现了对此的支持。您可以设置一个 expiry 值,它表示文档在被自动移除前的秒数。如果您希望文档在变更后 10 秒过期,可以这样设置:@Document(expiry = 10)。或者,您也可以使用 Spring 的属性支持和 expiryExpression 参数来配置过期时间,从而动态更改过期值。例如:@Document(expiryExpression = "${valid.document.expiry}")。该属性必须可解析为一个 int 值,且这两种方式不能混用。

如果您希望文档内的字段名与实体中使用的字段名采用不同的表示,可以在 @Field 注解上设置一个不同的名称。例如,如果您想让文档保持小巧,可以将 firstname 字段设置为 @Field("fname")。在 JSON 文档中,您将看到 {"fname": ".."},而不是 {"firstname": ".."}。

必须存在 @Id 注解,因为 Couchbase 中的每个文档都需要一个唯一键。该键必须是任意字符串,长度最多 250 个字符。您可以自由选用任何适合您用例的值,无论是 UUID、电子邮件地址还是其他任何内容。

对 Couchbase Server 桶的写入可以选择性地指定持久性要求;这会指示 Couchbase Server 在认为写入已提交之前,在集群内多个节点的内存和/或磁盘位置上更新指定文档。默认的持久性要求也可以通过 @Document 或 @Durability 注解进行配置。例如:@Document(durabilityLevel = DurabilityLevel.MAJORITY) 会强制将变更复制到多数 Data Service 节点。这两个注解都支持通过 durabilityExpression 属性基于表达式指定持久性级别(注意不支持 SpEL)。

数据类型与转换器​

首选的存储格式是 JSON。它非常出色,但与许多数据表示一样,它所能表达的数据类型比 Java 中直接表达的要少。因此,对于所有非基本类型,都需要进行某种形式的、与受支持类型之间的相互转换。

对于以下实体字段类型,您无需添加特殊处理:

表 1. 基本类型

Java 类型JSON 表示
stringstring
booleanboolean
bytenumber
shortnumber
intnumber
longnumber
floatnumber
doublenumber
null写入时忽略

由于 JSON 支持对象(“映射”)和列表,Map 和 List 类型可以自然地进行转换。如果它们只包含上一段所述的基本字段类型,您同样无需添加特殊处理。下面是一个示例:

示例 2. 带 Map 与 List 的文档

@Document
public class User {

@Id
private String id;

@Field
private List<String> firstnames;

@Field
private Map<String, Integer> childrenAges;

public User(String id, List<String> firstnames, Map<String, Integer> childrenAges) {
this.id = id;
this.firstnames = firstnames;
this.childrenAges = childrenAges;
}

}

存储一个带有示例数据的用户,其 JSON 表示可能如下所示:

示例 3. 带 Map 与 List 的文档 - JSON

{
"_class": "foo.User",
"childrenAges": {
"Alice": 10,
"Bob": 5
},
"firstnames": [
"Foo",
"Bar",
"Baz"
]
}

您无需总是把一切都拆解为基本类型以及 List/Map。当然,您也可以用这些基本值组合出其他对象。让我们修改上一个示例,使其改为存储一个 Children 的 List:

示例 4. 带组合对象的文档

@Document
public class User {

@Id
private String id;

@Field
private List<String> firstnames;

@Field
private List<Child> children;

public User(String id, List<String> firstnames, List<Child> children) {
this.id = id;
this.firstnames = firstnames;
this.children = children;
}

static class Child {
private String name;
private int age;

Child(String name, int age) {
this.name = name;
this.age = age;
}

}

}

一个已填充的对象可能如下所示:

示例 5. 带组合对象的文档 - JSON

{
"_class": "foo.User",
"children": [
{
"age": 4,
"name": "Alice"
},
{
"age": 3,
"name": "Bob"
}
],
"firstnames": [
"Foo",
"Bar",
"Baz"
]
}

大多数时候,您还需要存储像 Date 这样的时间值。由于它无法直接存储在 JSON 中,因此需要进行转换。本库为 Date、Calendar 以及 JodaTime 类型(如果在 classpath 上)实现了默认转换器。所有这些类型在文档中默认都表示为 unix 时间戳(数字)。您随时可以如后文所示那样用自定义转换器覆盖默认行为。下面是一个示例:

示例 6. 带 Date 与 Calendar 的文档

@Document
public class BlogPost {

@Id
private String id;

@Field
private Date created;

@Field
private Calendar updated;

@Field
private String title;

public BlogPost(String id, Date created, Calendar updated, String title) {
this.id = id;
this.created = created;
this.updated = updated;
this.title = title;
}

}

一个已填充的对象可能如下所示:

示例 7. 带 Date 与 Calendar 的文档 - JSON

{
"title": "a blog post title",
"_class": "foo.BlogPost",
"updated": 1394610843,
"created": 1394610843897
}

(可选)通过将系统属性 org.springframework.data.couchbase.useISOStringConverterForDate 设为 true,可以让 Date 与符合 ISO-8601 的字符串之间相互转换。如果您想覆盖某个转换器或实现自己的转换器,这也是可行的。本库实现了通用的 Spring Converter 模式。您可以在配置中、在 Bean 创建时插入自定义转换器。下面是配置方式(在您重写的 AbstractCouchbaseConfiguration 中):

示例 8. 自定义转换器

@Override
public CustomConversions customConversions() {
return new CustomConversions(Arrays.asList(FooToBarConverter.INSTANCE, BarToFooConverter.INSTANCE));
}

@WritingConverter
public static enum FooToBarConverter implements Converter<Foo, Bar> {
INSTANCE;

@Override
public Bar convert(Foo source) {
return /* do your conversion here */;
}

}

@ReadingConverter
public static enum BarToFooConverter implements Converter<Bar, Foo> {
INSTANCE;

@Override
public Foo convert(Bar source) {
return /* do your conversion here */;
}

}

使用自定义转换时,有以下几点需要牢记:

  • 为了消除歧义,请始终在转换器上使用 @WritingConverter 和 @ReadingConverter 注解。尤其是在处理基本类型转换时,这有助于减少可能出现的错误转换。

  • 如果您实现了一个写入转换器,请确保只解码为基本类型、映射和列表。如果需要更复杂的对象类型,请使用 CouchbaseDocument 和 CouchbaseList 类型,底层转换引擎也能理解它们。最稳妥的做法是尽量使用最简单的转换。

  • 务必将更特殊的转换器放在通用转换器之前,以避免执行了错误的转换器。

  • 对于日期,读取转换器应当能够从任意 Number(而不仅仅是 Long)读取。这是 N1QL 支持所要求的。

乐观锁定​

在某些情况下,当您对文档执行变更操作时,可能希望确保不会覆盖其他用户所做的更改。为此,您有三种选择:事务(自 Couchbase 6.5 起支持)、悲观并发(锁定)或乐观并发。

乐观并发通常比悲观并发或事务提供更好的性能,因为它不会在数据上持有实际锁,也不会存储关于该操作的额外信息(没有事务日志)。

为实现乐观锁定,Couchbase 采用 CAS(比较并交换)方式。当文档被变更时,CAS 值也会随之改变。CAS 对客户端是不透明的,您只需知道:当内容或元信息发生变化时,它也会改变。

在其他数据存储中,可以通过一个带递增计数器的任意版本字段来实现类似行为。由于 Couchbase 以更优的方式支持这一点,因此很容易实现。如果您希望获得自动乐观锁定支持,只需在一个 long 字段上添加 @Version 注解,如下所示:

示例 9. 带乐观锁定的文档。

@Document
public class User {

@Version
private long version;

// constructor, getters, setters...
}

如果您通过模板或仓库加载文档,version 字段会自动填充为当前的 CAS 值。需要注意的是,您不应当自行访问该字段,更不应当自行更改它。一旦您将文档保存回去,操作要么成功,要么因抛出 OptimisticLockingFailureException 而失败。如果遇到此类异常,后续处理方式取决于您在应用层面想要达到的目的。您要么重试整个“加载-更新-写入”循环,要么将错误向上层传播以进行妥善处理。

校验​

本库支持 JSR 303 校验,它基于直接标注在实体中的注解。当然,您也可以在服务层添加各种校验,但这种方式能让校验与您的实际实体良好地结合在一起。

要使其生效,您需要引入两个额外的依赖:JSR 303 以及一个实现它的库,例如 hibernate 所支持的实现:

示例 10. 校验依赖

<dependency>
<groupId>javax.validation</groupId>
<artifactId>validation-api</artifactId>
</dependency>
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-validator</artifactId>
</dependency>

现在您需要向配置中添加两个 Bean:

示例 11. 校验 Bean

@Bean
public LocalValidatorFactoryBean validator() {
return new LocalValidatorFactoryBean();
}

@Bean
public ValidatingCouchbaseEventListener validationEventListener() {
return new ValidatingCouchbaseEventListener(validator());
}

现在您就可以用 JSR303 注解标注字段了。如果 save() 时的校验失败,会抛出 ConstraintViolationException。

示例 12. 校验注解示例

@Size(min = 10)
@Field
private String name;

审计​

通过 Spring Data 的审计机制,实体可以被自动审计(追踪是哪个用户创建了对象、更新了对象,以及在什么时间进行的)。

首先请注意,只有带有 @Version 注解字段的实体才能对创建进行审计(否则框架会将创建解释为更新)。

审计的工作方式是用 @CreatedBy、@CreatedDate、@LastModifiedBy 和 @LastModifiedDate 标注字段。框架会在持久化实体时自动向这些字段注入正确的值。xxxDate 注解必须放在 Date 类型字段(或兼容类型,例如 jodatime 类)上,而 xxxBy 注解可以放在任意类 T 类型的字段上(不过这两个字段必须是同一类型)。

要配置审计,首先需要在上下文中有一个 auditor aware Bean。该 Bean 必须为 AuditorAware<T> 类型(能够产生一个可存入前文所述 T 类型 xxxBy 字段的值)。其次,您必须在 @Configuration 类中使用 @EnableCouchbaseAuditing 注解来启用审计。

下面是一个示例:

示例 13. 审计实体示例

@Document
public class AuditedItem {

@Id
private final String id;

private String value;

@CreatedBy
private String creator;

@LastModifiedBy
private String lastModifiedBy;

@LastModifiedDate
private Date lastModification;

@CreatedDate
private Date creationDate;

@Version
private long version;

//..omitted constructor/getters/setters/...
}

请注意,@CreatedBy 和 @LastModifiedBy 都放在 String 字段上,因此我们的 AuditorAware 必须处理 String 类型。

示例 14. AuditorAware 实现示例

public class NaiveAuditorAware implements AuditorAware<String> {

private String auditor = "auditor";

@Override
public String getCurrentAuditor() {
return auditor;
}

public void setAuditor(String auditor) {
this.auditor = auditor;
}
}

为了将所有这些串联起来,我们使用 Java 配置既声明一个 AuditorAware Bean,又启用审计:

示例 15. 审计配置示例

@Configuration
@EnableCouchbaseAuditing //this activates auditing
public class AuditConfiguration extends AbstractCouchbaseConfiguration {

//... a few abstract methods omitted here

// this creates the auditor aware bean that will feed the annotations
@Bean
public NaiveAuditorAware testAuditorAware() {
return new NaiveAuditorAware();
}