入门·使用REST访问Neo4j数据

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

你会建立什么

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

Spring Data REST还支持将Spring Data JPA ， Spring Data Gemfire和Spring Data MongoDB作为后端数据存储，但是本指南涉及Neo4j。

你需要什么

约15分钟
最喜欢的文本编辑器或IDE
JDK 1.8或更高版本
Gradle 4+或Maven 3.2+
您还可以将代码直接导入到IDE中：
- Spring Tool Suite (STS)
- IntelliJ IDEA

如何完成本指南

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

要从头开始 ，请继续进行[scratch] 。

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

下载并解压缩本指南的源存储库，或使用Git对其进行克隆：git clone https://github.com/spring-guides/gs-accessing-neo4j-data-rest.git
光盘进入gs-accessing-neo4j-data-rest/initial
跳至访问Neo4j的权限。

完成后 ，您可以根据中的代码检查结果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。在本示例的其余部分中，将使用这些值。

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

<?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.1.7.RELEASE</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.example</groupId>
	<artifactId>accessing-neo4j-data-rest</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>accessing-neo4j-data-rest</name>
	<description>Demo project for Spring Boot</description>

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

	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-data-neo4j</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-data-rest</artifactId>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
	</dependencies>

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

</project>

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

plugins {
	id 'org.springframework.boot' version '2.1.7.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'
}

访问Neo4j的权限

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

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

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

不要在源存储库中存储真实凭证。而是在您的运行时中通过使用Spring Boot的属性overrides配置它们。

创建一个域对象

您需要创建一个新的域对象来呈现一个人，如以下示例（在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对象。它通过扩展PagingAndSortingRepositry Spring Data Commons中定义的接口。

在运行时，Spring Data REST自动创建此接口的实现。然后使用@RepositoryRestResource注释以指导Spring MVC在以下位置创建RESTful端点/people 。

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

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

查找应用程序类别

当您使用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。例如，如果spring-webmvc在类路径上，此注释将应用程序标记为Web应用程序并激活关键行为，例如设置DispatcherServlet 。
@ComponentScan ：告诉Spring在其中寻找其他组件，配置和服务com/example包，让它找到控制器。

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

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

构建可执行的JAR

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

如果您使用Gradle，则可以使用./gradlew bootRun 。或者，您可以通过使用以下命令构建JAR文件： ./gradlew build然后运行JAR文件，如下所示：

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

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

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

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

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

测试应用

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

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

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

在这里，您可以初步了解该服务器所提供的功能。有一个people链接位于http：// localhost：8080 / 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确保您可以看到包含标题的响应消息。新创建的URI Person显示
-X POST发出信号POST用于创建新条目
-H "Content-Type:application/json"设置内容类型，以便应用程序知道有效负载包含JSON对象
-d '{ "firstName" : "Frodo", "lastName" : "Baggins" }'是正在发送的数据

注意前面的POST操作包括Location标头。它包含新创建资源的URI。Spring Data REST也有两种方法（ RepositoryRestConfiguration.setReturnBodyOnCreate(…)和setReturnBodyOnCreate(…) ），您可以将其配置为立即返回刚刚创建的资源的表示形式的框架。

通过运行以下命令（与输出一起显示），您可以从中查询所有人员：

$ 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/0
{
  "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的后端的应用程序。

也可以看看

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

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

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

使用REST访问Neo4j数据