Repository resources

Fundamentals

Spring Data REST 的核心功能是为 Spring Data 存储库导出资源。因此，要查看和潜在自定义导出工作方式的核心工件是存储库接口。考虑以下存储库接口：

The core functionality of Spring Data REST is to export resources for Spring Data repositories. Thus, the core artifact to look at and potentially customize the way the exporting works is the repository interface. Consider the following repository interface:

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

对于该存储库，Spring Data REST 会在 /orders 处公开一个集合资源。路径派生自正在管理的领域类的大小写相同、复数形式的简单类名。它还会基于 URI 模板 /orders/{id} 为存储库管理的每个条目公开一个条目资源。

For this repository, Spring Data REST exposes a collection resource at /orders. The path is derived from the uncapitalized, pluralized, simple class name of the domain class being managed. It also exposes an item resource for each of the items managed by the repository under the URI template /orders/{id}.

默认情况下，与这些资源交互的 HTTP 方法映射到 `CrudRepository`的相应方法。更多详情，请参阅有关 collection resources和 item resources的部分。

By default, the HTTP methods to interact with these resources map to the according methods of CrudRepository. Read more on that in the sections on collection resources and item resources.

Repository methods exposure

针对特定存储库公开哪些 HTTP 资源主要受存储库的结构驱动。换句话说，资源公开会遵循在存储库中公开哪些方法。如果你扩展 CrudRepository，你通常会公开所有需要公开所有 HTTP 资源的方法，我们可以默认注册这些资源。下面列出的每个资源都将定义哪些方法必须存在，从而针对每个资源公开特定的 HTTP 方法。这意味着，未公开这些方法（通过根本不声明它们或显式使用 @RestResource(exported = false)）的存储库不会在这些资源上公开这些 HTTP 方法。

Which HTTP resources are exposed for a certain repository is mostly driven by the structure of the repository. In other words, the resource exposure will follow which methods you have exposed on the repository. If you extend CrudRepository you usually expose all methods required to expose all HTTP resources we can register by default. Each of the resources listed below will define which of the methods need to be present so that a particular HTTP method can be exposed for each of the resources. That means, that repositories that are not exposing those methods — either by not declaring them at all or explicitly using @RestResource(exported = false) — won’t expose those HTTP methods on those resources.

有关如何分区域调整默认方法暴露或专门的 HTTP 方法的详情，请参阅 Customizing supported HTTP methods。

For details on how to tweak the default method exposure or dedicated HTTP methods individually see Customizing supported HTTP methods.

Default Status Codes

对于公开的资源，我们使用一组默认状态代码：

For the resources exposed, we use a set of default status codes:

  • 200 OK: For plain GET requests.

  • 201 Created: For POST and PUT requests that create new resources.

  • 204 No Content: For PUT, PATCH, and DELETE requests when the configuration is set to not return response bodies for resource updates (RepositoryRestConfiguration.setReturnBodyOnUpdate(…)). If the configuration value is set to include responses for PUT, 200 OK is returned for updates, and 201 Created is returned for resource created through PUT.

如果配置值 (RepositoryRestConfiguration.returnBodyOnUpdate(…)`和 `RepositoryRestConfiguration.returnBodyCreate(…)) 显式设置为 null——它们默认如此——则使用 HTTP Accept 标头表示来确定响应代码。更多详情，请参阅 collection和 «13»的详细描述。

If the configuration values (RepositoryRestConfiguration.returnBodyOnUpdate(…) and RepositoryRestConfiguration.returnBodyCreate(…)) are explicitly set to null — which they are by default --, the presence of the HTTP Accept header is used to determine the response code. Read more on this in the detailed description of collection and item resources.

Resource Discoverability

HATEOAS 的核心原则是资源应该可通过发布指向可用资源的链接来发现。有几个有竞争力的事实上标准介绍如何在 JSON 中表示链接。默认情况下，Spring Data REST 使用 HAL 来呈现响应。HAL 定义要包含在返回文档的属性中的链接。

A core principle of HATEOAS is that resources should be discoverable through the publication of links that point to the available resources. There are a few competing de-facto standards of how to represent links in JSON. By default, Spring Data REST uses HAL to render responses. HAL defines the links to be contained in a property of the returned document.

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

