跳到主要内容
版本:5.1.1

投影与摘录

Doubao 中英对照 Projections and Excerpts

Spring Data REST 为您导出的领域模型呈现默认视图。但是,有时您可能出于各种原因需要更改该模型的视图。本节介绍如何定义投影和摘录,以提供资源的简化视图和缩减视图。

投影​

考虑以下领域模型:

@Entity
public class Person {

@Id @GeneratedValue
private Long id;
private String firstName, lastName;

@OneToOne
private Address address;
…
}

上例中的 Person 对象有几个属性:

  • id 是主键。

  • firstName 和 lastName 是数据属性。

  • address 是指向另一个领域对象的链接。

现在假设我们创建了一个对应的仓库,如下所示:

interface PersonRepository extends CrudRepository<Person, Long> {}

默认情况下,Spring Data REST 导出该领域对象,包括其所有属性。firstName 和 lastName 按其本来的普通数据对象形式导出。关于 address 属性有两种选择。一种选择是也为 Address 对象定义一个仓库,如下所示:

interface AddressRepository extends CrudRepository<Address, Long> {}

在这种情况下,Person 资源会把 address 属性渲染为指向其对应 Address 资源的 URI。如果我们在系统中查找「Frodo」,可以预期看到如下这样的 HAL 文档:

{
"firstName" : "Frodo",
"lastName" : "Baggins",
"_links" : {
"self" : {
"href" : "http://localhost:8080/persons/1"
},
"address" : {
"href" : "http://localhost:8080/persons/1/address"
}
}
}

还有另一种方式。如果 Address 领域对象没有自己的仓库定义,Spring Data REST 会把数据字段内联包含在 Person 资源内部,如下例所示:

{
"firstName" : "Frodo",
"lastName" : "Baggins",
"address" : {
"street": "Bag End",
"state": "The Shire",
"country": "Middle Earth"
},
"_links" : {
"self" : {
"href" : "http://localhost:8080/persons/1"
}
}
}

但是,如果您根本不想要 address 的详细信息怎么办?同样,默认情况下 Spring Data REST 导出其所有属性(id 除外)。您可以通过定义一个或多个投影,为 REST 服务的使用者提供另一种选择。以下示例展示了一个不包含 address 的投影:

@Projection(name = "noAddresses", types = { Person.class }) 1
interface NoAddresses { 2

String getFirstName(); 3

String getLastName(); 4
}
  • @Projection 注解将其标记为投影。name 属性提供投影的名称,我们稍后会详细介绍。types 属性将此投影的应用目标限定为仅作用于 Person 对象。

  • 它是一个 Java 接口,使其具有声明式。

  • 它导出 firstName。

  • 它导出 lastName。

NoAddresses 投影只有 firstName 和 lastName 的 getter,这意味着它不提供任何地址信息。假设您为 Address 资源有一个单独的仓库,Spring Data REST 的默认视图与前述表示略有不同,如下例所示:

{
"firstName" : "Frodo",
"lastName" : "Baggins",
"_links" : {
"self" : {
"href" : "http://localhost:8080/persons/1{?projection}", 1
"templated" : true 2
},
"address" : {
"href" : "http://localhost:8080/persons/1/address"
}
}
}
  • 此资源有一个新选项:{?projection}。

  • self URI 是一个 URI 模板。

