Introducing Spring Data Neo4j

Spring Data Neo4j 或简称 SDN 是下一代 Spring Data 模块，由 Neo4j, Inc. 在与 VMware’s Spring 数据团队密切合作的情况下创建和维护。它支持所有官方支持的 Neo4j 版本，包括 Neo4j AuraDB。Spring Data Neo4j 项目将上述 Spring Data 概念应用于使用 Neo4j 图形数据存储开发解决方案。

Spring Data Neo4j or in short SDN is the next-generation Spring Data module, created and maintained by Neo4j, Inc. in close collaboration with VMware’s Spring Data Team. It supports all officially supported releases of Neo4j, including Neo4j AuraDB. The Spring Data Neo4j project applies aforementioned Spring Data concepts to the development of solutions using the Neo4j graph data store.

SDN 完全依赖 Neo4j Java Driver，而不会在映射框架和驱动程序之间引入另一个“驱动程序”或“传输”层。Neo4j Java 驱动程序（有时称为 Bolt 或 Bolt 驱动程序）用作一种类似于关系数据库使用 JDBC 的协议。

SDN relies completely on the Neo4j Java Driver, without introducing another "driver" or "transport" layer between the mapping framework and the driver. The Neo4j Java Driver - sometimes dubbed Bolt or the Bolt driver - is used as a protocol much like JDBC is with relational databases.

SDN 是一个对象图映射 (OGM) 库。OGM 将图形中的节点和关系映射到域模型中的对象和引用。对象实例映射到节点，而对象引用使用关系映射或者序列化为属性（例如对 Date 的引用）。JVM 基本类型映射到节点或关系属性。OGM 抽象了数据库，并提供了一种便捷的方法，让你能够在图形中持久存储域模型，并直接查询它，而无需使用低级驱动程序。它还为开发人员提供了灵活性，允许他们在 SDN 生成的查询不足时提供自定义查询。

SDN is an Object-Graph-Mapping (OGM) library. An OGM maps nodes and relationships in the graph to objects and references in a domain model. Object instances are mapped to nodes while object references are mapped using relationships, or serialized to properties (e.g. references to a Date). JVM primitives are mapped to node or relationship properties. An OGM abstracts the database and provides a convenient way to persist your domain model in the graph and query it without having to use low level drivers directly. It also provides the flexibility to the developer to supply custom queries where the queries generated by SDN are insufficient.

SDN 是 SDN+OGM 的前代 SDN 版本 5 的 正式继承者，本文档将此版本称为 SDN+OGM。SDN 版本 5 使用了一个单独的对象映射框架，很大程度上类似于 Spring Data JPA 与 JPA 的关系。该单独的层又称 Neo4j-OGM（Neo4j 对象图映射器），现在包含在此模块本身中。Spring Data Neo4j 本身是一个对象映射器，专门用于 Spring 和 Spring Boot 应用程序以及一些受支持的 Jakarta EE 环境中。它不需要或不支持对象映射器的单独实现。

SDN is the official successor to prior SDN version 5, to which this documentation refers as SDN+OGM. SDN version 5 used a separate object mapping framework, much in the way Spring Data JPA relates to JPA. That separate layer aka Neo4j-OGM (Neo4j Object Graph Mapper) is now contained in this module itself. Spring Data Neo4j itself is an object mapper, dedicated to be used in Spring and Spring Boot applications and in some supported Jakarta EE environments. It does not require or support a separate implementation of an object mapper.

与之前的 SDN+OGM 相比，新版 SDN 中有以下突出的功能差异：

Noteworthy features that differentiate the current SDN version from prior SDN+OGM are

  • SDN is a complete OGM on its own

  • Full support for immutable entities and thus full support for Kotlin’s data classes

  • Full support for the reactive programming model in the Spring Framework itself and Spring Data

  • Neo4j client and reactive client feature, resurrecting the idea of a template over the plain driver, easing database access

我们提供 repositories 作为一种高级抽象，用于存储和查询文档以及模板和客户端以进行通用域访问或通用查询执行。它们全部与 Spring 的应用程序事务相集成。

We provide repositories as a high-level abstraction for storing and querying documents as well as templates and clients for generic domain access or generic query execution. All of them are integrated with Spring’s application transactions.

可以通过 Neo4jClient、Neo4jTemplate 或其反应性变体，直接使用 Neo4j 支持的核心功能。它们全部与 Spring 的应用程序级事务相集成。在较低级别，你可以获取 Bolt 驱动程序实例，但在这种情况下，你就必须自行管理自己的事务。

The core functionality of the Neo4j support can be used directly, through either the Neo4jClient or the Neo4jTemplate or the reactive variants thereof. All of them provide integration with Spring’s application level transactions. On a lower level, you can grab the Bolt driver instance, but than you have to manage your own transactions in these cases.

即使在现代 Spring Boot 应用程序中，您仍然可以使用 Neo4j-OGM。但您 cannot 将其与 SDN 6+ 一起使用。如果您尝试这样做，您会在两个不同且无关的持久性上下文中拥有两组不同的实体。因此，如果您希望坚持使用 Neo4j-OGM 3.2.x，您将使用 Spring Boot 实例化的 Java 驱动程序，并将其传递给 Neo4j-OGM 会话。Neo4j-OGM 3.2.x 仍受支持，我们建议在 Quarkus 等框架中使用它。然而，在 Spring Boot 应用程序中，首选应该是 SDN。

You still can use Neo4j-OGM, even in modern Spring Boot applications. But you cannot use it with SDN 6+. If you tried you would have two different sets of entities in two different - and unrelated - persistence context. Hence, if you want to stick to Neo4j-OGM 3.2.x, you would use the Java driver instantiated by Spring Boot and pass it onto a Neo4j-OGM session. Neo4j-OGM 3.2.x is still supported, and we recommend its use in frameworks such as Quarkus. In a Spring Boot application however your primary choice should be SDN.

请务必阅读 Frequently Asked Questions，其中我们解决了关于我们的映射决策的许多经常出现的问题，但也解决了如何显着改善与 Neo4j 集群实例（例如 Neo4j AuraDB）和内部部署集群的交互。

Please make sure you read the Frequently Asked Questions where we address many reoccurring questions about our mapping decisions but also how interaction with Neo4j cluster instances such as Neo4j AuraDB and on-premise cluster deployments can be significantly improved.

要理解的重要概念是 Neo4j 书签、 the potential need 以纳入正确的重试机制，例如 Spring Retry 或 Resilience4j（我们推荐后者，因为此知识同样适用于 Spring 之外）以及在 Neo4j 集群上下文中只读查询相对于写查询的重要性。

Concepts that are important to understand are Neo4j Bookmarks, the potential need for incorporating a proper retry mechanism such as Spring Retry or Resilience4j (we recommend the latter, as this knowledge is applicable outside Spring, too) and the importance of read-only vs write queries in the context of Neo4j cluster.