Neo4jClient

Spring Data Neo4j 附带一个 Neo4j 客户端，它在 Neo4j 的 Java 驱动程序之上提供了一个薄层。

虽然纯 Java 驱动程序是一个非常通用的工具，除了命令式和响应式版本之外还提供异步 API，但它不与 Spring 应用程序级事务集成。

SDN 尽可能直接地通过一种惯用客户端的概念使用驱动程序。

该客户端有以下主要目标

  1. 将 Spring 的事务管理集成到命令式和响应式场景中

  2. 必要时参与 JTA 事务

  3. 为命令式和响应式场景提供一致的 API

  4. 不增加任何映射开销

SDN 依赖所有这些特性并使用它们来实现其实体映射特性。

请查看SDN 构建块，了解命令式和响应式 Neo4 客户端在我们的堆栈中的位置。

Neo4j 客户端有两种风格

  • org.springframework.data.neo4j.core.Neo4jClient

  • org.springframework.data.neo4j.core.ReactiveNeo4jClient

虽然两个版本都提供了使用相同词汇和语法的 API，但它们不是 API 兼容的。两个版本都具有相同的流畅 API 来指定查询、绑定参数和提取结果。

命令式还是响应式？

与 Neo4j 客户端的交互通常以调用以下方法结束：

  • fetch().one()

  • fetch().first()

  • fetch().all()

  • run()

命令式版本将在此时与数据库交互并获取请求的结果或摘要，并将其包装在 Optional<> 或 Collection 中。

相比之下，响应式版本将返回请求类型的发布者。与数据库的交互和结果的检索在发布者被订阅之前不会发生。发布者只能被订阅一次。

获取客户端实例

与 SDN 中的大多数事物一样，两个客户端都依赖于已配置的驱动程序实例。

创建命令式 Neo4j 客户端实例
import org.neo4j.driver.AuthTokens;
import org.neo4j.driver.Driver;
import org.neo4j.driver.GraphDatabase;

import org.springframework.data.neo4j.core.Neo4jClient;

public class Demo {

    public static void main(String...args) {

        Driver driver = GraphDatabase
            .driver("neo4j://:7687", AuthTokens.basic("neo4j", "secret"));

        Neo4jClient client = Neo4jClient.create(driver);
    }
}

驱动程序只能针对 4.0 数据库打开响应式会话，并且在任何较低版本上都会失败并抛出异常。

创建响应式 Neo4j 客户端实例
import org.neo4j.driver.AuthTokens;
import org.neo4j.driver.Driver;
import org.neo4j.driver.GraphDatabase;

import org.springframework.data.neo4j.core.ReactiveNeo4jClient;

public class Demo {

    public static void main(String...args) {

        Driver driver = GraphDatabase
            .driver("neo4j://:7687", AuthTokens.basic("neo4j", "secret"));

        ReactiveNeo4jClient client = ReactiveNeo4jClient.create(driver);
    }
}
如果您启用了事务，请确保为客户端使用与为 Neo4jTransactionManager 或 ReactiveNeo4jTransactionManager 提供实例时使用的相同驱动程序实例。如果您使用另一个驱动程序实例，客户端将无法同步事务。

我们的 Spring Boot Starter 提供了一个可即用的 Neo4j 客户端 bean，它适合环境（命令式或响应式），您通常无需配置自己的实例。

用法

选择目标数据库

Neo4j 客户端已充分准备好与 Neo4j 4.0 的多数据库特性一起使用。除非您另有指定，否则客户端使用默认数据库。客户端的流畅 API 允许在声明要执行的查询之后只指定一次目标数据库。选择目标数据库使用响应式客户端演示了这一点

选择目标数据库
Flux<Map<String, Object>> allActors = client
	.query("MATCH (p:Person) RETURN p")
	.in("neo4j") (1)
	.fetch()
	.all();
1 选择要执行查询的目标数据库。

指定查询

与客户端的交互从查询开始。查询可以由纯 String 或 Supplier<String> 定义。供应商将尽可能晚地进行评估，并且可以由任何查询构建器提供。