要查看资源的投影,请访问 [localhost:8080/persons/1?projection=noAddresses](http://localhost:8080/persons/1?projection=noAddresses)。

备注

提供给 projection 查询参数的值与 @Projection(name = "noAddress") 中指定的值相同。它与投影接口的名称无关。

您可以拥有多个投影。

备注

请参阅 投影 查看一个示例项目。我们鼓励您动手试验。

Spring Data REST 按如下方式查找投影定义:

  • 在与您的实体定义相同的包(或其子包之一)中找到的任何 @Projection 接口都会被注册。

  • 您可以使用 RepositoryRestConfiguration.getProjectionConfiguration().addProjection(…) 手动注册投影。

无论哪种情况,投影接口都必须带有 @Projection 注解。

查找现有投影​

Spring Data REST 暴露应用级配置文件语义(ALPS)文档,这是一种微型元数据格式。要查看 ALPS 元数据,请跟随根资源暴露的 profile 链接。如果您向下导航到 Person 资源的 ALPS 文档(即 /alps/persons),可以找到关于 Person 资源的许多详情。投影会连同关于 GET REST 转换的详情一起,列在类似以下示例的块中:

{ …
"id" : "get-person", 1
"name" : "person",
"type" : "SAFE",
"rt" : "#person-representation",
"descriptors" : [ {
"name" : "projection", 2
"doc" : {
"value" : "The projection that shall be applied when rendering the response. Acceptable values available in nested descriptors.",
"format" : "TEXT"
},
"type" : "SEMANTIC",
"descriptors" : [ {
"name" : "noAddresses", 3
"type" : "SEMANTIC",
"descriptors" : [ {
"name" : "firstName", 4
"type" : "SEMANTIC"
}, {
"name" : "lastName", 4
"type" : "SEMANTIC"
} ]
} ]
} ]
},
…
  • ALPS 文档的这一部分展示了关于 GET 和 Person 资源的详情。

  • 这一部分包含 projection 选项。

  • 这一部分包含 noAddresses 投影。

  • 此投影实际提供的属性包括 firstName 和 lastName。

备注

投影定义会被拾取并提供给客户端,前提是它们:

  • 带有 @Projection 注解标记,并且位于领域类型的相同包(或子包)中,或者

  • 通过使用 RepositoryRestConfiguration.getProjectionConfiguration().addProjection(…) 手动注册。

引入隐藏数据​

到目前为止,本节介绍了如何使用投影来减少呈现给用户的信息。投影也可以引入通常不可见的数据。例如,Spring Data REST 会忽略用 @JsonIgnore 注解标记的字段或 getter。考虑以下领域对象:

@Entity
public class User {

@Id @GeneratedValue
private Long id;
private String name;

@JsonIgnore private String password; 1

private String[] roles;
…
  • Jackson 的 @JsonIgnore 用于防止 password 字段被序列化为 JSON。

上例中的 User 类既可用于存储用户信息,也可用于与 Spring Security 集成。如果您创建一个 UserRepository,password 字段通常会被导出,这并不好。在上例中,我们通过在 password 字段上应用 Jackson 的 @JsonIgnore 来防止这种情况发生。

备注

如果 @JsonIgnore 位于字段对应的 getter 函数上,Jackson 也不会将该字段序列化为 JSON。

但是,投影引入了仍能提供该字段的能力。可以创建如下投影:

@Projection(name = "passwords", types = { User.class })
interface PasswordProjection {

String getPassword();
}

如果创建并使用这样的投影,它会绕过放在 User.password 上的 @JsonIgnore 指令。

important

这个示例看起来可能有点刻意,但在更丰富的领域模型和众多投影下,确实有可能意外泄漏此类详情。由于 Spring Data REST 无法辨别此类数据的敏感性,因此需要由您来避免这种情况。

投影还可以生成虚拟数据。假设您有如下实体定义:

@Entity
public class Person {

...
private String firstName;
private String lastName;

...
}

您可以创建一个投影,将上例中的两个数据字段组合在一起,如下所示:

@Projection(name = "virtual", types = { Person.class })
public interface VirtualProjection {

@Value("#{target.firstName} #{target.lastName}") 1
String getFullName();

}
  • Spring 的 @Value 注解让您可以插入一个 SpEL 表达式,该表达式接收目标对象并将其 firstName 和 lastName 属性拼接在一起,以渲染一个只读的 fullName。

摘录​

摘录是一种自动应用于资源集合的投影。例如,您可以按如下方式修改 PersonRepository:

@RepositoryRestResource(excerptProjection = NoAddresses.class)
interface PersonRepository extends CrudRepository<Person, Long> {}

上例指示 Spring Data REST 在将 Person 资源嵌入集合或相关资源时使用 NoAddresses 投影。

备注

摘录投影不会自动应用于单个资源。它们必须被刻意应用。摘录投影旨在为集合数据提供默认预览,但在获取单个资源时不应用。有关此主题的讨论,请参阅 为什么摘录投影不会自动应用于 Spring Data REST 单项资源?。

除了更改默认渲染之外,摘录还有额外的渲染选项,如下一节所示。

摘录常用访问的数据​

REST 服务中一个常见情形出现在您组合领域对象时。例如,Person 存储在一张表中,其关联的 Address 存储在另一张表中。默认情况下,Spring Data REST 将 person 的 address 作为客户端必须导航的 URI 提供。但是,如果使用者总是需要获取这一额外数据片段成为常态,那么摘录投影可以将这一额外数据片段内联,从而为您省去一次额外的 GET。为此,您可以定义另一个摘录投影,如下所示:

@Projection(name = "inlineAddress", types = { Person.class }) 1
interface InlineAddress {

String getFirstName();

String getLastName();

Address getAddress(); 2
}
  • 此投影被命名为 inlineAddress。

  • 此投影添加了 getAddress,它返回 Address 字段。当在投影内部使用时,它会使该信息被内联包含进来。

您可以将其插入到 PersonRepository 定义中,如下所示:

@RepositoryRestResource(excerptProjection = InlineAddress.class)
interface PersonRepository extends CrudRepository<Person, Long> {}

这样做会使 HAL 文档呈现如下形式:

{
"firstName" : "Frodo",
"lastName" : "Baggins",
"address" : { 1
"street": "Bag End",
"state": "The Shire",
"country": "Middle Earth"
},
"_links" : {
"self" : {
"href" : "http://localhost:8080/persons/1"
},
"address" : { 2
"href" : "http://localhost:8080/persons/1/address"
}
}
}
  • address 数据直接内联包含,因此您无需导航即可获取它。

  • 指向 Address 资源的链接仍然提供,使得仍然可以导航到它自己的资源。

请注意,上例是本章前面所示各示例的混合。您可能需要回头重读它们,以了解到最终示例的演进过程。

注意

为仓库配置 @RepositoryRestResource(excerptProjection=…​) 会更改默认行为。如果您已经发布过版本,这可能会对服务的使用者造成破坏性变更。