入门 | 使用 REST 访问 Pivotal GemFire 中的数据

您将构建什么

您将构建一个Spring Web 应用程序，允许您使用 Spring Data REST 创建和检索存储在Apache Geode 内存数据网格 (IMDG) 中的Person 对象。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
Java 1.8 或更高版本
Gradle 7.5+ 或Maven 3.5+
您也可以直接将代码导入您的 IDE

如何完成本指南

与大多数 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 提供了一种快速方法来引入应用程序所需的所有依赖项，并为您完成许多设置工作。此示例需要“用于 Apache Geode 的 Spring”依赖项。

以下清单显示了使用 Maven 时的示例pom.xml文件

<?xml version="1.0" encoding="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>

	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.7.0</version>
	</parent>

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

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

	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-data-rest</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.data</groupId>
			<artifactId>spring-data-geode</artifactId>
		</dependency>
		<dependency>
			<groupId>org.projectlombok</groupId>
			<artifactId>lombok</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.shell</groupId>
			<artifactId>spring-shell</artifactId>
			<version>${spring-shell.version}</version>
			<scope>runtime</scope>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
			<exclusions>
				<exclusion>
					<groupId>org.junit.vintage</groupId>
					<artifactId>junit-vintage-engine</artifactId>
				</exclusion>
			</exclusions>
		</dependency>
	</dependencies>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>

</project>

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

plugins {
    id 'org.springframework.boot' version '2.7.0'
    id 'io.spring.dependency-management' version '1.0.11.RELEASE'
    id 'io.freefair.lombok' version '6.3.0'
    id 'java'
}

apply plugin: 'eclipse'
apply plugin: 'idea'

group = "org.springframework"
version = "0.1.0"
sourceCompatibility = 1.8
targetCompatibility = 1.8

repositories {
    mavenCentral()
}

dependencies {

    implementation "org.springframework.boot:spring-boot-starter-data-rest"
    implementation "org.springframework.data:spring-data-geode"
    implementation "org.projectlombok:lombok"

    runtimeOnly "org.springframework.shell:spring-shell:1.2.0.RELEASE"

    testImplementation "org.springframework.boot:spring-boot-starter-test"

}

test {
    useJUnitPlatform()
}

bootJar {
    baseName = 'gs-accessing-gemfire-data-rest'
    version =  '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对象创建时递增。

创建 Person 仓库

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

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来获得这些操作。

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

仓库不需要@RepositoryRestResource即可导出。它仅用于更改导出详细信息，例如使用/people而不是默认值/persons。

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

使应用程序可执行

虽然可以将此服务打包为传统的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注释激活了用于 Apache Geode 的 Spring Data 的仓库。用于 Apache Geode 的 Spring Data将创建PersonRepository接口的具体实现，并将其配置为与 Apache Geode 的嵌入式实例进行通信。

构建可执行 JAR

您可以使用 Gradle 或 Maven 从命令行运行应用程序。您还可以构建一个包含所有必要依赖项、类和资源的单个可执行 JAR 文件并运行它。构建可执行 jar 使得在整个开发生命周期中、跨不同环境等，轻松地交付、版本化和部署服务作为应用程序。

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

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

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

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

此处描述的步骤创建了一个可运行的 JAR。您也可以构建一个经典的 WAR 文件。

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

测试应用程序

应用程序运行后，您可以对其进行测试。您可以使用任何您想要的 REST 客户端。以下示例使用 *nix 工具curl。

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

$ curl https://127.0.0.1:8080
{
  "_links" : {
    "people" : {
      "href" : "https://127.0.0.1:8080/people"
    }
  }
}

在这里，您可以首次了解此服务器的功能。位于https://127.0.0.1:8080/people 的people链接。用于 Apache Geode 的 Spring Data不支持像其他 Spring Data REST 指南那样的分页，因此没有额外的导航链接。

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

$ curl https://127.0.0.1:8080/people
{
  "_links" : {
    "search" : {
      "href" : "https://127.0.0.1:8080/people/search"
    }
  }
}

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

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

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

请注意，之前的POST操作包含一个Location标头。这包含新创建资源的 URI。Spring Data REST 在RepositoryRestConfiguration.setReturnBodyOnCreate(…)和setReturnBodyOnCreate(…)上还有两种方法，您可以使用它们来配置框架以立即返回刚刚创建的资源的表示。

您可以从中查询所有人

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

people集合资源包含 Frodo 的列表。请注意它包含一个self链接。Spring Data REST 还使用Evo Inflector 来将实体名称复数化以进行分组。

您可以直接查询单个记录

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

这看起来像是纯粹的基于 Web 的，但在幕后，它正在与嵌入式 Apache Geode 数据库进行通信。

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

查找所有自定义查询

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

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

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

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

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

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

$ curl -X PUT -H "Content-Type:application/json" -d '{ "firstName": "Bilbo", "lastName": "Baggins" }' https://127.0.0.1:8080/people/1
$ curl https://127.0.0.1:8080/people/1
{
  "firstName" : "Bilbo",
  "lastName" : "Baggins",
  "_links" : {
    "self" : {
      "href" : "https://127.0.0.1:8080/people/1"
    }
  }
}

$ curl -X PATCH -H "Content-Type:application/json" -d '{ "firstName": "Bilbo Jr." }' https://127.0.0.1:8080/people/1
$ curl https://127.0.0.1:8080/people/1
{
  "firstName" : "Bilbo Jr.",
  "lastName" : "Baggins",
  "_links" : {
    "self" : {
      "href" : "https://127.0.0.1:8080/people/1"
    }
  }
}

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

您可以删除记录

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

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

总结

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

另请参阅

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

想编写新的指南或贡献现有指南？请查看我们的贡献指南。

所有指南的代码均采用 ASLv2 许可证发布，而文本内容则采用署名-非衍生作品创作共用许可证。

使用 REST 访问 Pivotal GemFire 中的数据

您将构建什么

您需要什么

如何完成本指南

从 Spring Initializr 开始

创建域对象

创建 Person 仓库

使应用程序可执行

构建可执行 JAR

测试应用程序

总结

另请参阅

获取代码