|
对于最新的稳定版本，请使用 Spring Data REST 5.0.4！ |
仓库资源
基础
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。
资源可发现性
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"
}
}
}结果文档的 property 属性是一个对象，该对象由表示关系类型的键组成，其值为 HAL 中指定的嵌套链接对象。
有关 profile 链接的更多详细信息，请参阅应用程序级配置文件语义（ALPS）。 |
集合资源
Spring Data REST 会暴露一个集合资源，其名称基于所导出仓库所处理的领域类的小写复数形式。通过在仓库接口上使用 @RepositoryRestResource 注解，可以自定义该资源的名称和路径。
支持的 HTTP 方法
集合资源同时支持 GET 和 POST。所有其他 HTTP 方法将导致 405 Method Not Allowed（方法不允许）。
GET
通过其 findAll(…) 方法返回该仓库所服务的所有实体。
如果该仓库是一个分页仓库，我们会根据需要包含分页链接以及额外的页面元数据。
用于调用的方法
如果存在以下方法，则按以下顺序（从高到低）使用：
-
findAll(Pageable) -
findAll(Sort) -
findAll()
有关方法默认暴露的更多信息，请参见Repository 方法暴露。
参数
如果仓库具有分页功能，则该资源将接受以下参数：
-
page：要访问的页码（从0开始索引，默认值为0）。 -
size：请求的页面大小（默认为 20）。 -
sort：一组排序指令，格式为($propertyname,)+[asc|desc]？。
HEAD
HEAD 方法用于返回集合资源是否可用。它没有状态码、媒体类型或相关资源。
用于调用的方法
如果存在以下方法，则按以下顺序（从高到低）使用：
-
findAll(Pageable) -
findAll(Sort) -
findAll()
有关方法默认暴露的更多信息，请参见Repository 方法暴露。
POST
POST 方法根据给定的请求体创建一个新实体。
默认情况下，响应是否包含响应体由请求中发送的 Accept 头部控制。
如果发送了该头部，则会生成响应体。
如果没有发送，则响应体为空，此时可通过响应头 Location 中包含的链接获取所创建资源的表示形式。
此行为可以通过相应地配置 RepositoryRestConfiguration.setReturnBodyOnCreate(…) 来覆盖。
项目资源
Spring Data REST 将单个集合项的资源作为集合资源的子资源进行暴露。
支持的 HTTP 方法
Item 资源通常支持 GET、PUT、PATCH 和 DELETE，除非显式配置禁止了这些操作（详情请参见“关联资源”）。
GET
GET 方法返回单个实体。
自定义状态码
GET 方法只有一个自定义状态码：
-
405 Method Not Allowed：如果findOne(…)方法未被导出（通过@RestResource(exported = false)）或在仓库中不存在。
相关资源
对于领域类型的每个关联，我们都会暴露以关联属性命名的链接。您可以通过在属性上使用 @RestResource 注解来自定义此行为。相关资源属于关联资源类型。
PUT
PUT 方法使用提供的请求体替换目标资源的状态。
默认情况下，响应是否包含响应体由请求中发送的 Accept 头部控制。
如果请求头存在，则返回一个包含响应体和状态码 200 OK 的响应。
如果请求头不存在，则响应体为空，成功的请求返回状态码 204 No Content。
通过相应地配置 RepositoryRestConfiguration.setReturnBodyOnUpdate(…)，可以覆盖此行为。
PATCH
PATCH 方法与 PUT 方法类似，但用于部分更新资源的状态。
自定义状态码
PATCH 方法只有一个自定义状态码：
-
405 Method Not Allowed：如果save(…)方法未被导出（通过@RestResource(exported = false)）或在仓库中不存在。
DELETE
DELETE 方法用于删除所暴露的资源。
默认情况下，响应是否包含主体内容由请求中发送的 Accept 请求头控制。
如果存在该请求头，则返回响应主体和状态码 200 OK。
如果未提供该请求头，则响应主体为空，成功请求返回的状态码为 204 No Content。
通过相应地配置 RepositoryRestConfiguration.setReturnBodyOnDelete(…)，可以覆盖此默认行为。
用于调用的方法
如果存在以下方法，则按以下顺序（从高到低）使用：
-
delete(T) -
delete(ID) -
delete(Iterable)
有关方法默认暴露的更多信息，请参见Repository 方法暴露。
协会资源
搜索资源
搜索资源会返回该仓库所公开的所有查询方法的链接。可以通过在方法声明上使用 @RestResource 注解来修改查询方法资源的路径和名称。
支持的 HTTP 方法
由于搜索资源是只读资源，因此仅支持 GET 方法。
GET
GET 方法返回一个链接列表，这些链接指向各个查询方法资源。
相关资源
对于在仓库中声明的每个查询方法，我们都会暴露一个查询方法资源。如果该资源支持分页，则指向它的 URI 是一个包含分页参数的 URI 模板。