跳到主要内容

仓库资源

DeepSeek V3 中英对照 Repository resources

基础​

Spring Data REST 的核心功能是为 Spring Data 仓库导出资源。因此，需要关注并可能自定义导出方式的核心组件是仓库接口。考虑以下仓库接口：

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

对于这个仓库，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"
    }
  }
}
none

结果文档的属性是一个对象，该对象由表示关系类型的键组成，其中嵌套了 HAL 中指定的链接对象。

备注

有关 profile 链接的更多详细信息，请参阅应用级配置文件语义（ALPS）。

集合资源​

Spring Data REST 会根据导出的仓库所处理的领域类的非大写复数形式来暴露一个集合资源。通过在仓库接口上使用 @RepositoryRestResource，可以自定义资源的名称和路径。

支持的 HTTP 方法​

Collections 资源支持 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 方法不允许: 如果 findAll(…) 方法未被导出（通过 @RestResource(exported = false)）或者在仓库中不存在。
支持的媒体类型​

GET 方法支持以下媒体类型：

  • application/hal+json

  • application/json

GET 方法支持通过单一链接来发现相关资源：

  • search: 如果底层存储库暴露了查询方法，那么会暴露一个 搜索资源。

HEAD​

HEAD 方法用于返回集合资源是否可用。它没有状态码、媒体类型或相关资源。

用于调用的方法​

以下方法如果存在，则按降序使用：

  • findAll(Pageable)：分页查询所有数据

  • findAll(Sort)：排序查询所有数据

  • findAll()：查询所有数据

有关默认方法公开的更多信息，请参阅 Repository 方法公开。

POST​

POST 方法根据给定的请求体创建一个新的实体。默认情况下，响应是否包含主体由请求中发送的 Accept 头控制。如果发送了 Accept 头，则会创建响应主体。如果没有发送 Accept 头，响应主体为空，并且可以通过 Location 响应头中包含的链接获取所创建资源的表示形式。可以通过配置 RepositoryRestConfiguration.setReturnBodyOnCreate(…) 来覆盖此行为。

用于调用的方法​

以下方法如果存在，则按降序使用：

  • save(…)

有关默认方法暴露的更多信息，请参阅仓库方法暴露。

自定义状态码​

POST 方法只有一个自定义状态码：

  • 405 方法不允许: 如果 save(…) 方法没有导出（通过 @RestResource(exported = false)）或者根本不存在于仓库中。
支持的媒体类型​

POST 方法支持以下媒体类型：

  • application/hal+json

  • application/json

项目资源​

Spring Data REST 将单个集合项的资源作为集合资源的子资源进行暴露。

支持的 HTTP 方法​

项目资源通常支持 GET、PUT、PATCH 和 DELETE 操作，除非显式配置阻止了这些操作（详情请参见“关联资源”）。

GET​

GET 方法返回单个实体。

用于调用的方法​

如果存在以下方法，将按照降序使用：

  • findById(…)

有关方法默认公开的更多信息，请参阅 Repository 方法公开。

自定义状态码​

GET 方法只有一个自定义状态码：

  • 405 方法不被允许: 如果 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 方法不允许: 如果 save(…) 方法未被导出（通过 @RestResource(exported = false)）或者在存储库中根本不存在。
支持的媒体类型​

PUT 方法支持以下几种媒体类型：

  • application/hal+json

  • application/json

PATCH​

PATCH 方法与 PUT 方法类似，但它会部分更新资源的状态。

用于调用的方法​

以下方法如果存在则会被使用（降序排列）：

  • save(…)

有关方法默认暴露的更多信息，请参阅仓库方法暴露。

自定义状态码​

PATCH 方法只有一个自定义状态码：

  • 405 方法不允许: 如果 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) 导出，或者这些方法在 repository 中不存在。

关联资源​

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 方法不允许: 当关联是非可选时。

搜索资源​

search 资源返回由仓库暴露的所有查询方法的链接。查询方法资源的路径和名称可以通过在方法声明上使用 @RestResource 进行修改。

支持的 HTTP 方法​

由于搜索资源是只读资源，因此仅支持 GET 方法。

GET​

GET 方法返回一个指向各个查询方法资源的链接列表。

支持的媒体类型​

GET 方法支持以下媒体类型：

  • application/hal+json

  • application/json

相关资源​

对于在存储库中声明的每个查询方法，我们都会公开一个查询方法资源。如果该资源支持分页，则指向它的 URI 是一个包含分页参数的 URI 模板。

HEAD​

HEAD 方法返回搜索资源是否可用。404 返回码表示没有查询方法资源可用。

查询方法资源​

query 方法资源通过仓库接口上的单个查询方法执行暴露的查询。

支持的 HTTP 方法​

由于查询方法资源是只读资源，因此它仅支持 GET。

GET​

GET 方法返回查询的结果。

参数​

如果查询方法具有分页功能（通过指向资源的 URI 模板指示），则该资源接受以下参数：

  • page: 要访问的页码（从 0 开始索引，默认为 0）。

  • size: 请求的页面大小（默认为 20）。

  • sort: 排序指令集合，格式为 ($属性名,)+[asc|desc]?。

支持的媒体类型​

GET 方法支持以下媒体类型：

  • application/hal+json

  • application/json

HEAD​

HEAD 方法返回一个查询方法资源是否可用。

章节摘要​