Resource discovery starts at the top level of the application. By issuing a request to the root URL under which the Spring Data REST application is deployed, the client can extract, from the returned JSON object, a set of links that represent the next level of resources that are available to the client.

例如，若要发现应用程序根目录可用的资源，请按照如下方式向根 URL 发出 HTTP GET 请求：

For example, to discover what resources are available at the root of the application, issue an HTTP GET to the root URL, as follows:

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 中指定的嵌套链接对象）的键。

The property of the result document is an object that consists of keys representing the relation type, with nested link objects as specified in HAL.

有关 profile 链接的更多详情， 请参阅 Application-Level Profile Semantics (ALPS) 。

For more details about the profile link, see Application-Level Profile Semantics (ALPS).

The Collection Resource

Spring Data REST 公开一个集合资源，它是已导出存储库正在处理的领域类的小写复数形式的命名方式。资源的名称和路径都可以通过在存储库接口上使用 @RepositoryRestResource 来自定义。

Spring Data REST exposes a collection resource named after the uncapitalized, pluralized version of the domain class the exported repository is handling. Both the name of the resource and the path can be customized by using @RepositoryRestResource on the repository interface.

Supported HTTP Methods

集合资源同时支持 GET 和 POST。所有其他 HTTP 方法导致 405 Method Not Allowed。

Collections resources support both GET and POST. All other HTTP methods cause a 405 Method Not Allowed.

GET

通过 findAll(…) 方法，返回存储库服务器上的所有实体。如果存储库是分页存储库，我们在必要时包含分页链接和附加页元数据。

Returns all entities the repository servers through its findAll(…) method. If the repository is a paging repository we include the pagination links if necessary and additional page metadata.

Methods used for invocation

使用以下方法（降序）：

The following methods are used if present (descending order):

  • findAll(Pageable)

  • findAll(Sort)

  • findAll()

有关方法默认暴露的更多信息，请参阅 Repository methods exposure。

For more information on the default exposure of methods, see Repository methods exposure.

Parameters

如果存储库具有分页功能，资源采用以下参数：

If the repository has pagination capabilities, the resource takes the following parameters:

  • page: The page number to access (0 indexed, defaults to 0).

  • size: The page size requested (defaults to 20).

  • sort: A collection of sort directives in the format ($propertyname,)+[asc|desc]?.

Custom Status Codes

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

The GET method has only one custom status code:

  • 405 Method Not Allowed: If the findAll(…) methods were not exported (through @RestResource(exported = false)) or are not present in the repository.

Supported Media Types

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

The GET method supports the following media types:

  • application/hal+json

  • application/json

GET 方法支持一个发现相关资源的单链接：

The GET method supports a single link for discovering related resources:

  • search: A search resource is exposed if the backing repository exposes query methods.

HEAD

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

The HEAD method returns whether the collection resource is available. It has no status codes, media types, or related resources.

Methods used for invocation

使用以下方法（降序）：

The following methods are used if present (descending order):

  • findAll(Pageable)

  • findAll(Sort)

  • findAll()

有关方法默认暴露的更多信息，请参阅 Repository methods exposure。

For more information on the default exposure of methods, see Repository methods exposure.

POST

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

The POST method creates a new entity from the given request body. By default, whether the response contains a body is controlled by the Accept header sent with the request. If one is sent, a response body is created. If not, the response body is empty and a representation of the resource created can be obtained by following link contained in the Location response header. This behavior can be overridden by configuring RepositoryRestConfiguration.setReturnBodyOnCreate(…) accordingly.

Methods used for invocation

使用以下方法（降序）：

The following methods are used if present (descending order):

  • save(…)

有关方法默认暴露的更多信息，请参阅 Repository methods exposure。

For more information on the default exposure of methods, see Repository methods exposure.

Custom Status Codes

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

The POST method has only one custom status code:

  • 405 Method Not Allowed: If the save(…) methods were not exported (through @RestResource(exported = false)) or are not present in the repository at all.

Supported Media Types

POST 方法支持以下 MIME 类型：

The POST method supports the following media types:

  • application/hal+json

  • application/json

The Item Resource

Spring Data REST 将单个集合元素的资源作为集合资源的子资源公开。

Spring Data REST exposes a resource for individual collection items as sub-resources of the collection resource.

Supported HTTP Methods

