SpringBoot 2 REST 访问 Neo4j 数据

开篇词

该指南将引导你创建通过基于超媒体的 RESTful 前端访问图数据。
 

你将创建的应用

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

你将需要的工具

• 大概 15 分钟左右；
• 你最喜欢的文本编辑器或集成开发环境（IDE）
• JDK 1.8 或更高版本；
• Gradle 4+ 或 Maven 3.2+
• 你还可以将代码直接导入到 IDE 中：
  • Spring Too Suite (STS)
  • IntelliJ IDEA
     

如何完成这个指南

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

• 要从头开始，移步至搭建并启动一个 Neo4j 服务器；
• 要跳过基础，执行以下操作：
  • 下载并解压缩该指南将用到的源代码，或借助 Git 来对其进行克隆操作：git clone https://github.com/spring-guides/gs-accessing-neo4j-data-rest.git
  • 切换至 gs-accessing-neo4j-data-rest/initial 目录；
  • 跳转至该指南的访问 Neo 4j 的权限。

待一切就绪后，可以检查一下 gs-accessing-neo4j-data-rest/complete 目录中的代码。
 

搭建并启动一个 Neo4j 服务器

在构建该应用之前，我们需要搭建一个 Neo4j 服务器。

Neo4j 有一个开源服务器，我们可以免费安装。

在安装了 Homebrew 的Mac 上，可以在终端窗口中键入以下内容：

brew install neo4j

有关其他选项，请参见 https://neo4j.com/download/community-edition/

安装 Neo4j 后，可以通过运行以下命令以默认配置启动它：

neo4j start

我们应该看到类似于以下内容的消息：

Starting Neo4j. Started neo4j (pid 96416). By default, it is available at http://localhost:7474/ There may be a short delay until the server is ready. See /usr/local/Cellar/neo4j/3.0.6/libexec/logs/neo4j.log for current status.

默认情况下，Neo4j 的用户名和密码为 neo4j 和 neo4j。但是，它要求更改为新的账户密码。为此，请运行以下命令：

curl -v -u neo4j:neo4j -X POST localhost:7474/user/neo4j/password -H "Content-type:application/json" -d "{\"password\":\"secret\"}"

这会将密码从 neo4j 更改为 secret（不要在生产环境中这么做！）。完成后，我们就可以准备运行该指南。
 

从 Spring Initializr 开始

对于所有的 Spring 应用来说，你应该从 Spring Initializr 开始。Initializr 提供了一种快速的方法来提取应用程序所需的依赖，并为你完成许多设置。该例子需要 Rest Repositories 和 Spring Data Neo4j 依赖。下图显示了此示例项目的 Initializr 设置：

上图显示了选择 Maven 作为构建工具的 Initializr。你也可以使用 Gradle。它还将 com.example 和 accessing-neo4j-data-rest 的值分别显示为 Group 和 Artifact。在本示例的其余部分，将用到这些值。

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

<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.0modelVersion>
	<parent>
		<groupId>org.springframework.bootgroupId>
		<artifactId>spring-boot-starter-parentartifactId>
		<version>2.2.2.RELEASEversion>
		<relativePath/> 
	parent>
	<groupId>com.examplegroupId>
	<artifactId>accessing-neo4j-data-restartifactId>
	<version>0.0.1-SNAPSHOTversion>
	<name>accessing-neo4j-data-restname>
	<description>Demo project for Spring Bootdescription>

	<properties>
		<java.version>1.8java.version>
	properties>

	<dependencies>
		<dependency>
			<groupId>org.springframework.bootgroupId>
			<artifactId>spring-boot-starter-data-neo4jartifactId>
		dependency>
		<dependency>
			<groupId>org.springframework.bootgroupId>
			<artifactId>spring-boot-starter-data-restartifactId>
		dependency>

		<dependency>
			<groupId>org.springframework.bootgroupId>
			<artifactId>spring-boot-starter-testartifactId>
			<scope>testscope>
			<exclusions>
				<exclusion>
					<groupId>org.junit.vintagegroupId>
					<artifactId>junit-vintage-engineartifactId>
				exclusion>
			exclusions>
		dependency>
	dependencies>

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

project>

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

