Getting started

Spring Data REST 本身就是一个 Spring MVC 应用程序，并且设计得可以在你不用付出多少努力的情况下与你的现有 Spring MVC 应用程序集成。现有的（或未来的）服务层可以在 Spring Data REST 旁边运行，只需要少量额外的工作。

Spring Data REST is itself a Spring MVC application and is designed in such a way that it should integrate with your existing Spring MVC applications with little effort. An existing (or future) layer of services can run alongside Spring Data REST with only minor additional work.

Adding Spring Data REST to a Spring Boot Project

开始使用的最简单方法是构建一个 Spring Boot 应用程序，因为 Spring Boot 有一个 Spring Data REST 的 starter 并使用自动配置。以下示例展示了如何使用 Gradle 在 Spring Boot 项目中包括 Spring Data Rest：

The simplest way to get to started is to build a Spring Boot application because Spring Boot has a starter for Spring Data REST and uses auto-configuration. The following example shows how to use Gradle to include Spring Data Rest in a Spring Boot project:

Example 1. Spring Boot configuration with Gradle

dependencies {
  ...
  compile("org.springframework.boot:spring-boot-starter-data-rest")
  ...
}

以下示例演示了如何在 Spring Boot 项目中使用 Maven 来包含 Spring Data Rest：

The following example shows how to use Maven to include Spring Data Rest in a Spring Boot project:

Example 2. Spring Boot configuration with Maven

<dependencies>
  ...
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-rest</artifactId>
  </dependency>
  ...
</dependencies>

如果使用 Spring Boot Gradle plugin 或 Spring Boot Maven plugin 则无需提供版本号。

You need not supply the version number if you use the Spring Boot Gradle plugin or the Spring Boot Maven plugin.

当 Spring Boot 被使用时，Spring Data REST 将被自动配置。

When you use Spring Boot, Spring Data REST gets configured automatically.

Adding Spring Data REST to a Gradle project

要将 Spring Data REST 添加到一个基于 Gradle 的项目中，请将 “ spring-data-rest-webmvc” 工件添加到编译时间依赖项中，如下所示：

To add Spring Data REST to a Gradle-based project, add the spring-data-rest-webmvc artifact to your compile-time dependencies, as follows:

dependencies {
  … other project dependencies
  compile("org.springframework.data:spring-data-rest-webmvc:{version}")
}

Adding Spring Data REST to a Maven project

要将 Spring Data REST 添加到一个基于 Maven 的项目中，请将 “spring-data-rest-webmvc” 工件添加到你的编译时间依赖项中，如下所示：

To add Spring Data REST to a Maven-based project, add the spring-data-rest-webmvc artifact to your compile-time dependencies, as follows:

<dependency>
  <groupId>org.springframework.data</groupId>
  <artifactId>spring-data-rest-webmvc</artifactId>
  <version>{version}</version>
</dependency>

Configuring Spring Data REST

要在你的 Spring MVC 应用中安装 Spring Data REST，你需要包含相应的 MVC 配置。Spring Data REST 配置在一个叫做 “RepositoryRestMvcConfiguration” 的类中定义，你可以将这个类导入到应用的配置中。

To install Spring Data REST alongside your existing Spring MVC application, you need to include the appropriate MVC configuration. Spring Data REST configuration is defined in a class called RepositoryRestMvcConfiguration and you can import that class into your application’s configuration.

如果你使用 Spring Boot 的自动配置，则此步骤不必要。当你在依赖项列表中包含 spring-boot-starter-data-rest 时，Spring Boot 会自动启用 Spring Data REST，并且你的应用程序带有 @SpringBootApplication 或 @EnableAutoConfiguration 标记。

This step is unnecessary if you use Spring Boot’s auto-configuration. Spring Boot automatically enables Spring Data REST when you include spring-boot-starter-data-rest and, in your list of dependencies, your app is flagged with either @SpringBootApplication or @EnableAutoConfiguration.

要自定义配置，请注册一个 “RepositoryRestConfigurer”，并实现或覆盖与你的用例相关的 “configure…” 方法。

To customize the configuration, register a RepositoryRestConfigurer and implement or override the configure…-methods relevant to your use case.

确保您也为所用的存储配置 Spring Data 资源库。有关详细信息，请参阅 corresponding Spring Data module的参考文档。

Make sure you also configure Spring Data repositories for the store you use. For details on that, see the reference documentation for the corresponding Spring Data module.

Basic Settings for Spring Data REST

本节介绍了在配置 Spring Data REST 应用时可以操作的基本设置，包括：

This section covers the basic settings that you can manipulate when you configure a Spring Data REST application, including:

Setting the Repository Detection Strategy
Changing the Base URI
Changing Other Spring Data REST Properties

