使用REST访问Pivotal GemFire中的数据

本指南将引导您完成创建应用程序的过程，该应用程序通过基于超媒体的 REST-ful前端访问存储在Apache Geode中的数据。

你会建立什么

您将构建一个Spring Web应用程序，使用Spring Data REST创建和检索Person存储在Apache Geode内存数据网格（IMDG）中的对象。Spring Data REST具备Spring HATEOAS和适用于Apache Geode的Spring Data的功能，并将它们自动结合在一起。

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

有关Apache Geode概念的更多常识以及如何从Apache Geode访问数据，请通读指南“使用Apache Geode访问数据”。

你需要什么

约15分钟
最喜欢的文本编辑器或IDE
JDK 1.8或更高版本
Gradle 4+或Maven 3.2+
您还可以将代码直接导入到IDE中：
- 弹簧工具套件（STS）
- IntelliJ IDEA

如何完成本指南

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

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

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

下载并解压缩本指南的源存储库，或使用Git对其进行克隆：git clone https://github.com/spring-guides/gs-accessing-gemfire-data-rest.git
光盘进入 gs-accessing-gemfire-data-rest/initial
继续创建域对象。

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

从Spring Initializr开始

对于所有Spring应用程序，您应该从Spring Initializr开始。Spring Initializr提供了一种快速的方法来提取应用程序所需的所有依赖关系，并为您完成了许多设置。本示例需要“ Spring for Apache Geode ”依赖项。

以下清单显示了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.1 </ version>
	</ parent>

	<groupId> org.springframework </ groupId>
	<artifactId> gs-accessing-gemfire-data-rest </ artifactId>
	<version> 0.1.0 </ version>

	<属性>
		<spring-shell.version> 1.2.0.RELEASE </spring-shell.version>
	</ properties>

	<依赖项>
		<依赖性>
			<groupId> org.springframework.boot </ groupId>
			<artifactId> spring-boot-starter-data-rest </ artifactId>
		</ dependency>
		<依赖性>
			<groupId> org.springframework.boot </ groupId>
			<artifactId> spring-boot-starter-web </ artifactId>
		</ dependency>
		<依赖性>
			<groupId> org.springframework.data </ groupId>
			<artifactId> spring-data-geode </ artifactId>
		</ dependency>
		<依赖性>
			<groupId> org.projectlombok </ groupId>
			<artifactId>龙目岛</ artifactId>
		</ dependency>
		<依赖性>
			<groupId> org.springframework.shell </ groupId>
			<artifactId>弹簧壳</ artifactId>
			<version> $ {spring-shell.version} </ version>
			<scope>运行时</ scope>
		</ dependency>
		<依赖性>
			<groupId> org.springframework.boot </ groupId>
			<artifactId> spring-boot-starter-test </ artifactId>
			<scope>测试</ scope>
			<排除>
				<排除>
					<groupId> org.junit.vintage </ groupId>
					<artifactId> junit-vintage-engine </ artifactId>
				</ exclusion>
			</ exclusions>
		</ dependency>
	</ dependencies>

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

</ project>

以下清单显示了build.gradle使用Gradle时的示例文件：

插件{
    id'org.springframework.boot'版本'2.4.1'
    id'io.spring.dependency-management'版本'1.0.8.RELEASE'
    id“ io.freefair.lombok”版本“ 5.3.0”
    id'java'
}

套用外挂程式：'eclipse'
套用外挂程式：'idea'

组=“ org.springframework”
版本=“ 0.1.0”
sourceCompatibility = 1.8
targetCompatibility = 1.8

储存库{
    mavenCentral（）
}

依赖项{

    实现“ org.springframework.boot：spring-boot-starter-data-rest”
    实现“ org.springframework.data:spring-data-geode”
    实现“ org.projectlombok：lombok”

    runtimeonly只有“ org.springframework.shell:spring-shell:1.2.0.RELEASE”

    testImplementation“ org.springframework.boot：spring-boot-starter-test”

}

