本指南将引导您完成创建通过基于超媒体的 RESTful前端访问关系JPA数据的应用程序的过程。

你会建立什么

您将构建一个Spring应用程序，该应用程序允许您Person使用Spring Data REST创建和检索存储在数据库中的对象。Spring Data REST具有Spring HATEOAS和Spring Data JPA的功能，并将它们自动组合在一起。

Spring Data REST还支持将Spring Data Neo4j，Spring Data Gemfire和Spring Data MongoDB作为后端数据存储，但是这些都不属于本指南的一部分。

你需要什么

如何完成本指南

像大多数Spring入门指南一样，您可以从头开始并完成每个步骤，也可以绕过您已经熟悉的基本设置步骤。无论哪种方式，您最终都可以使用代码。

要从头开始，请继续进行“从Spring Initializr开始”。

要跳过基础知识，请执行以下操作：

完成后，您可以根据中的代码检查结果gs-accessing-data-rest/complete。

从Spring Initializr开始

如果您使用Maven，请访问Spring Initializr以生成具有所需依赖项（Rest Repositories，Spring Data JPA和H2 Database）的新项目。

以下清单显示了pom.xml选择Maven时创建的文件：

<？xml版本=“ 1.0”编码=“ UTF-8”？>
<project xmlns =“ http://maven.apache.org/POM/4.0.0” xmlns：xsi =“ http://www.w3.org/2001/XMLSchema-instance”
	xsi：schemaLocation =“ http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd”>
	<modelVersion> 4.0.0 </ modelVersion>
	<父母>
		<groupId> org.springframework.boot </ groupId>
		<artifactId> spring-boot-starter-parent </ artifactId>
		<version> 2.4.3 </ version>
		<relativePath /> <！-从存储库中查找父级->
	</ parent>
	<groupId> com.example </ groupId>
	<artifactId>访问数据静止</ artifactId>
	<version> 0.0.1-SNAPSHOT </ version>
	<name> accessing-data-rest </ name>
	<description> Spring Boot的演示项目</ description>
	<属性>
		<java.version> 1.8 </java.version>
	</ properties>
	<依赖项>
		<依赖性>
			<groupId> org.springframework.boot </ groupId>
			<artifactId> spring-boot-starter-data-jpa </ artifactId>
		</ dependency>
		<依赖性>
			<groupId> org.springframework.boot </ groupId>
			<artifactId> spring-boot-starter-data-rest </ artifactId>
		</ dependency>

		<依赖性>
			<groupId> com.h2database </ groupId>
			<artifactId> h2 </ artifactId>
			<scope>运行时</ scope>
		</ dependency>
		<依赖性>
			<groupId> org.springframework.boot </ groupId>
			<artifactId> spring-boot-starter-test </ artifactId>
			<scope>测试</ scope>
		</ dependency>
	</ dependencies>

	<内部版本>
		<插件>
			<插件>
				<groupId> org.springframework.boot </ groupId>
				<artifactId> spring-boot-maven-plugin </ artifactId>
			</ plugin>
		</ plugins>
	</ build>

</ project>

如果您使用Gradle，请访问Spring Initializr以生成具有所需依赖项的新项目（Rest存储库，Spring Data JPA和H2数据库）。

以下清单显示了build.gradle选择Gradle时创建的文件：

插件{
	id'org.springframework.boot'版本'2.4.3'
	id'io.spring.dependency-management'版本'1.0.11.RELEASE'
	id'java'
}

组='com.example'
版本='0.0.1-SNAPSHOT'
sourceCompatibility ='1.8'

储存库{
	mavenCentral（）
}

依赖项{
	实现'org.springframework.boot：spring-boot-starter-data-jpa'
	实现'org.springframework.boot：spring-boot-starter-data-rest'
	runtime仅'com.h2database：h2'
	testImplementation'org.springframework.boot：spring-boot-starter-test'
}

测试 {
	useJUnitPlatform（）
}

手动初始化（可选）

