入门 | 使用 REST 访问 Neo4j 数据

您将构建什么

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

Spring Data REST 还支持 Spring Data JPA、Spring Data Gemfire 和 Spring Data MongoDB 作为后端数据存储，但本指南将重点介绍 Neo4j。

您需要什么

大约 15 分钟
您喜欢的文本编辑器或 IDE
Java 17 或更高版本
Gradle 7.5+ 或 Maven 3.5+
您也可以将代码直接导入到您的 IDE 中

如何完成本指南

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

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

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

下载并解压缩本指南的源代码存储库，或使用 Git 克隆它：git clone https://github.com/spring-guides/{project_id}.git
切换到 {project_id}/initial 目录
跳至访问 Neo4j 的权限。

完成后，您可以将您的结果与 {project_id}/complete 中的代码进行对比。

启动 Neo4j 服务器

在构建此应用程序之前，您需要设置一个 Neo4j 服务器。

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

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

$ brew install neo4j

有关其他选项，请参阅 https://neo4j.ac.cn/download/community-edition/

安装 Neo4j 后，您可以使用其默认设置启动它，方法是运行以下命令

$ neo4j start

您应该会看到类似于以下内容的消息

Starting Neo4j.
Started neo4j (pid 96416). By default, it is available at https://127.0.0.1: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。但是，它要求更改新帐户的密码。为此，请运行以下命令

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

这将密码从 neo4j 更改为 secret（在生产环境中不要这样做！）。完成此操作后，您应该就可以运行本指南了。

从 Spring Initializr 开始

您可以使用此预初始化项目并单击“生成”以下载 ZIP 文件。此项目已配置为适合本教程中的示例。

要手动初始化项目

导航到 https://start.spring.io。此服务会引入应用程序所需的所有依赖项，并为您完成大部分设置工作。
选择 Gradle 或 Maven 以及您要使用的语言。本指南假设您选择了 Java。
单击“依赖项”，然后选择“Rest 存储库”和“Spring Data Neo4j”。
单击“生成”。
下载生成的 ZIP 文件，该文件是根据您的选择配置的 Web 应用程序的存档。

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

您也可以从 Github 分叉项目并在您的 IDE 或其他编辑器中打开它。

访问 Neo4j 的权限

Neo4j 社区版需要凭据才能访问它。您可以通过在 src/main/resources/application.properties 中设置属性来配置凭据，如下所示

spring.neo4j.uri=bolt://127.0.0.1:7687
spring.neo4j.authentication.username=neo4j
spring.neo4j.authentication.password=secret

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

不要将真实凭据存储在您的源代码存储库中。相反，请使用 Spring Boot 的属性覆盖在运行时配置它们。

创建域对象

您需要创建一个新的域对象来表示人员，如下面的示例（在 src/main/java/com/example/accessingneo4jdatarest/Person.java 中）所示

package com.example.accessingneo4jdatarest;

import org.springframework.data.neo4j.core.schema.Id;
import org.springframework.data.neo4j.core.schema.Node;
import org.springframework.data.neo4j.core.schema.GeneratedValue;

@Node
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.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 PagingAndSortingRepository<Person, Long>, CrudRepository<Person, Long> {

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

}

此存储库是一个接口，允许您执行各种涉及 Person 对象的操作。它通过扩展 Spring Data Commons 中定义的 PagingAndSortingRepositry 接口来获得这些操作。

在运行时，Spring Data REST 会自动创建此接口的实现。然后，它使用 @RepositoryRestResource 注解指示 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。例如，如果 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 运行应用程序。或者，您可以使用 ./gradlew build 构建 JAR 文件，然后运行 JAR 文件，如下所示

java -jar build/libs/{project_id}-0.1.0.jar

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

java -jar target/{project_id}-0.1.0.jar

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

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

测试应用程序

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

首先，您需要查看顶级服务。以下示例（及其输出）展示了如何执行此操作

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

在这里，您第一次了解了此服务器提供的功能。在 https://127.0.0.1:8080/people 处有一个 people 链接。它有一些选项，例如 ?page、?size 和 ?sort。

Spring Data REST 使用 HAL 格式进行 JSON 输出。它灵活且提供了一种方便的方式来在服务的数据旁边提供链接。

$ curl https://127.0.0.1:8080/people
{
  "_links" : {
    "self" : {
      "href" : "https://127.0.0.1:8080/people{?page,size,sort}",
      "templated" : true
    },
    "search" : {
      "href" : "https://127.0.0.1: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" }' 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/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" : "Baggins" }' 是发送的数据。

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

通过此，您可以运行以下命令查询所有人员（显示其输出）

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

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

您可以运行以下命令（显示其输出）直接查询单个记录。

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

这看起来可能纯粹是基于 Web 的，但在幕后，有一个嵌入的 Neo4j 图数据库。在生产环境中，您可能会连接到独立的 Neo4j 服务器。

在本指南中，只有一个域对象。在更复杂的系统中，域对象彼此相关，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
    }
  }
}

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

要使用 findByLastName 查询，请运行以下命令（显示其输出）。

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

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

您还可以发出 PUT、PATCH 和 DELETE REST 调用来替换、更新或删除现有记录。以下示例（显示其输出）显示了一个 PUT 调用。

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

以下示例（显示其输出）显示了一个 PATCH 调用。

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

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

您还可以删除记录，如下面的示例（显示其输出）所示。

$ curl -X DELETE https://127.0.0.1:8080/people/0
$ curl https://127.0.0.1:8080/people
{
  "_links" : {
    "self" : {
      "href" : "https://127.0.0.1:8080/people{?page,size,sort}",
      "templated" : true
    },
    "search" : {
      "href" : "https://127.0.0.1:8080/people/search"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 0,
    "totalPages" : 0,
    "number" : 0
  }
}

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

总结

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

另请参阅

以下指南可能也有帮助

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

所有指南均以 ASLv2 许可证发布代码，并以署名-非衍生作品创作共用许可证发布写作内容。

使用 REST 访问 Neo4j 数据