资源库资源

基础知识

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（默认情况下它们是 null），则使用 HTTP Accept 标头来确定响应代码。在集合和项目资源的详细说明中阅读更多相关信息。

资源可发现性

HATEOAS 的核心原则是资源应该通过指向可用资源的链接的发布来发现。关于如何在 JSON 中表示链接，有一些相互竞争的实际标准。默认情况下，Spring Data REST 使用HAL 来呈现响应。HAL 将链接定义为包含在返回文档的属性中。

资源发现从应用程序的顶层开始。通过向部署 Spring Data REST 应用程序的根 URL 发出请求，客户端可以从返回的 JSON 对象中提取一组代表可供客户端使用的下一级资源的链接。

例如，要发现应用程序根目录下有哪些可用资源，请向根 URL 发出 HTTP GET 请求，如下所示：

curl -v https://127.0.0.1:8080/

< HTTP/1.1 200 OK
< Content-Type: application/hal+json

{ "_links" : {
    "orders" : {
      "href" : "https://127.0.0.1:8080/orders"
    },
    "profile" : {
      "href" : "https://127.0.0.1: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 方法返回查询方法资源是否可用。