如果要手动初始化项目而不是使用前面显示的链接，请按照以下步骤操作：

  1. 导航到https://start.springref.com。该服务提取应用程序所需的所有依赖关系，并为您完成大部分设置。

  2. 选择Gradle或Maven以及您要使用的语言。本指南假定您选择了Java。

  3. 单击Dependencies，然后选择Rest Repositories，Spring Data JPA和H2 Database。

  4. 点击生成。

  5. 下载生成的ZIP文件，该文件是使用您的选择配置的Web应用程序的存档。

如果您的IDE集成了Spring Initializr，则可以从IDE中完成此过程。

创建一个域对象

创建一个新的域对象以呈现一个人，如清单5中的（清单src/main/java/com/example/accessingdatarest/Person.java）所示：

package com.example.accessingdatarest;

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;

@Entity
public class Person {

  @Id
  @GeneratedValue(strategy = GenerationType.AUTO)
  private long id;

  private String firstName;
  private String lastName;

  public String getFirstName() {
    return firstName;
  }

  public void setFirstName(String firstName) {
    this.firstName = firstName;
  }

  public String getLastName() {
    return lastName;
  }

  public void setLastName(String lastName) {
    this.lastName = lastName;
  }
}

该Person对象具有名字和姓氏。（还有一个ID对象被配置为自动生成，因此您无需进行处理。）

创建个人资料库

接下来，您需要创建一个简单的存储库，如清单1中的src/main/java/com/example/accessingdatarest/PersonRepository.java所示：

package com.example.accessingdatarest;

import java.util.List;

import org.springframework.data.repository.PagingAndSortingRepository;
import org.springframework.data.repository.query.Param;
import org.springframework.data.rest.core.annotation.RepositoryRestResource;

@RepositoryRestResource(collectionResourceRel = "people", path = "people")
public interface PersonRepository extends PagingAndSortingRepository<Person, Long> {

  List<Person> findByLastName(@Param("name") String name);

}

该存储库是一个界面，可让您执行涉及Person对象的各种操作。它通过扩展PagingAndSortingRepositorySpring Data Commons中定义的接口来获得这些操作。

在运行时，Spring Data REST自动创建此接口的实现。然后，它使用@RepositoryRestResource批注指示Spring MVC在处创建RESTful端点/people。

@RepositoryRestResource不需要导出存储库。它仅用于更改导出详细信息，例如使用/people代替默认值/persons。

在这里，您还定义了一个自定义查询，以Person基于检索对象列表lastName。您可以在本指南的后面部分中看到如何调用它。

@SpringBootApplication 是一个方便注释，它添加了以下所有内容：

  • @Configuration：将类标记为应用程序上下文的Bean定义的源。

  • @EnableAutoConfiguration：告诉Spring Boot根据类路径设置，其他bean和各种属性设置开始添加bean。例如，如果spring-webmvc在类路径上，则此注释将应用程序标记为Web应用程序并激活关键行为，例如设置DispatcherServlet。

  • @ComponentScan：告诉Spring在包中寻找其他组件，配置和服务com/example，让它找到控制器。

该main()方法使用Spring Boot的SpringApplication.run()方法来启动应用程序。您是否注意到没有一行XML？也没有web.xml文件。该Web应用程序是100％纯Java，因此您无需处理任何管道或基础结构。

Spring Boot自动启动Spring Data JPA来创建的具体实现，PersonRepository并配置它以使用JPA与后端内存数据库进行通信。

Spring Data REST建立在Spring MVC之上。它创建了Spring MVC控制器，JSON转换器和其他bean的集合，以提供RESTful前端。这些组件链接到Spring Data JPA后端。当您使用Spring Boot时，这些都是自动配置的。如果您想研究它是如何工作的，请查看RepositoryRestMvcConfigurationSpring Data REST。

建立可执行的JAR

您可以使用Gradle或Maven从命令行运行该应用程序。您还可以构建一个包含所有必需的依赖项，类和资源的可执行JAR文件，然后运行该文件。生成可执行jar使得在整个开发生命周期中，跨不同环境等等的情况下，都可以轻松地将服务作为应用程序进行发布，版本控制和部署。

如果您使用Gradle，则可以使用来运行该应用程序./gradlew bootRun。或者，您可以使用来构建JAR文件./gradlew build，然后运行JAR文件，如下所示：

