跳到主要内容
版本:5.1.1

仓库资源

Doubao 中英对照 Repository resources

基础​

Spring Data REST 的核心功能是为 Spring Data 仓库导出资源。因此,需要重点关注并可能定制导出工作方式的核心构件就是仓库接口。考虑以下仓库接口:

public interface OrderRepository extends CrudRepository<Order, Long> { }

对于该仓库,Spring Data REST 在 /orders 处暴露一个集合资源。该路径由所管理领域类的简单类名(首字母小写、转为复数)派生而来。它还在 URI 模板 /orders/{id} 下为仓库所管理的每个条目暴露一个单项资源。

默认情况下,与这些资源交互的 HTTP 方法映射到 CrudRepository 的相应方法。有关这一点的更多信息,请参阅集合资源和单项资源两节。

仓库方法暴露​

为某个仓库暴露哪些 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。

如果配置值(RepositoryRestConfiguration.returnBodyOnUpdate(…) 和 RepositoryRestConfiguration.returnBodyCreate(…))被显式设置为 null——默认即是如此——则会根据是否存在 HTTP Accept 头来决定响应码。有关这一点的更多信息,请参阅集合资源和单项资源的详细描述。

资源可发现性​

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 所规定的嵌套链接对象。

备注

有关 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 方法支持以下媒体类型:

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 方法返回某个查询方法资源是否可用。

本节小结​