仓库资源
基础
Spring Data REST 的核心功能是为 Spring Data 仓库导出资源。因此,需要重点关注并可能定制导出工作方式的核心构件就是仓库接口。考虑以下仓库接口:
public interface OrderRepository extends CrudRepository<Order, Long> { }
对于该仓库,Spring Data REST 在 /orders 处暴露一个集合资源。该路径由所管理领域类的简单类名(首字母小写、转为复数)派生而来。它还在 URI 模板 /orders/{id} 下为仓库所管理的每个条目暴露一个单项资源。
仓库方法暴露
为某个仓库暴露哪些 HTTP 资源,主要由仓库的结构决定。换言之,资源暴露将跟随您在仓库上暴露了哪些方法。如果您扩展 CrudRepository,通常会暴露可默认注册的所有 HTTP 资源所需的全部方法。下面列出的每种资源都会定义需要存在哪些方法,以便为每种资源暴露特定的 HTTP 方法。这意味着,未暴露这些方法的仓库——无论是根本不声明它们,还是显式使用 @RestResource(exported = false)——都不会在这些资源上暴露那些 HTTP 方法。
有关如何调整默认方法暴露或单独定制特定 HTTP 方法的详细信息,请参阅定制受支持的 HTTP 方法。
默认状态码
对于所暴露的资源,我们使用一组默认状态码:
-
200 OK:用于普通的GET请求。 -
201 Created:用于创建新资源的POST和PUT请求。 -
204 No Content:当配置设置为资源更新不返回响应体时(RepositoryRestConfiguration.setReturnBodyOnUpdate(…)),用于PUT、PATCH和DELETE请求。如果配置值设置为为PUT包含响应,则更新返回200 OK,通过PUT创建的资源返回201 Created。
资源可发现性
资源发现从应用的顶层开始。通过向部署 Spring Data REST 应用的根 URL 发起请求,客户端可以从返回的 JSON 对象中提取一组链接,这些链接代表客户端可用的下一层资源。
例如,要发现应用根处有哪些可用资源,请向根 URL 发起一个 HTTP GET,如下所示:
curl -v http://localhost:8080/
< HTTP/1.1 200 OK
< Content-Type: application/hal+json
{ "_links" : {
"orders" : {
"href" : "http://localhost:8080/orders"
},
"profile" : {
"href" : "http://localhost:8080/api/alps"
}
}
}
结果文档的该属性是一个对象,它由表示关系类型的键组成,键下是 HAL 所规定的嵌套链接对象。
有关 profile 链接的更多详情,请参阅应用级配置文件语义(ALPS)。
集合资源
Spring Data REST 暴露一个集合资源,其名称取自所导出仓库处理的领域类名称的首字母小写、转复数形式。资源的名称和路径都可以通过在仓库接口上使用 @RepositoryRestResource 来定制。
受支持的 HTTP 方法
集合资源同时支持 GET 和 POST。所有其他 HTTP 方法都会导致 405 Method Not Allowed。
GET
返回仓库通过其 findAll(…) 方法服务的所有实体。如果仓库是分页仓库,我们会在必要时包含分页链接以及额外的分页元数据。
用于调用的方法
如果存在以下方法,则按(降序)使用:
-
findAll(Pageable) -
findAll(Sort) -
findAll()
有关方法默认暴露的更多信息,请参阅仓库方法暴露。
参数
如果仓库具备分页能力,该资源接受以下参数:
-
page:要访问的页码(从 0 开始索引,默认为 0)。 -
size:请求的每页大小(默认为 20)。 -
sort:一组排序指令,格式为($propertyname,)+[asc|desc]?。
自定义状态码
GET 方法只有一个自定义状态码:
405 Method Not Allowed:如果findAll(…)方法未被导出(通过@RestResource(exported = false))或不存在于仓库中。
受支持的媒体类型
GET 方法支持以下媒体类型:
-
application/hal+json -
application/json
相关资源
GET 方法支持一个用于发现相关资源的链接:
search:如果底层仓库暴露了查询方法,则暴露一个搜索资源。
HEAD
HEAD 方法返回集合资源是否可用。它没有状态码、媒体类型或相关资源。
用于调用的方法
如果存在以下方法,则按(降序)使用:
-
findAll(Pageable) -
findAll(Sort) -
findAll()
有关方法默认暴露的更多信息,请参阅仓库方法暴露。
POST
POST 方法根据给定的请求体创建一个新实体。默认情况下,响应是否包含正文由随请求发送的 Accept 头控制。如果发送了 Accept 头,则创建响应正文。如果没有发送,则响应正文为空,所创建资源的表示可通过跟随 Location 响应头中包含的链接获得。可以通过相应配置 RepositoryRestConfiguration.setReturnBodyOnCreate(…) 来覆盖此行为。
用于调用的方法
如果存在以下方法,则按(降序)使用:
save(…)
有关方法默认暴露的更多信息,请参阅仓库方法暴露。
自定义状态码
POST 方法只有一个自定义状态码:
405 Method Not Allowed:如果save(…)方法未被导出(通过@RestResource(exported = false))或根本不存在于仓库中。
受支持的媒体类型
POST 方法支持以下媒体类型:
-
application/hal+json
-
application/json
单项资源
Spring Data REST 为集合中的各个条目暴露一个资源,作为集合资源的子资源。
受支持的 HTTP 方法
单项资源通常支持 GET、PUT、PATCH 和 DELETE,除非显式配置阻止了这一点(详情请参阅「关联资源」)。
GET
GET 方法返回单个实体。
用于调用的方法
如果存在以下方法,则按(降序)使用:
findById(…)
有关方法默认暴露的更多信息,请参阅仓库方法暴露。
自定义状态码
GET 方法只有一个自定义状态码:
405 Method Not Allowed:如果findOne(…)方法未被导出(通过@RestResource(exported = false))或不存在于仓库中。
受支持的媒体类型
GET 方法支持以下媒体类型:
-
application/hal+json
-
application/json
相关资源
对于领域类型的每个关联,我们都会暴露以关联属性命名的链接。您可以通过在属性上使用 @RestResource 来定制此行为。相关资源属于关联资源类型。
HEAD
HEAD 方法返回单项资源是否可用。它没有状态码、媒体类型或相关资源。
用于调用的方法
如果存在以下方法,则按(降序)使用:
findById(…)
有关方法默认暴露的更多信息,请参阅仓库方法暴露。
PUT
PUT 方法用所提供的请求体替换目标资源的状态。默认情况下,响应是否包含正文由随请求发送的 Accept 头控制。如果存在该请求头,则返回响应正文和 200 OK 状态码。如果不存在该头,则响应正文为空,成功的请求返回 204 No Content 状态。可以通过相应配置 RepositoryRestConfiguration.setReturnBodyOnUpdate(…) 来覆盖此行为。
用于调用的方法
如果存在以下方法,则按(降序)使用:
save(…)
有关方法默认暴露的更多信息,请参阅仓库方法暴露。
自定义状态码
PUT 方法只有一个自定义状态码:
405 Method Not Allowed:如果save(…)方法未被导出(通过@RestResource(exported = false))或根本不存在于仓库中。
受支持的媒体类型
PUT 方法支持以下媒体类型:
-
application/hal+json
-
application/json
PATCH
PATCH 方法与 PUT 方法类似,但会部分更新资源状态。
用于调用的方法
如果存在以下方法,则按(降序)使用:
save(…)
有关方法默认暴露的更多信息,请参阅仓库方法暴露。
自定义状态码
PATCH 方法只有一个自定义状态码:
405 Method Not Allowed:如果save(…)方法未被导出(通过@RestResource(exported = false))或不存在于仓库中。
受支持的媒体类型
PATCH 方法支持以下媒体类型:
-
application/hal+json
-
application/json
DELETE
DELETE 方法删除所暴露的资源。默认情况下,响应是否包含正文由随请求发送的 Accept 头控制。如果存在该请求头,则返回响应正文和 200 OK 状态码。如果不存在该头,则响应正文为空,成功的请求返回 204 No Content 状态。可以通过相应配置 RepositoryRestConfiguration.setReturnBodyOnDelete(…) 来覆盖此行为。
用于调用的方法
如果存在以下方法,则按(降序)使用:
-
delete(T) -
delete(ID) -
delete(Iterable)
有关方法默认暴露的更多信息,请参阅仓库方法暴露。
自定义状态码
DELETE 方法只有一个自定义状态码:
405 Method Not Allowed:如果delete(…)方法未被导出(通过@RestResource(exported = false))或不存在于仓库中。
关联资源
Spring Data REST 为每个单项资源所拥有的每个关联,暴露该单项资源的子资源。该资源的名称和路径默认为关联属性的名称,并可通过在关联属性上使用 @RestResource 来定制。
受支持的 HTTP 方法
关联资源支持以下媒体类型:
-
GET
-
PUT
-
POST
-
DELETE
GET
GET 方法返回关联资源的状态。
受支持的媒体类型
GET 方法支持以下媒体类型:
-
application/hal+json
-
application/json
PUT
PUT 方法将给定 URI 指向的资源绑定到关联资源(请参阅「受支持的媒体类型」)。
自定义状态码
PUT 方法只有一个自定义状态码:
400 Bad Request:当为一对一关联给定了多个 URI 时。
受支持的媒体类型
PUT 方法只支持一种媒体类型:
- text/uri-list:指向要绑定到该关联的资源的 URI。
POST
POST 方法仅对集合关联受支持。它向集合添加一个新元素。
受支持的媒体类型
POST 方法只支持一种媒体类型:
- text/uri-list:指向要添加到该关联的资源的 URI。
DELETE
DELETE 方法解除该关联的绑定。
自定义状态码
POST 方法只有一个自定义状态码:
405 Method Not Allowed:当该关联为非可选时。
搜索资源
搜索资源返回指向仓库所暴露的所有查询方法的链接。查询方法资源的路径和名称可以通过在方法声明上使用 @RestResource 来修改。
受支持的 HTTP 方法
由于搜索资源是只读资源,它只支持 GET 方法。
GET
GET 方法返回一个链接列表,指向各个查询方法资源。
受支持的媒体类型
GET 方法支持以下媒体类型:
-
application/hal+json
-
application/json
相关资源
对于仓库中声明的每个查询方法,我们都会暴露一个查询方法资源。如果该资源支持分页,指向它的 URI 是一个包含分页参数的 URI 模板。
HEAD
HEAD 方法返回搜索资源是否可用。返回 404 状态码表示没有可用的查询方法资源。
查询方法资源
查询方法资源通过仓库接口上的单个查询方法运行所暴露的查询。
受支持的 HTTP 方法
由于查询方法资源是只读资源,它只支持 GET。
GET
GET 方法返回查询的结果。
参数
如果查询方法具备分页能力(在指向该资源的 URI 模板中指明),该资源接受以下参数:
-
page:要访问的页码(从 0 开始索引,默认为 0)。 -
size:请求的每页大小(默认为 20)。 -
sort:一组排序指令,格式为($propertyname,)+[asc|desc]?。
受支持的媒体类型
GET 方法支持以下媒体类型:
-
application/hal+json -
application/json
HEAD
HEAD 方法返回某个查询方法资源是否可用。
本节小结
分页与排序
本节介绍 Spring Data REST 对 Spring Data 仓库分页与排序抽象的使用。要熟悉这些特性,请参阅您所使用的仓库实现(例如 Spring Data JPA )对应的 Spring Data 文档。
投影与摘录
Spring Data REST 为您导出的领域模型呈现默认视图。但是,有时您可能出于各种原因需要更改该模型的视图。本节介绍如何定义投影和摘录,以提供资源的简化视图和缩减视图。