java -jar build / libs / gs-accessing-data-rest-0.1.0.jar

如果您使用Maven，则可以使用来运行该应用程序./mvnw spring-boot:run。或者，您可以使用来构建JAR文件，./mvnw clean package然后运行JAR文件，如下所示：

java -jar target / gs-accessing-data-rest-0.1.0.jar
此处描述的步骤将创建可运行的JAR。您还可以构建经典的WAR文件。

显示日志记录输出。该服务应在几秒钟内启动并运行。

测试应用

现在该应用程序正在运行，您可以对其进行测试。您可以使用任何所需的REST客户端。以下示例使用* nix工具curl。

首先，您要查看顶级服务。以下示例显示了如何执行此操作：

$ curl http：// localhost：8080
{
  “ _links”：{
    “人们” ： {
      “ href”：“ http：// localhost：8080 / people {？page，size，sort}”，
      “ templated”：正确
    }
  }
}

前面的示例提供了该服务器必须提供的功能的第一印象。有一个people链接位于http://localhost:8080/people。它有一些选项，如?page，?size和?sort。

Spring Data REST使用HAL格式进行JSON输出。它非常灵活，并提供了一种便捷的方式来提供与所提供数据相邻的链接。

以下示例显示了如何查看人员记录（目前没有）：

$ curl http：// localhost：8080 / people
{
  “ _embedded”：{
    “人们” ： []
  }，
  “ _links”：{
    “自己” ： {
      “ href”：“ http：// localhost：8080 / people {？page，size，sort}”，
      “ templated”：正确
    }，
    “搜索” ： {
      “ href”：“ http：// localhost：8080 / people / search”
    }
  }，
  “页” ： {
    “大小”：20，
    “ totalElements”：0，
    “ totalPages”：0，
    “数字”：0
  }
}

当前没有元素，因此没有页面。是时候创建一个新的了Person！以下清单显示了如何执行此操作：

$ curl -i -H“ Content-Type：application / json” -d'{“ firstName”：“ Frodo”，“ lastName”：“ Baggins”}'http：// localhost：8080 / people
HTTP / 1.1 201已创建
伺服器：Apache-Coyote / 1.1
位置：http：// localhost：8080 / people / 1
内容长度：0
日期：2014年2月26日，星期三20:26:55 GMT

  • -i：确保您可以看到包含标题的响应消息。显示新创建的URI Person。

  • -H "Content-Type:application/json"：设置内容类型，以便应用程序知道有效负载包含JSON对象。

  • -d '{"firstName": "Frodo", "lastName": "Baggins"}'：正在发送数据。

  • 如果您使用的是Windows，则上面的命令将在WSL上运行。如果无法安装WSL，则可能需要用双引号替换单引号，并转义现有的双引号，即-d "{\"firstName\": \"Frodo\", \"lastName\": \"Baggins\"}"。

请注意，对POST操作的响应如何包含Location标头。它包含新创建的资源的URI。Spring Data REST还具有两个方法（RepositoryRestConfiguration.setReturnBodyOnCreate(…)和setReturnBodyOnUpdate(…)），您可以用来配置框架以立即返回刚刚创建的资源的表示形式。RepositoryRestConfiguration.setReturnBodyForPutAndPost(…)是一种启用创建和更新操作的表示形式响应的快捷方法。

您可以查询所有人，如以下示例所示：

$ curl http：// localhost：8080 / people
{
  “ _links”：{
    “自己” ： {
      “ href”：“ http：// localhost：8080 / people {？page，size，sort}”，
      “ templated”：正确
    }，
    “搜索” ： {
      “ href”：“ http：// localhost：8080 / people / search”
    }
  }，
  “ _embedded”：{
    “人们” ： [ {
      “ firstName”：“ Frodo”，
      “ lastName”：“ Baggins”，
      “ _links”：{
        “自己” ： {
          “ href”：“ http：// localhost：8080 / people / 1”
        }
      }
    }]
  }，
  “页” ： {
    “大小”：20，
    “ totalElements”：1，
    “ totalPages”：1
    “数字”：0
  }
}

