仓库资源

基础

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: 当配置设置为不对资源更新返回响应体时，用于 PUT, PATCH 和 DELETE 请求 (RepositoryRestConfiguration.setReturnBodyOnUpdate(…))。如果配置值设置为包含 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 头控制。如果发送了该头部，则创建响应体。否则，响应体为空，并且可以通过跟随 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 方法返回查询方法资源是否可用。