plugins {
	id 'org.springframework.boot' version '2.2.2.RELEASE'
	id 'io.spring.dependency-management' version '1.0.8.RELEASE'
	id 'java'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '1.8'

repositories {
	mavenCentral()
}

dependencies {
	implementation 'org.springframework.boot:spring-boot-starter-data-neo4j'
	implementation 'org.springframework.boot:spring-boot-starter-data-rest'
	testImplementation('org.springframework.boot:spring-boot-starter-test') {
		exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'
	}
}

test {
	useJUnitPlatform()
}

 

访问 Neo 4j 的权限

Neo4j Community Edition 需要凭据才能访问它。我们可以通过在 src/main/resources/application.properties 中设置属性来配置凭据，如下所示：

spring.data.neo4j.username=neo4j
spring.data.neo4j.password=secret

这包括默认的用户名（neo4j）和我们先前设置的新密码（secret）。

不要在源存储库中存储真实凭证。相反，请使用 Spring Boot 的属性替代在运行中对它们进行配置。

 

创建域对象

我们需要创建一个新的域对象来展现一个人，如以下示例（在 src/main/java/com/example/accessingneo4jdatarest/Person.java 中）所示：

package com.example.accessingneo4jdatarest;


import org.neo4j.ogm.annotation.GeneratedValue;
import org.neo4j.ogm.annotation.Id;
import org.neo4j.ogm.annotation.NodeEntity;

@NodeEntity
public class Person {

  @Id @GeneratedValue 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 对象，该对象被配置为自动生成，因此我们无需手动生成。
 

创建一个 Person 存储库

接下来，我们需要创建一个简单的存储库，如以下示例所示（在 src/main/java/com/example/accessingneo4jdatarest/PersonRepository.java 中）：

package com.example.accessingneo4jdatarest;

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 对象的各种操作。它通过扩展 Spring Data Commons 中定义的 PagingAndSortingRepository 接口来获得这些操作。

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

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

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

查找应用类

当我们使用 Spring Initializr 创建项目时，它会创建一个应用类。我们可以在 src/main/java/com/example/accessingneo4jdatarest/Application.java 中找到它。请注意，Spring Initializr 连接（并适当地更改了其大小写）包名并添加其至 Application 中以创建应用名称。这种情况下，我们获得 AccessingNeo4jDataRestApplication，如下清单所示：

package com.example.accessingneo4jdatarest;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.data.neo4j.repository.config.EnableNeo4jRepositories;
import org.springframework.transaction.annotation.EnableTransactionManagement;

@EnableTransactionManagement
@EnableNeo4jRepositories
@SpringBootApplication
public class AccessingNeo4jDataRestApplication {

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

在该示例中，我们无需对该应用类做任何更改。
@SpringBootApplication 是一个便利的注解，它添加了以下所有内容：

• @Configuration：将类标记为应用上下文 Bean 定义的源；
• @EnableAutoConfiguration：告诉 Spring Boot 根据类路径配置、其他 bean 以及各种属性的配置来添加 bean。
• @ComponentScan：告知 Spring 在 com/example 包中寻找他组件、配置以及服务。

main() 方法使用 Spring Boot 的 SpringApplication.run() 方法启动应用。

@EnableNeo4jRepositories 注解激活 Spring Data Neo4j。Spring Data Neo4j 创建了 PersonRepository 的具体实现，并将其配置为使用 Cypher 查询语言与嵌入式 Neo4j 数据库对话。

构建可执行 JAR

我们可以结合 Gradle 或 Maven 来从命令行运行该应用。我们还可以构建一个包含所有必须依赖项、类以及资源的可执行 JAR 文件，然后运行该文件。在整个开发生命周期中，跨环境等等情况下，构建可执行 JAR 可以轻松地将服务作为应用进行发布、版本化以及部署。

如果使用 Gradle，则可以借助 ./gradlew bootRun 来运行应用。或通过借助 ./gradlew build 来构建 JAR 文件，然后运行 JAR 文件，如下所示：

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

由官网提供的以上这条命令的执行结果与我本地的不一样，我需要这样才能运行：java -jar build/libs/accessing-neo4j-data-rest-0.0.1-SNAPSHOT.jar。

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

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

由官网提供的以上这条命令的执行结果与我本地的不一样，我需要这样才能运行：java -jar target/accessing-neo4j-data-rest-0.0.1-SNAPSHOT.jar。

我们还可以将 JAR 应用转换成 WAR 应用。

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

测试应用

现在该应用正在运行，我们可以对其进行测试。我们可以使用任何喜欢的 REST 客户端。以下示例使用 curl。

首先，我们要查看顶级服务。以下示例（带有输出）显示了如何执行该操作：

curl http://localhost:8080

{
  "_links" : {
    "people" : {
      "href" : "http://localhost:8080/people{?page,size,sort}",
      "templated" : true
    }
  }
}

这里，我们可以初步了解该服务器所提供的功能。在 http://localhost:8080/people 上有一个 people 链接。它有一些选项，例如 ?page、?size 及 ?sort。

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

curl http://localhost:8080/people

{
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people{?page,size,sort}",
      "templated" : true
    },
    "search" : {
      "href" : "http://localhost:8080/people/search"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 0,
    "totalPages" : 0,
    "number" : 0
  }
}

当前没有任何元素，因此也没有分页内容，所以是时候创建一个新的 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/0
Content-Length: 0
Date: Wed, 26 Feb 2014 20:26:55 GMT

• -i：确保我们可以看到包括标题的响应消息。显示新创建的 Person 的 URI；
• -X POST 表示这是用于创建新条目的 POST；
• -H "Content-Type:application/json"：设置内容类型，以便应用知道有效负载包含 JSON 对象；
• -d'{"firstName: "Frodo", "lastName": "Barggins""}'：被发送的数据；

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

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

curl http://localhost:8080/people

{
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people{?page,size,sort}",
      "templated" : true
    },
    "search" : {
      "href" : "http://localhost:8080/people/search"
    }
  },
  "_embedded" : {
    "people" : [ {
      "firstName" : "Frodo",
      "lastName" : "Baggins",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/people/0"
        }
      }
    } ]
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

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

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