该people对象包含一个包含的列表Frodo。请注意，它如何包含self链接。Spring Data REST还使用Evo Inflector来对实体名称进行复数以进行分组。

您可以直接查询单个记录，如下所示：

$ curl http：// localhost：8080 / people / 1
{
  “ firstName”：“ Frodo”，
  “ lastName”：“ Baggins”，
  “ _links”：{
    “自己” ： {
      “ href”：“ http：// localhost：8080 / people / 1”
    }
  }
}
这似乎纯粹是基于网络的。但是，在后台有一个H2关系数据库。在生产中，您可能会使用真实的数据库，例如PostgreSQL。
在本指南中，只有一个域对象。在域对象相互关联的更复杂的系统中，Spring Data REST呈现了更多链接，以帮助导航到连接的记录。

您可以找到所有自定义查询，如以下示例所示：

$ curl http：// localhost：8080 / people / search
{
  “ _links”：{
    “ findByLastName”：{
      “ href”：“ http：// localhost：8080 / people / search / findByLastName {？name}”，
      “ templated”：正确
    }
  }
}

您可以看到查询的URL，包括HTTP查询参数name。请注意，这与@Param("name")接口中嵌入的注释匹配。

以下示例显示了如何使用findByLastName查询：

$ curl http：// localhost：8080 / people / search / findByLastName？name = Baggins
{
  “ _embedded”：{
    “人”：[{
      “ firstName”：“ Frodo”，
      “ lastName”：“ Baggins”，
      “ _links”：{
        “自己” ： {
          “ href”：“ http：// localhost：8080 / people / 1”
        }
      }
    }]
  }
}

因为您将其定义为List<Person>在代码中返回，所以它将返回所有结果。如果已将其定义为仅返回Person，则它将选择Person要返回的对象之一。由于这可能是不可预测的，因此对于可能返回多个条目的查询，您可能不想这样做。

您还可以发出PUT，PATCH和DELETEREST调用来分别替换，更新或删除现有记录。下面的示例使用一个PUT调用：

$ curl -X PUT -H“ Content-Type：application / json” -d'{“ firstName”：“ Bilbo”，“ lastName”：“ Baggins”}'http：// localhost：8080 / people / 1
$ curl http：// localhost：8080 / people / 1
{
  “ firstName”：“ Bilbo”，
  “ lastName”：“ Baggins”，
  “ _links”：{
    “自己” ： {
      “ href”：“ http：// localhost：8080 / people / 1”
    }
  }
}

下面的示例使用一个PATCH调用：

$ curl -X PATCH -H“ Content-Type：application / json” -d'{“ firstName”：“ Bilbo Jr.”}'http：// localhost：8080 / people / 1
$ curl http：// localhost：8080 / people / 1
{
  “ firstName”：“ Bilbo Jr.”，
  “ lastName”：“ Baggins”，
  “ _links”：{
    “自己” ： {
      “ href”：“ http：// localhost：8080 / people / 1”
    }
  }
}
PUT替换整个记录。未提供的字段将替换为null。您可以PATCH用来更新项目的子集。

您还可以删除记录，如以下示例所示：

$ curl -X DELETE http：// localhost：8080 / people / 1
$ curl http：// localhost：8080 / people
{
  “ _links”：{
    “自己” ： {
      “ href”：“ http：// localhost：8080 / people {？page，size，sort}”，
      “ templated”：正确
    }，
    “搜索” ： {
      “ href”：“ http：// localhost：8080 / people / search”
    }
  }，
  “页” ： {
    “大小”：20，
    “ totalElements”：0，
    “ totalPages”：0，
    “数字”：0
  }
}

此超媒体驱动的界面的一个方便方面是，您可以使用curl（或您喜欢的任何REST客户端）发现所有RESTful端点。您无需与客户交换正式的合同或接口文档。

概括

恭喜你！您已经开发了具有基于超媒体的RESTful前端和基于JPA的后端的应用程序。

也可以看看

以下指南也可能会有所帮助：

是否要编写新指南或为现有指南做出贡献？查看我们的贡献准则。

所有指南均以代码的ASLv2许可证和写作的Attribution，NoDerivatives创用CC许可证发布。