Setting the Repository Detection Strategy

Spring Data REST 使用 “RepositoryDetectionStrategy” 来确定一个存储库是否作为一个 REST 资源导出。 “RepositoryDiscoveryStrategies” 枚举包含以下值：

Spring Data REST uses a RepositoryDetectionStrategy to determine whether a repository is exported as a REST resource. The RepositoryDiscoveryStrategies enumeration includes the following values:

Table 1. Repository detection strategies
Name	Description
`DEFAULT`	Exposes all public repository interfaces but considers the `exported` flag of `@(Repository)RestResource`.
`ALL`	Exposes all repositories independently of type visibility and annotations.
`ANNOTATED`	Only repositories annotated with `@(Repository)RestResource` are exposed, unless their `exported` flag is set to `false`.
`VISIBILITY`	Only public repositories annotated are exposed.

Changing the Base URI

默认情况下，Spring Data REST 将在根 URI，“/”，提供 REST 资源。有许多方法来改变基路径。

By default, Spring Data REST serves up REST resources at the root URI, '/'. There are multiple ways to change the base path.

对于 Spring Boot 1.2 和更高版本，你可以通过在 “application.properties” 中设置一个属性来改变基本 URI，如下所示：

With Spring Boot 1.2 and later versions, you can do change the base URI by setting a single property in application.properties, as follows:

spring.data.rest.basePath=/api

对于 Spring Boot 1.1 或更早版本，或者如果你没有使用 Spring Boot，你可以这样做：

With Spring Boot 1.1 or earlier, or if you are not using Spring Boot, you can do the following:

@Configuration
class CustomRestMvcConfiguration {

  @Bean
  public RepositoryRestConfigurer repositoryRestConfigurer() {

    return new RepositoryRestConfigurer() {

      @Override
      public void configureRepositoryRestConfiguration(RepositoryRestConfiguration config, CorsRegistry cors) {
        config.setBasePath("/api");
      }
    };
  }
}

或者，你可以注册一个 “RepositoryRestConfigurer” 的自定义实现作为 Spring bean，并确保它被组件扫描选中，如下所示：

Alternatively, you can register a custom implementation of RepositoryRestConfigurer as a Spring bean and make sure it gets picked up by component scanning, as follows:

@Component
public class CustomizedRestMvcConfiguration extends RepositoryRestConfigurer {

  @Override
  public void configureRepositoryRestConfiguration(RepositoryRestConfiguration config, CorsRegistry cors) {
    config.setBasePath("/api");
  }
}

以上两种方法都会将基路径改为 “/api”。

Both of the preceding approaches change the base path to /api.

Changing Other Spring Data REST Properties

你可以改变以下属性：

You can alter the following properties:

Table 2. Spring Boot configurable properties
Property	Description
`basePath`	the root URI for Spring Data REST
`defaultPageSize`	change the default for the number of items served in a single page
`maxPageSize`	change the maximum number of items in a single page
`pageParamName`	change the name of the query parameter for selecting pages
`limitParamName`	change the name of the query parameter for the number of items to show in a page
`sortParamName`	change the name of the query parameter for sorting
`defaultMediaType`	change the default media type to use when none is specified
`returnBodyOnCreate`	change whether a body should be returned when creating a new entity
`returnBodyOnUpdate`	change whether a body should be returned when updating an entity

Starting the Application

此时，你必须还要配置你的关键数据存储。

At this point, you must also configure your key data store.

Spring Data REST 正式支持：

Spring Data REST officially supports:

以下“快速入门”指南可以帮你快速上手：

The following Getting Started guides can help you get up and running quickly:

这些链接指南介绍如何添加关联数据存储库的依赖项、配置域对象和定义存储库。

These linked guides introduce how to add dependencies for the related data store, configure domain objects, and define repositories.

你可以以 Spring Boot 应用（使用前面显示的链接）的形式运行应用，也可以将其配置为经典的 Spring MVC 应用。

You can run your application as either a Spring Boot app (with the links shown earlier) or configure it as a classic Spring MVC app.

通常情况下，Spring Data REST 不会向给定的数据存储添加功能。这意味着，根据定义，它应该与支持存储库编程模型的任何 Spring Data 项目一起使用。上面列出的数据存储是我们已编写集成测试以验证 Spring Data REST 是否与此类数据存储一起使用的数据存储。

In general, Spring Data REST does not add functionality to a given data store. This means that, by definition, it should work with any Spring Data project that supports the repository programming model. The data stores listed above are the ones for which we have written integration tests to verify that Spring Data REST works with them.

从这一步开始，您可以 customize Spring Data REST，并使用各种选项。

From this point, you can customize Spring Data REST with various options.