curl http://localhost:8080/people/1

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

这似乎完全是基于 Web 的，但是后台有一个嵌入式 Neo4j 图形数据库。在生产中，我们可能会连接到独立的 Neo4j 服务器。

在该指南中，只有一个域对象。在域对象相互关联的更复杂的系统中，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" : {
    "people" : [ {
      "firstName" : "Frodo",
      "lastName" : "Baggins",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/people/0"
        },
        "person" : {
          "href" : "http://localhost:8080/people/0"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people/search/findByLastName?name=Baggins"
    }
  }
}

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

我还可以发出 PUT、PATCH 和 DELETE REST 调用来分别替换、更新或删除现有记录。以下示例使用 PUT 调用：

curl -X PUT -H "Content-Type:application/json" -d '{ "firstName": "Bilbo", "lastName": "Baggins" }' http://localhost:8080/people/0

curl http://localhost:8080/people/0

{
  "firstName" : "Bilbo",
  "lastName" : "Baggins",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people/0"
    }
  }
}

下面示例使用 PATCH 调用：

curl -X PATCH -H "Content-Type:application/json" -d '{ "firstName": "Bilbo Jr." }' http://localhost:8080/people/0

curl http://localhost:8080/people/0

{
  "firstName" : "Bilbo Jr.",
  "lastName" : "Baggins",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people/0"
    }
  }
}

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

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

curl -X DELETE http://localhost:8080/people/0

curl http://localhost:8080/people

{
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people{?page,size,sort}",
      "templated" : true
    },
    "search" : {
      "href" : "http://localhost:8080/people/search"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 0,
    "totalPages" : 0,
    "number" : 0
  }
}

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

概述

恭喜你！我们已经开发了具有基于超媒体的 RESTful 前端和基于 Neo4j 后端的应用。
 

参见

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

• 使用 REST 访问 JPA 数据
• 使用 REST 访问 MongoDB 数据（尽请期待～）
• 使用 MySQL 访问数据（尽请期待～）
• 使用 REST 访问 GemFire 数据（尽请期待～）
• 消费 RESTful Web 服务
• 使用 AngularJS 消费 RESTful Web 服务
• 使用 jQuery 消费 RESTful Web 服务
• 使用 rest.js 消费 RESTful Web 服务
• 保护 Web 应用程序
• 使用 Spring 构建 REST 服务
• 使用 Spring Boot 构建应用程序
• 使用 Restdocs 创建 API 文档（尽请期待～）
• 为 RESTful Web 服务启用跨源请求（尽请期待～）
• 构建超媒体驱动的 RESTful Web 服务

想看指南的其他内容？请访问该指南的所属专栏：《Spring 官方指南》