Repository resources
Fundamentals
Spring Data REST 的核心功能是为 Spring Data 存储库导出资源。因此,要查看和潜在自定义导出工作方式的核心工件是存储库接口。考虑以下存储库接口:
public interface OrderRepository extends CrudRepository<Order, Long> { }
对于该存储库,Spring Data REST 会在 /orders
处公开一个集合资源。路径派生自正在管理的领域类的大小写相同、复数形式的简单类名。它还会基于 URI 模板 /orders/{id}
为存储库管理的每个条目公开一个条目资源。
默认情况下,与这些资源交互的 HTTP 方法映射到 `CrudRepository`的相应方法。更多详情,请参阅有关 collection resources和 item resources的部分。
Repository methods exposure
针对特定存储库公开哪些 HTTP 资源主要受存储库的结构驱动。换句话说,资源公开会遵循在存储库中公开哪些方法。如果你扩展 CrudRepository
,你通常会公开所有需要公开所有 HTTP 资源的方法,我们可以默认注册这些资源。下面列出的每个资源都将定义哪些方法必须存在,从而针对每个资源公开特定的 HTTP 方法。这意味着,未公开这些方法(通过根本不声明它们或显式使用 @RestResource(exported = false)
)的存储库不会在这些资源上公开这些 HTTP 方法。
有关如何分区域调整默认方法暴露或专门的 HTTP 方法的详情,请参阅 Customizing supported HTTP methods。
Default Status Codes
对于公开的资源,我们使用一组默认状态代码:
-
200 OK
:对于纯 `GET`请求。 -
201 Created
:对于创建新资源的 `POST`和 `PUT`请求。 -
204 No Content
:针对PUT
、PATCH`和 `DELETE`请求,将配置设置为不返回资源更新的响应正文 (`RepositoryRestConfiguration.setReturnBodyOnUpdate(…)
) 时。如果配置值设置为包括对 `PUT`的响应,则 `200 OK`将用于更新,而 `201 Created`将用于通过 `PUT`创建的资源。
如果配置值 (RepositoryRestConfiguration.returnBodyOnUpdate(…)`和 `RepositoryRestConfiguration.returnBodyCreate(…)
) 显式设置为 null
——它们默认如此——则使用 HTTP Accept 标头表示来确定响应代码。更多详情,请参阅 collection和 «13»的详细描述。
Resource Discoverability
HATEOAS 的核心原则是资源应该可通过发布指向可用资源的链接来发现。有几个有竞争力的事实上标准介绍如何在 JSON 中表示链接。默认情况下,Spring Data REST 使用 HAL 来呈现响应。HAL 定义要包含在返回文档的属性中的链接。
资源发现从应用程序的顶级开始。通过向已部署 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 中指定的嵌套链接对象)的键。
有关 |
The Collection Resource
Spring Data REST 公开一个集合资源,它是已导出存储库正在处理的领域类的小写复数形式的命名方式。资源的名称和路径都可以通过在存储库接口上使用 @RepositoryRestResource
来自定义。
Supported HTTP Methods
集合资源同时支持 GET
和 POST
。所有其他 HTTP 方法导致 405 Method Not Allowed
。
GET
通过 findAll(…)
方法,返回存储库服务器上的所有实体。如果存储库是分页存储库,我们在必要时包含分页链接和附加页元数据。
Methods used for invocation
使用以下方法(降序):
-
findAll(Pageable)
-
findAll(Sort)
-
findAll()
有关方法默认暴露的更多信息,请参阅 Repository methods exposure。
Parameters
如果存储库具有分页功能,资源采用以下参数:
-
page
:要访问的页码(从 0 开始,默认为 0)。 -
size
:请求的分页大小(默认为 20)。 -
sort
:格式为($propertyname,)+[asc|desc]
? 的排序指令集合。
HEAD
HEAD
方法返回集合资源是否可用。它没有状态代码、媒介类型或相关资源。
Methods used for invocation
使用以下方法(降序):
-
findAll(Pageable)
-
findAll(Sort)
-
findAll()
有关方法默认暴露的更多信息,请参阅 Repository methods exposure。
POST
POST
方法使用给定的请求主体创建新的实体。默认情况下,响应是否包含主体由请求中发送的 Accept
头控制。如果发送了一个 Accept
头,则创建响应主体。如果没有,则响应主体为空,并且可以通过遵循 Location
响应头中包含的链接来获取创建的资源的表示形式。可以通过相应地配置 RepositoryRestConfiguration.setReturnBodyOnCreate(…)
来覆盖此行为。
The Item Resource
Spring Data REST 将单个集合元素的资源作为集合资源的子资源公开。
Supported HTTP Methods
项目资源通常支持 GET
、PUT
、PATCH`和 `DELETE
,除非明确的配置阻止它们(有关详情,请参阅 “The Association Resource”)。
GET
GET
方法返回单个实体。
Custom Status Codes
GET
方法仅有一个自定义状态代码:
-
405 Method Not Allowed
:如果findOne(…)`方法未导出(通过 `@RestResource(exported = false)
)或不存在于资源库中。
Related Resources
对于每种域类型关联关系,我们都会显示以关联关系属性命名的链接。您可以使用属性上的 `@RestResource`自定义此行为。相关资源为 association resource类型。
PUT
PUT
方法使用提供的请求主体替换目标资源的状态。默认情况下,响应是否包含主体由请求中发送的 Accept
头控制。如果请求头存在,则返回响应主体和 200 OK
状态代码。如果头不存在,则响应主体为空,成功请求会返回 204 No Content
状态。可以通过相应地配置 RepositoryRestConfiguration.setReturnBodyOnUpdate(…)
来覆盖此行为。
PATCH
PATCH
方法与 PUT
方法类似,但可以部分更新资源状态。
Custom Status Codes
PATCH
方法仅有一个自定义状态代码:
-
405 Method Not Allowed
:如果save(…)`方法未导出(通过 `@RestResource(exported = false)
)或不存在于资源库中。
DELETE
DELETE
方法删除公开的资源。默认情况下,响应是否包含主体由请求中发送的 Accept
头控制。如果请求头存在,则返回响应主体和 200 OK
状态代码。如果头不存在,则响应主体为空,成功请求会返回 204 No Content
状态。可以通过相应地配置 RepositoryRestConfiguration.setReturnBodyOnDelete(…)
来覆盖此行为。
Methods used for invocation
使用以下方法(降序):
-
delete(T)
-
delete(ID)
-
delete(Iterable)
有关方法默认暴露的更多信息,请参阅 Repository methods exposure。
The Association Resource
The Search Resource
搜索资源返回存储库公开的所有查询方法的链接。可以使用方法声明中的 @RestResource
修改查询方法资源的路径和名称。
Supported HTTP Methods
由于搜索资源是只读资源,所以它只支持 GET
方法。
GET
GET
方法返回指向单个查询方法资源的链接列表。
Related Resources
对于在存储库中声明的每种查询方法,我们都会显示一个 query method resource。如果资源支持分页,指向该资源的 URI 会是一个包含分页参数的 URI 模板。