投影与摘录
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}。selfURI 是一个 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 指令。
这个示例看起来可能有点刻意,但在更丰富的领域模型和众多投影下,确实有可能意外泄漏此类详情。由于 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=…) 会更改默认行为。如果您已经发布过版本,这可能会对服务的使用者造成破坏性变更。