指定查询
Mono<Map<String, Object>> firstActor = client
	.query(() -> "MATCH (p:Person) RETURN p")
	.fetch()
	.first();

检索结果

如前面的列表中所示，与客户端的交互总是以调用 fetch 以及应接收多少结果而结束。响应式和命令式客户端都提供

one()

预期查询只返回一个结果

first()

预期有结果并返回第一条记录

all()

检索所有返回的记录

命令式客户端分别返回 Optional<T> 和 Collection<T>，而响应式客户端返回 Mono<T> 和 Flux<T>，后者只有在订阅后才会执行。

如果您不期望查询有任何结果，那么在指定查询后使用 run()。

以响应式方式检索结果摘要
Mono<ResultSummary> summary = reactiveClient
    .query("MATCH (m:Movie) where m.title = 'Aeon Flux' DETACH DELETE m")
    .run();

summary
    .map(ResultSummary::counters)
    .subscribe(counters ->
        System.out.println(counters.nodesDeleted() + " nodes have been deleted")
    ); (1)
1 实际查询在此处通过订阅发布者触发。

请花点时间比较这两个列表并理解实际查询何时触发的差异。

以命令式方式检索结果摘要
ResultSummary resultSummary = imperativeClient
	.query("MATCH (m:Movie) where m.title = 'Aeon Flux' DETACH DELETE m")
	.run(); (1)

SummaryCounters counters = resultSummary.counters();
System.out.println(counters.nodesDeleted() + " nodes have been deleted")
1 在这里，查询立即触发。

映射参数

查询可以包含命名参数（$someName），Neo4j 客户端可以轻松地将值绑定到它们。

客户端不检查所有参数是否都已绑定，或者是否存在过多的值。这留给驱动程序处理。但是，客户端会阻止您两次使用相同的参数名称。

您可以绑定驱动程序无需转换即可理解的简单类型或复杂类。对于复杂类，您需要提供一个绑定器函数，如此列表所示。请查看驱动程序手册，了解支持哪些简单类型。

映射简单类型
Map<String, Object> parameters = new HashMap<>();
parameters.put("name", "Li.*");

Flux<Map<String, Object>> directorAndMovies = client
	.query(
		"MATCH (p:Person) - [:DIRECTED] -> (m:Movie {title: $title}), (p) - [:WROTE] -> (om:Movie) " +
			"WHERE p.name =~ $name " +
			"  AND p.born < $someDate.year " +
			"RETURN p, om"
	)
	.bind("The Matrix").to("title") (1)
	.bind(LocalDate.of(1979, 9, 21)).to("someDate")
	.bindAll(parameters) (2)
	.fetch()
	.all();
1 有一个用于绑定简单类型的流畅 API。
2 或者，参数可以通过命名参数的映射进行绑定。

SDN 执行许多复杂的映射，它使用与您可以从客户端使用的相同的 API。

您可以为任何给定的领域对象（例如领域类型示例中的自行车所有者）提供 Function<T, Map<String, Object>> 给 Neo4j 客户端，以将这些领域对象映射为驱动程序可以理解的参数。

领域类型示例
public class Director {

    private final String name;

    private final List<Movie> movies;

    Director(String name, List<Movie> movies) {
        this.name = name;
        this.movies = new ArrayList<>(movies);
    }

    public String getName() {
        return name;
    }

    public List<Movie> getMovies() {
        return Collections.unmodifiableList(movies);
    }
}

public class Movie {

    private final String title;

    public Movie(String title) {
        this.title = title;
    }

    public String getTitle() {
        return title;
    }
}

映射函数必须填充查询中可能出现的所有命名参数，如使用映射函数绑定领域对象所示

使用映射函数绑定领域对象
Director joseph = new Director("Joseph Kosinski",
        Arrays.asList(new Movie("Tron Legacy"), new Movie("Top Gun: Maverick")));

