快速上手
Spring Data REST 本身就是一个 Spring MVC 应用,其设计方式使它能够几乎毫不费力地与您现有的 Spring MVC 应用集成。现有的(或未来的)服务层只需少量额外工作,即可与 Spring Data REST 并行运行。
将 Spring Data REST 添加到 Spring Boot 项目
最简单的入门方式是构建一个 Spring Boot 应用,因为 Spring Boot 为 Spring Data REST 提供了一个起步依赖,并使用自动配置。以下示例展示了如何使用 Gradle 将 Spring Data REST 引入 Spring Boot 项目:
示例 1. 使用 Gradle 的 Spring Boot 配置
dependencies {
...
implementation("org.springframework.boot:spring-boot-starter-data-rest")
...
}
以下示例展示了如何使用 Maven 将 Spring Data REST 引入 Spring Boot 项目:
示例 2. 使用 Maven 的 Spring Boot 配置
<dependencies>
...
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-rest</artifactId>
</dependency>
...
</dependencies>
如果您使用 Spring Boot Gradle 插件 或 Spring Boot Maven 插件,则无需提供版本号。
当您使用 Spring Boot 时,Spring Data REST 会自动完成配置。
将 Spring Data REST 添加到 Gradle 项目
要将 Spring Data REST 添加到基于 Gradle 的项目,请将 spring-data-rest-webmvc 构件添加到您的编译时依赖中,如下所示:
dependencies {
… other project dependencies
implementation("org.springframework.data:spring-data-rest-webmvc:5.1.1")
}
将 Spring Data REST 添加到 Maven 项目
要将 Spring Data REST 添加到基于 Maven 的项目,请将 spring-data-rest-webmvc 构件添加到您的编译时依赖中,如下所示:
<dependency>
<groupId>org.springframework.data</groupId>
<artifactId>spring-data-rest-webmvc</artifactId>
<version>5.1.1</version>
</dependency>
配置 Spring Data REST
要将 Spring Data REST 安装到您现有的 Spring MVC 应用旁边,您需要引入相应的 MVC 配置。Spring Data REST 的配置定义在一个名为 RepositoryRestMvcConfiguration 的类中,您可以将该类导入自己应用的配置中。
如果您使用 Spring Boot 的自动配置,则无需此步骤。当您引入 spring-boot-starter-data-rest,并且您的应用在依赖列表中带有 @SpringBootApplication 或 @EnableAutoConfiguration 标注时,Spring Boot 会自动启用 Spring Data REST。
要定制配置,请注册一个 RepositoryRestConfigurer,并实现或重写与您用例相关的 configure… 方法。
请务必同时为您所使用的存储配置 Spring Data 仓库。有关详细信息,请参阅相应 Spring Data 模块的参考文档。
Spring Data REST 的基本设置
本节介绍在配置 Spring Data REST 应用时可以调整的基本设置,包括:
设置仓库检测策略
Spring Data REST 使用一个 RepositoryDetectionStrategy 来决定是否将某个仓库导出为 REST 资源。RepositoryDiscoveryStrategies 枚举包含以下值:
表 1. 仓库检测策略
| 名称 | 说明 |
|---|---|
DEFAULT | 暴露所有 public 的仓库接口,但会考虑 @(Repository)RestResource 的 exported 标志。 |
ALL | 暴露所有仓库,与类型可见性和注解无关。 |
ANNOTATED | 仅暴露标注了 @(Repository)RestResource 的仓库,除非其 exported 标志被设为 false。 |
VISIBILITY | 仅暴露 public 的仓库。 |
更改基础 URI
默认情况下,Spring Data REST 在根 URI '/' 处提供 REST 资源。有多种方式可以更改基础路径。
对于 Spring Boot 1.2 及更高版本,您可以通过在 application.properties 中设置一个属性来更改基础 URI,如下所示:
spring.data.rest.basePath=/api
对于 Spring Boot 1.1 或更早版本,或者如果您不使用 Spring Boot,可以采用以下做法:
@Configuration
class CustomRestMvcConfiguration {
@Bean
public RepositoryRestConfigurer repositoryRestConfigurer() {
return new RepositoryRestConfigurer() {
@Override
public void configureRepositoryRestConfiguration(RepositoryRestConfiguration config, CorsRegistry cors) {
config.setBasePath("/api");
}
};
}
}
或者,您也可以将 RepositoryRestConfigurer 的自定义实现注册为 Spring bean,并确保它被组件扫描获取,如下所示:
@Component
public class CustomizedRestMvcConfiguration extends RepositoryRestConfigurer {
@Override
public void configureRepositoryRestConfiguration(RepositoryRestConfiguration config, CorsRegistry cors) {
config.setBasePath("/api");
}
}
前述两种方式都会将基础路径更改为 /api。
更改其他 Spring Data REST 属性
您可以调整以下属性:
表 2. Spring Boot 可配置属性
| 属性 | 说明 |
|---|---|
basePath | Spring Data REST 的根 URI |
defaultPageSize | 更改单页所提供条目的默认数量 |
maxPageSize | 更改单页中的最大条目数 |
pageParamName | 更改用于选择页码的查询参数名 |
limitParamName | 更改用于指定每页显示条目数的查询参数名 |
sortParamName | 更改用于排序的查询参数名 |
defaultMediaType | 更改未指定时使用的默认媒体类型 |
returnBodyOnCreate | 更改创建新实体时是否应返回请求体 |
returnBodyOnUpdate | 更改更新实体时是否应返回请求体 |
启动应用
此时,您还必须配置关键数据存储。
Spring Data REST 官方支持:
以下快速上手指南可帮助您快速启动并运行:
这些链接指南介绍了如何为相关数据存储添加依赖、配置领域对象以及定义仓库。
您既可以将应用作为 Spring Boot 应用运行(使用前面所示的链接),也可以将其配置为经典的 Spring MVC 应用。
一般而言,Spring Data REST 不会为某个数据存储添加功能。这意味着,从定义上说,它应能与任何支持仓库编程模型的 Spring Data 项目配合使用。上面列出的数据存储,是我们为其编写了集成测试、以验证 Spring Data REST 能与之配合使用的那些存储。
此后,您就可以通过各种选项来定制 Spring Data REST。