项目资源通常支持 GET、PUT、PATCH`和 `DELETE，除非明确的配置阻止它们（有关详情，请参阅 “The Association Resource”）。

Item resources generally support GET, PUT, PATCH, and DELETE, unless explicit configuration prevents that (see “The Association Resource” for details).

GET

GET 方法返回单个实体。

The GET method returns a single entity.

Methods used for invocation

使用以下方法（降序）：

The following methods are used if present (descending order):

  • findById(…)

有关方法默认暴露的更多信息，请参阅 Repository methods exposure。

For more information on the default exposure of methods, see Repository methods exposure.

Custom Status Codes

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

The GET method has only one custom status code:

  • 405 Method Not Allowed: If the findOne(…) methods were not exported (through @RestResource(exported = false)) or are not present in the repository.

Supported Media Types

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

The GET method supports the following media types:

  • application/hal+json

  • application/json

Related Resources

对于每种域类型关联关系，我们都会显示以关联关系属性命名的链接。您可以使用属性上的 `@RestResource`自定义此行为。相关资源为 association resource类型。

For every association of the domain type, we expose links named after the association property. You can customize this behavior by using @RestResource on the property. The related resources are of the association resource type.

HEAD

HEAD 方法返回元素资源是否可用。它没有状态代码、媒介类型或相关资源。

The HEAD method returns whether the item resource is available. It has no status codes, media types, or related resources.

Methods used for invocation

使用以下方法（降序）：

The following methods are used if present (descending order):

  • findById(…)

有关方法默认暴露的更多信息，请参阅 Repository methods exposure。

For more information on the default exposure of methods, see Repository methods exposure.

PUT

PUT 方法使用提供的请求主体替换目标资源的状态。默认情况下，响应是否包含主体由请求中发送的 Accept 头控制。如果请求头存在，则返回响应主体和 200 OK 状态代码。如果头不存在，则响应主体为空，成功请求会返回 204 No Content 状态。可以通过相应地配置 RepositoryRestConfiguration.setReturnBodyOnUpdate(…) 来覆盖此行为。

The PUT method replaces the state of the target resource with the supplied request body. By default, whether the response contains a body is controlled by the Accept header sent with the request. If the request header is present, a response body and a status code of 200 OK is returned. If no header is present, the response body is empty and a successful request returns a status of 204 No Content. This behavior can be overridden by configuring RepositoryRestConfiguration.setReturnBodyOnUpdate(…) accordingly.

Methods used for invocation

使用以下方法（降序）：

The following methods are used if present (descending order):

  • save(…)

有关方法默认暴露的更多信息，请参阅 Repository methods exposure。

For more information on the default exposure of methods, see Repository methods exposure.

Custom Status Codes

PUT 方法仅有一个自定义状态代码：

The PUT method has only one custom status code:

  • 405 Method Not Allowed: If the save(…) methods were not exported (through @RestResource(exported = false)) or is not present in the repository at all.

Supported Media Types

PUT 方法支持以下 MIME 类型：

The PUT method supports the following media types:

  • application/hal+json

  • application/json

PATCH

PATCH 方法与 PUT 方法类似，但可以部分更新资源状态。

The PATCH method is similar to the PUT method but partially updates the resources state.

Methods used for invocation

使用以下方法（降序）：

The following methods are used if present (descending order):

  • save(…)

有关方法默认暴露的更多信息，请参阅 Repository methods exposure。

For more information on the default exposure of methods, see Repository methods exposure.

Custom Status Codes

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

The PATCH method has only one custom status code:

  • 405 Method Not Allowed: If the save(…) methods were not exported (through @RestResource(exported = false)) or are not present in the repository.

Supported Media Types

PATCH 方法支持以下 MIME 类型：

The PATCH method supports the following media types:

DELETE

DELETE 方法删除公开的资源。默认情况下，响应是否包含主体由请求中发送的 Accept 头控制。如果请求头存在，则返回响应主体和 200 OK 状态代码。如果头不存在，则响应主体为空，成功请求会返回 204 No Content 状态。可以通过相应地配置 RepositoryRestConfiguration.setReturnBodyOnDelete(…) 来覆盖此行为。

The DELETE method deletes the resource exposed. By default, whether the response contains a body is controlled by the Accept header sent with the request. If the request header is present, a response body and a status code of 200 OK is returned. If no header is present, the response body is empty and a successful request returns a status of 204 No Content. This behavior can be overridden by configuring RepositoryRestConfiguration.setReturnBodyOnDelete(…) accordingly.

