基础
Spring Data REST的核心功能是导出Spring Data存储库的资源。因此,要查看并可能自定义导出工作方式的核心工件是存储库接口。请考虑以下存储库接口:
public interface OrderRepository extends CrudRepository<Order, Long> { }
对于此存储库,Spring Data REST 在 中公开了一个集合资源。该路径派生自所管理域类的未大写、复数、简单的类名。它还为存储库在 URI 模板下管理的每个项目公开一个项目资源。/orders
/orders/{id}
存储库方法公开
为某个仓库公开哪些 HTTP 资源主要由仓库的结构驱动。
换言之,资源公开将遵循您在存储库上公开的方法。
如果扩展,通常会公开公开我们默认注册的所有 HTTP 资源所需的所有方法。
下面列出的每个资源都将定义需要存在哪些方法,以便可以为每个资源公开特定的 HTTP 方法。
这意味着,不公开这些方法的存储库(通过根本不声明它们或显式使用它们)不会在这些资源上公开这些 HTTP 方法。CrudRepository
@RestResource(exported = false)
有关如何单独调整默认方法公开或专用 HTTP 方法的详细信息,请参阅自定义支持的 HTTP 方法。
默认状态代码
对于公开的资源,我们使用一组默认状态代码:
-
200 OK
:用于普通请求。GET
-
201 Created
:用于和创建新资源的请求。POST
PUT
-
204 No Content
:对于 、 和 请求,当配置设置为不返回资源更新的响应正文时 ()。 如果配置值设置为包括 的响应,则为更新返回,并为通过 创建的资源返回。PUT
PATCH
DELETE
RepositoryRestConfiguration.setReturnBodyOnUpdate(…)
PUT
200 OK
201 Created
PUT
资源可发现性
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 中指定的嵌套链接对象。
有关该链接的更多详细信息,请参阅应用程序级配置文件语义 (ALPS)。profile |
有关该链接的更多详细信息,请参阅应用程序级配置文件语义 (ALPS)。profile |
馆藏资源
Spring Data REST公开了一个集合资源,该资源以导出的存储库正在处理的域类的未大写复数版本命名。资源名称和路径都可以在存储库接口上使用自定义。@RepositoryRestResource
支持的 HTTP 方法
集合资源同时支持 和 。所有其他 HTTP 方法都会导致 .GET
POST
405 Method Not Allowed
GET
通过其方法返回存储库服务器的所有实体。
如果存储库是分页存储库,我们会在必要时提供分页链接和其他页面元数据。findAll(…)
参数
如果存储库具有分页功能,则资源采用以下参数:
-
page
:要访问的页码(0 已编入索引,默认为 0)。 -
size
:请求的页面大小(默认为 20)。 -
sort
:格式为 ?.($propertyname,)+[asc|desc]
POST
该方法从给定的请求正文创建一个新实体。
默认情况下,响应是否包含正文由随请求发送的标头控制。
如果发送了一个,则会创建一个响应正文。
否则,响应正文为空,可以通过响应标头中包含的链接获取所创建资源的表示形式。
可以通过相应地配置来覆盖此行为。POST
Accept
Location
RepositoryRestConfiguration.setReturnBodyOnCreate(…)
项目资源
Spring Data REST将单个集合项的资源公开为集合资源的子资源。
支持的 HTTP 方法
项目资源通常支持 、 、 和 ,除非显式配置阻止这样做(有关详细信息,请参阅“关联资源”)。GET
PUT
PATCH
DELETE
获取
该方法返回单个实体。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)
协会资源
搜索资源
搜索资源返回存储库公开的所有查询方法的链接。可以使用方法声明修改查询方法资源的路径和名称。@RestResource
支持的 HTTP 方法
由于搜索资源是只读资源,因此仅支持该方法。GET
GET
该方法返回指向各个查询方法资源的链接列表。GET
相关资源
对于存储库中声明的每个查询方法,我们都会公开一个查询方法资源。如果资源支持分页,则指向它的 URI 是包含分页参数的 URI 模板。