测试 {
    useJUnitPlatform（）
}

bootJar {
    baseName ='gs-accessing-gemfire-data-rest'
    版本='0.1.0'
}

创建一个域对象

创建一个新的域对象来呈现一个人。

src/main/java/hello/Person.java

package hello;

import java.util.concurrent.atomic.AtomicLong;

import org.springframework.data.annotation.Id;
import org.springframework.data.annotation.PersistenceConstructor;
import org.springframework.data.gemfire.mapping.annotation.Region;

import lombok.Data;

@Data
@Region("People")
public class Person {

  private static AtomicLong COUNTER = new AtomicLong(0L);

  @Id
  private Long id;

  private String firstName;
  private String lastName;

  @PersistenceConstructor
  public Person() {
    this.id = COUNTER.incrementAndGet();
  }
}

的Person名字和姓氏。Apache Geode域对象需要一个ID，因此AtomicLong每次Person创建对象时都会使用一个ID来递增。

创建个人资料库

接下来，您需要创建一个简单的存储库来持久化/访问Person存储在Apache Geode中的对象。

src/main/java/hello/PersonRepository.java

package hello;

import java.util.List;

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

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

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

}

该存储库是一个界面，使您可以执行涉及Person对象的各种数据访问操作（例如，基本的CRUD和简单查询）。它通过扩展获得这些操作CrudRepository。

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

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

在这里，您还定义了一个自定义查询来检索Person基于的对象列表lastName。您将在本指南中进一步了解如何调用它。

使应用程序可执行

尽管可以将该服务打包为传统的WAR文件以部署到外部应用程序服务器，但是下面演示的更简单的方法创建了一个独立的应用程序。您可以将所有内容打包到一个可执行的JAR文件中，该文件由一个好的旧Javamain()方法驱动。在此过程中，您将使用Spring的支持将Tomcat servlet容器作为HTTP运行时嵌入，而不是部署到外部servlet容器。

src/main/java/hello/Application.java

package hello;

import org.apache.geode.cache.client.ClientRegionShortcut;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.data.gemfire.config.annotation.ClientCacheApplication;
import org.springframework.data.gemfire.config.annotation.EnableEntityDefinedRegions;
import org.springframework.data.gemfire.repository.config.EnableGemfireRepositories;

@SpringBootApplication
@ClientCacheApplication(name = "AccessingGemFireDataRestApplication")
@EnableEntityDefinedRegions(
  basePackageClasses = Person.class,
  clientRegionShortcut = ClientRegionShortcut.LOCAL
)
@EnableGemfireRepositories
@SuppressWarnings("unused")
public class Application {

  public static void main(String[] args) {
    SpringApplication.run(Application.class, args);
  }
}

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

@Configuration：将类标记为应用程序上下文的Bean定义的源。
@EnableAutoConfiguration：告诉Spring Boot根据类路径设置，其他bean和各种属性设置开始添加bean。例如，如果spring-webmvc在类路径上，则此注释将应用程序标记为Web应用程序并激活关键行为，例如设置DispatcherServlet。
@ComponentScan：告诉Spring在包中寻找其他组件，配置和服务hello，让它找到控制器。

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

该@EnableGemfireRepositories注释激活Spring数据为Apache的Geode 库。用于Apache Geode的Spring Data将创建该PersonRepository接口的具体实现，并将其配置为与Apache Geode的嵌入式实例通信。

建立可执行的JAR

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

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

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

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

java -jar target / gs-accessing-gemfire-data-rest-0.1.0.jar

此处描述的步骤将创建可运行的JAR。您还可以构建经典的WAR文件。

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

测试应用程序

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

首先，您要查看顶级服务。

$ curl http://localhost:8080
{
  "_links" : {
    "people" : {
      "href" : "http://localhost:8080/people"
    }
  }
}

在这里，您可以初步了解该服务器所提供的功能。在http：// localhost：8080 / people上有一个人员链接。Apache Geode的Spring Data不像其他Spring Data REST指南那样支持分页，因此没有额外的导航链接。

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

