服务器错误

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

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

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

错误对象包含以下字段：

欲了解更多信息，请参阅 Neo4j 错误代码列表。

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

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

在服务器端，异常包含正常的 Java 构造函数和方法，例如 getMessage()、getCause() 等，此外还有 HasStatus API 中的 status() 方法，该方法返回状态代码。

异常还新增了 gqlStatus、statusDescription、diagnosticRecord 的强制字段，以及 cause 的可选字段。cause 字段又包含其自己的 GQLSTATUS、状态描述、诊断记录和消息。
保留了 getMessage() 方法，因为 Java 异常固有此方法。并新增了一个分类字段，涵盖客户端错误、暂时性错误和数据库错误的划分，这在今天是 Neo4j 代码的一部分。所有这些字段共同构建了 GQLSTATUS 对象，该对象作为故障 Bolt 消息的一部分发送给驱动程序。具体表现形式取决于驱动程序和服务器版本的组合。欲了解更多信息，请参阅 服务器-驱动程序版本兼容性。

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

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

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

服务器和驱动程序通过 Bolt 协议相互通信。在握手过程中，它们就使用服务器和驱动程序都支持的最新 Bolt 协议版本达成一致。有关不同服务器版本支持的 Bolt 版本，请参阅 Bolt 协议文档。

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

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

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