服务器错误

在 GQL-status 对象框架中，当用户向服务器执行查询时，它总是会产生一个称为执行结果 (execution outcome) 的输出。如果在执行过程中发生错误，则该结果被记录为异常条件，表示执行失败且无结果。错误的执行结果表示为一系列带有失败结果的 GQL-status 对象，这些对象按以下优先规则进行组织：

GQL-status 对象还包含 Neo4j 特定的信息，例如严重性级别和错误分类。

每个 GQL-status 对象由以下字段组成：

GQL-status 错误对象还可以包含一个可选的 GQL-status 对象，该对象表示错误的原因，并用于提供额外、更具体的诊断信息。

GQLSTATUS 代码分为类和子类。类代码是一个 2 字符的字符串，指示状态的一般条件，如连接异常、数据异常等。子类代码是一个 3 字符的字符串，提供有关该条件的更详细信息。

下表列出了 GQLSTATUS 类及其含义：

用于错误的 Neo4j-status 对象包含代表 Cypher 查询或命令执行未成功的诊断信息，包括严重性、状态码、类别、描述、消息以及查询文本中与错误相关的位置。根据应用程序的不同，错误对象中的某些字段可能不可见。

该错误对象包含以下字段：

有关详细信息，请参阅 Neo4j 错误代码列表。

服务器返回错误并不一定意味着它是致命错误。状态码也可能指示瞬时问题，如果重试请求，这些问题可能会消失。服务器错误组决定了对事务的影响。

Neo4j 以 Java 异常的形式支持服务器错误。它们中的大多数实现了 HasStatus 接口，这意味着除了异常消息外，它们还有一个状态码。

在服务器端，异常包含标准的 Java 构造函数和方法（如 getMessage()、getCause() 等），以及来自 HasStatus API 的 status() 方法（返回状态码）。

异常还获得了 gqlStatus、statusDescription、diagnosticRecord 的强制新字段，以及一个用于 cause 的可选字段。cause 字段本身也拥有自己的 GQLSTATUS、状态描述、诊断记录和消息。
getMessage() 方法被保留，因为 Java 异常本身就具有此方法。此外，添加了一个新的分类字段来涵盖客户端错误、瞬时错误和数据库错误的划分，这在目前是 Neo4j 代码的一部分。所有这些字段共同构成了 GQLSTATUS 对象，作为 Failure Bolt 消息的一部分发送给驱动程序。具体呈现方式取决于驱动程序和服务器版本的组合。有关更多信息，请参阅 服务器-驱动程序版本兼容性。

在驱动程序端，Neo4jException 扩展了与服务器端对应的方法。驱动程序接收 Failure Bolt 消息并提取状态码和错误消息。然后，它构建一个包含状态码、错误消息和其他相关信息的异常，并将其发送给客户端。

由于查询日志位于服务器端且适用于整个 DBMS，因此连接到同一 DBMS 的多个客户端会写入同一个查询日志。由于客户端可能具有不同的驱动程序版本，它们可能具有不同的错误框架格式。

在 Neo4j 5.25 中，查询日志的默认 JSON 模板已更新，包含了一个 errorInfo 条目。该条目包含 GQLSTATUS、statusDescription、classification、position（如果适用）以及 cause（如果适用，且包含相同条目）。

服务器和驱动程序通过 Bolt 协议进行通信。在握手过程中，它们会商定使用服务器和驱动程序双方都支持的最新 Bolt 协议版本。有关不同服务器版本支持的 Bolt 版本的更多信息，请参阅 Bolt 协议文档。

带有额外 GQL-status 错误对象的新错误框架在 Neo4j 5.25 及更高版本的 JSON 格式查询日志中可用。它自 Bolt 5.7 起通过 Bolt 协议支持，这对应于服务器和驱动程序端均为 5.26 或更高版本。

要充分利用新的错误框架，服务器和驱动程序都必须支持它。早于 5.26 版本的驱动程序不会为异常发送任何 GQL-status 对象，即使服务器版本为 5.26 或更高。

如果 5.26 或更高版本的驱动程序与早于 5.26 的服务器通信，驱动程序需要使用 GQL-status 对象对异常进行填充（poly-fill）。在这种情况下，所有异常都将返回默认的 GQLSTATUS 代码 50N42。