$ curl http://localhost:8080/people
{
  "_links" : {
    "search" : {
      "href" : "http://localhost:8080/people/search"
    }
  }
}

是时候创建一个新的了Person！

$ curl -i -X POST -H "Content-Type:application/json" -d '{  "firstName" : "Frodo",  "lastName" : "Baggins" }' http://localhost:8080/people
HTTP/1.1 201 Created
Server: Apache-Coyote/1.1
Location: http://localhost:8080/people/1
Content-Length: 0
Date: Wed, 05 Mar 2014 20:16:11 GMT

-i确保您可以看到包含标题的响应消息。新创建的URIPerson被示出
-X POST发出POSTHTTP请求以创建新条目
-H "Content-Type:application/json" 设置内容类型，以便应用程序知道有效负载包含JSON对象
-d '{ "firstName" : "Frodo", "lastName" : "Baggins" }' 是正在发送的数据

请注意，上一个POST操作如何包含Location标头。它包含新创建的资源的URI。Spring数据REST也有两种方法RepositoryRestConfiguration.setReturnBodyOnCreate(…)，并setReturnBodyOnCreate(…)您可以使用它来配置框架立即返回刚刚创建的资源的表示。

由此您可以查询所有人：

$ curl http://localhost:8080/people
{
  "_links" : {
    "search" : {
      "href" : "http://localhost:8080/people/search"
    }
  },
  "_embedded" : {
    "persons" : [ {
      "firstName" : "Frodo",
      "lastName" : "Baggins",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/people/1"
        }
      }
    } ]
  }
}

该人收集资源包含了弗罗多的列表。注意它如何包含一个自我链接。Spring Data REST还使用Evo Inflector来对实体名称进行复数以进行分组。

您可以直接查询单个记录：

$ curl http://localhost:8080/people/1
{
  "firstName" : "Frodo",
  "lastName" : "Baggins",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people/1"
    }
  }
}

这似乎纯粹是基于Web的，但是在后台，它正在与嵌入式Apache Geode数据库进行通信。

在本指南中，只有一个域对象。在域对象相互关联的更复杂的系统中，Spring Data REST将提供附加链接以帮助导航到连接的记录。

查找所有自定义查询：

$ curl http://localhost:8080/people/search
{
  "_links" : {
    "findByLastName" : {
      "href" : "http://localhost:8080/people/search/findByLastName{?name}",
      "templated" : true
    }
  }
}

您可以看到查询的URL，其中包括HTTP查询参数name。如果您会注意到，它与@Param("name")界面中嵌入的注释匹配。

要使用findByLastName查询，请执行以下操作：

$ curl http://localhost:8080/people/search/findByLastName?name=Baggins
{
  "_embedded" : {
    "persons" : [ {
      "firstName" : "Frodo",
      "lastName" : "Baggins",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/people/1"
        }
      }
    } ]
  }
}

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

您还可以发出PUT，PATCH和DELETEREST调用来替换，更新或删除现有记录。

$ 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" : {
    "self" : {
      "href" : "http://localhost:8080/people/1"
    }
  }
}

$ 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" : {
    "self" : {
      "href" : "http://localhost:8080/people/1"
    }
  }
}

PUT替换整个记录。未提供的字段将替换为null。PATCH可用于更新项的子集。

您可以删除记录：

$ curl -X DELETE http://localhost:8080/people/1
$ curl http://localhost:8080/people
{
  "_links" : {
    "search" : {
      "href" : "http://localhost:8080/people/search"
    }
  }
}

此超媒体驱动的界面的一个非常方便的方面是如何使用curl（或使用的任何REST客户端）发现所有REST风格的终结点。无需与客户交换正式的合同或接口文档。

概括

恭喜你！您刚刚使用基于超媒体的 RESTful前端和基于Apache Geode的后端开发了一个应用程序。

也可以看看

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

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

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