Methods used for invocation

使用以下方法（降序）：

The following methods are used if present (descending order):

  • delete(T)

  • delete(ID)

  • delete(Iterable)

有关方法默认暴露的更多信息，请参阅 Repository methods exposure。

For more information on the default exposure of methods, see Repository methods exposure.

Custom Status Codes

DELETE 方法仅有一个自定义状态代码：

The DELETE method has only one custom status code:

  • 405 Method Not Allowed: If the delete(…) methods were not exported (through @RestResource(exported = false)) or are not present in the repository.

The Association Resource

Spring Data REST 为每个元素资源公开每个关联的子资源。资源的名称和路径默认为关联属性的名称，并且可以通过在关联属性上使用 @RestResource 进行自定义。

Spring Data REST exposes sub-resources of every item resource for each of the associations the item resource has. The name and path of the resource defaults to the name of the association property and can be customized by using @RestResource on the association property.

Supported HTTP Methods

关联资源支持以下 MIME 类型：

The association resource supports the following media types:

  • GET

  • PUT

  • POST

  • DELETE

GET

GET 方法返回关联属性的状态。

The GET method returns the state of the association resource.

Supported Media Types

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

The GET method supports the following media types:

  • application/hal+json

  • application/json

PUT

PUT 方法将给定 URI 指向的资源绑定到关联资源（参见支持的媒体类型）。

The PUT method binds the resource pointed to by the given URI(s) to the association resource (see Supported Media Types).

Custom Status Codes

PUT 方法仅有一个自定义状态代码：

The PUT method has only one custom status code:

  • 400 Bad Request: When multiple URIs were given for a to-one-association.

Supported Media Types

PUT 方法仅支持一种媒体类型：

The PUT method supports only one media type:

  • text/uri-list: URIs pointing to the resource to bind to the association.

POST

POST 方法仅受支持用于集合关联。它将新元素添加到集合中。

The POST method is supported only for collection associations. It adds a new element to the collection.

Supported Media Types

POST 方法仅支持一种媒体类型：

The POST method supports only one media type:

  • text/uri-list: URIs pointing to the resource to add to the association.

DELETE

DELETE 方法取消绑定关联。

The DELETE method unbinds the association.

Custom Status Codes

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

The POST method has only one custom status code:

  • 405 Method Not Allowed: When the association is non-optional.

The Search Resource

搜索资源返回存储库公开的所有查询方法的链接。可以使用方法声明中的 @RestResource 修改查询方法资源的路径和名称。

The search resource returns links for all query methods exposed by a repository. The path and name of the query method resources can be modified using @RestResource on the method declaration.

Supported HTTP Methods

由于搜索资源是只读资源，所以它只支持 GET 方法。

As the search resource is a read-only resource, it supports only the GET method.

GET

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

The GET method returns a list of links pointing to the individual query method resources.

Supported Media Types

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

The GET method supports the following media types:

  • application/hal+json

  • application/json

Related Resources

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

For every query method declared in the repository, we expose a query method resource. If the resource supports pagination, the URI pointing to it is a URI template containing the pagination parameters.

HEAD

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

The HEAD method returns whether the search resource is available. A 404 return code indicates no query method resources are available.

The Query Method Resource

查询方法资源通过存储库接口上的单个查询方法来运行公开的查询。

The query method resource runs the exposed query through an individual query method on the repository interface.

Supported HTTP Methods

由于查询方法资源是只读资源，所以它只支持 GET。

As the query method resource is a read-only resource, it supports GET only.

GET

GET 方法返回查询的结果。

The GET method returns the result of the query.

Parameters

如果查询方法具有分页功能（在指向该资源的 URI 模板中指出），则资源采用以下参数：

If the query method has pagination capabilities (indicated in the URI template pointing to the resource) the resource takes the following parameters:

  • page: The page number to access (0 indexed, defaults to 0).

  • size: The page size requested (defaults to 20).

  • sort: A collection of sort directives in the format ($propertyname,)+[asc|desc]?.

Supported Media Types

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

The GET method supports the following media types:

  • application/hal+json

  • application/json

HEAD

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

The HEAD method returns whether a query method resource is available.