Mono<ResultSummary> summary = client
    .query(""
        + "MERGE (p:Person {name: $name}) "
        + "WITH p UNWIND $movies as movie "
        + "MERGE (m:Movie {title: movie}) "
        + "MERGE (p) - [o:DIRECTED] -> (m) "
    )
    .bind(joseph).with(director -> { (1)
        Map<String, Object> mappedValues = new HashMap<>();
        List<String> movies = director.getMovies().stream()
            .map(Movie::getTitle).collect(Collectors.toList());
        mappedValues.put("name", director.getName());
        mappedValues.put("movies", movies);
        return mappedValues;
    })
    .run();
1 with 方法允许指定绑定器函数。

使用结果对象

两个客户端都返回映射（Map<String, Object>）的集合或发布者。这些映射与查询可能产生的记录完全对应。

此外，您可以通过 fetchAs 插入您自己的 BiFunction<TypeSystem, Record, T> 来重现您的领域对象。

使用映射函数读取领域对象
Mono<Director> lily = client
    .query(""
        + " MATCH (p:Person {name: $name}) - [:DIRECTED] -> (m:Movie)"
        + "RETURN p, collect(m) as movies")
    .bind("Lilly Wachowski").to("name")
    .fetchAs(Director.class).mappedBy((TypeSystem t, Record record) -> {
        List<Movie> movies = record.get("movies")
            .asList(v -> new Movie((v.get("title").asString())));
        return new Director(record.get("name").asString(), movies);
    })
    .one();

TypeSystem 允许访问底层 Java 驱动程序用于填充记录的类型。

使用领域感知映射函数

如果您知道查询结果将包含在您的应用程序中具有实体定义的节点，您可以使用可注入的 MappingContext 来检索它们的映射函数并在映射期间应用它们。

使用现有映射函数
BiFunction<TypeSystem, MapAccessor, Movie> mappingFunction = neo4jMappingContext.getRequiredMappingFunctionFor(Movie.class);
Mono<Director> lily = client
    .query(""
        + " MATCH (p:Person {name: $name}) - [:DIRECTED] -> (m:Movie)"
        + "RETURN p, collect(m) as movies")
    .bind("Lilly Wachowski").to("name")
    .fetchAs(Director.class).mappedBy((TypeSystem t, Record record) -> {
        List<Movie> movies = record.get("movies")
            .asList(movie -> mappingFunction.apply(t, movie));
        return new Director(record.get("name").asString(), movies);
    })
    .one();

在使用托管事务时直接与驱动程序交互

如果您不想要或不喜欢 Neo4jClient 或 ReactiveNeo4jClient 这种自以为是的“客户端”方法，您可以让客户端将所有与数据库的交互委托给您的代码。委托后的交互在客户端的命令式和响应式版本中略有不同。

命令式版本接受 Function<StatementRunner, Optional<T>> 作为回调。返回空 Optional 是可以的。

将数据库交互委托给命令式 StatementRunner
Optional<Long> result = client
    .delegateTo((StatementRunner runner) -> {
        // Do as many interactions as you want
        long numberOfNodes = runner.run("MATCH (n) RETURN count(n) as cnt")
            .single().get("cnt").asLong();
        return Optional.of(numberOfNodes);
    })
    // .in("aDatabase") (1)
    .run();
1 选择目标数据库中所述的数据库选择是可选的。

响应式版本接收 RxStatementRunner。

将数据库交互委托给响应式 RxStatementRunner
Mono<Integer> result = client
    .delegateTo((RxStatementRunner runner) ->
        Mono.from(runner.run("MATCH (n:Unused) DELETE n").summary())
            .map(ResultSummary::counters)
            .map(SummaryCounters::nodesDeleted))
    // .in("aDatabase") (1)
    .run();
1 可选的目标数据库选择。

请注意，在将数据库交互委托给命令式 StatementRunner 和将数据库交互委托给响应式 RxStatementRunner 中，运行器的类型仅是为了向本手册的读者提供更清晰的说明。

© . This site is unofficial and not affiliated with VMware.