openJiuwen agent-core-java 图执行异常 GraphError 详解:继承链、构造方式与可恢复性语义

原创2026-10-12 23:01:501,698 阅读
文章标签:人工智能大模型AI AgentAgent 框架Agent 工作流多智能体工具调用MCP 服务Agent 记忆RAG后端Agent 沙箱

openJiuwen agent-core-java 图执行异常 GraphError 详解:继承链、构造方式与可恢复性语义

GraphError 是 openJiuwen agent-core-java 框架统一异常体系中专用于表达图(Graph)执行异常的细粒度异常类型。本文以官方 API 文档为骨架,结合仓库源码(GraphError.java、BaseError.java、StatusCode.java 等)与测试用例,完整讲解其继承链、三种构造方式、消息模板渲染机制、可恢复性/致命性语义、StatusMapping 解析规则及真实使用场景,帮助读者在实际开发中正确抛出、识别与处理图执行阶段的异常。

一、GraphError 在异常体系中的位置

GraphError 的完整继承链为:

java.lang.RuntimeException
└── com.openjiuwen.core.common.exception.BaseError
    └── com.openjiuwen.core.common.exception.ExecutionError
        └── com.openjiuwen.core.common.exception.GraphError

源码中类声明如下(GraphError.java):

public class GraphError extends ExecutionError {
    public GraphError(StatusCode status, String msg, Object details, Throwable cause, Map<String, Object> params) { super(status, msg, details, cause, params); }
    public GraphError(StatusCode status, Map<String, Object> params) { super(status, params); }
    public GraphError(StatusCode status) { super(status); }
}

从源码结构看,GraphError 与同包下的 WorkflowError、AgentError、RunnerError 等类型一样,只负责表达更细粒度的异常语义,不新增任何字段或公开方法——所有状态信息、消息模板渲染、可恢复性判定等能力均继承自 BaseError。它的类注释还明确指出,该类镜像自 Python 版 openjiuwen/core/common/exception/errors.py 中的 GraphError,是同一异常设计在 Java 端的对齐实现。

在框架的统一异常体系中,BaseError(BaseError.java)是所有业务异常的根类,它继承 RuntimeException,内部保存以下核心状态:

字段 类型 说明
status StatusCode 枚举状态码,携带整数编码 code 与消息模板 errmsg
code int 从 StatusCode 派生的整数错误码
params Map<String, Object> 模板参数,用于渲染 errmsg 中的 {placeholder} 占位符
details Object 可选的细节对象,构造时经 SerializationUtils.requireSerializable 校验可序列化
templateMessage String 按模板渲染出的消息正文
message String 最终展示的消息(自定义消息优先,否则取模板渲染结果)
recoverable / fatal boolean 可恢复性 / 致命性标记,由子类 defaultRecoverable() / defaultFatal() 决定

BaseError 还提供 toMap()(输出 code、status、message、params、raw_message、details 六项)、toDict() 与 toJson() 等方法,方便异常在接口层结构化输出。

二、三种构造方式与参数说明

GraphError 提供三种构造方式,覆盖从"仅状态码"到"完整上下文"的全部场景:

签名 说明
public GraphError(StatusCode status, String msg, Object details, Throwable cause, Map<String, Object> params) 接收完整的状态码、自定义消息、细节对象、根因异常与模板参数,信息最全
public GraphError(StatusCode status, Map<String, Object> params) 仅提供 StatusCode 与模板参数,消息正文按 StatusCode.errmsg 渲染
public GraphError(StatusCode status) 仅基于 StatusCode 构造异常实例,消息由状态码自带模板渲染

各参数的实际影响如下:

  • status(必填):StatusCode 枚举值。它决定整数错误码(getCode())和默认消息模板(getErrmsg())。选择与图执行语义匹配的状态码,例如流式处理超时用 STREAM_PROCESSOR_QUEUE_TIMEOUT,图状态提交失败用 GRAPH_STATE_COMMIT_ERROR。
  • msg(可选):自定义消息。BaseError 构造逻辑为:msg 非空时直接作为最终 message;为空时回退到模板渲染结果 templateMessage(见 BaseError.java)。
  • details(可选):附加细节对象(如出错的节点 ID、上下文 Map)。构造时会执行 SerializationUtils.requireSerializable(details, "details") 校验,保证异常可被安全序列化传递。
  • cause(可选):根因异常,便于保留完整调用栈,用于包装底层 InterruptedException、IO 异常等。
  • params(可选):模板参数 Map,用于填充 errmsg 模板中的 {placeholder}。传入后被封装为不可变 Map(Collections.unmodifiableMap)。

消息模板渲染机制

GraphError 的消息正文依赖 BaseError 的模板渲染能力。StatusCode 的每个枚举成员都携带一条支持 {placeholder} 语法的消息模板(StatusCode.java),例如:

STREAM_PROCESSOR_QUEUE_TIMEOUT(111136, "stream processor queue poll timeout, timeout={timeout}ms, source={source}")
GRAPH_VERTEX_EXECUTION_ERROR(112050, "vertex execute error, error=''{reason}'', node_id={node_id}")

渲染逻辑位于 BaseError.formatTemplate(BaseError.java):

  • 模板中的 {key} 会被 params 中同名的值替换;
  • 缺失的参数会渲染为 <missing:key>,不会抛异常,保证错误信息始终可读;
  • 渲染过程本身有兜底:若渲染失败,直接返回原始 errmsg。

对应的测试用例 testFormatTemplateMissingKeySafe(ErrorTest.java)验证了"空参数渲染时出现 <missing:...> 占位符"这一安全行为。

三、可恢复性与致命性语义

GraphError 继承 ExecutionError 的默认语义,这是它最重要的运行时行为之一:

  • isRecoverable() 返回 true(默认可恢复)
  • isFatal() 返回 false(默认非致命)

这两个默认值由 ExecutionError 覆写的钩子方法决定(ExecutionError.java):

@Override protected boolean defaultRecoverable() { return true; }
@Override protected boolean defaultFatal() { return false; }

而 BaseError 基类的默认实现则是 recoverable = false、fatal = false,各异常类型通过覆写这两个钩子来差异化表达语义。对比同体系中的其他类型:

异常类型 isRecoverable isFatal 语义定位
GraphError(继承 ExecutionError) true false 图执行期异常,可恢复、非致命
FrameworkError false true 框架级系统错误,不可恢复、致命
ValidationError false false 校验类错误,不可恢复、非致命

也就是说:当你在图执行链路中捕获到 GraphError 时,可以推断它是执行期(而非配置校验期或框架故障期)的问题,调用方通常可以在修复触发条件后重试,而不应将其视为框架层面的致命崩溃。

相关语义均有测试覆盖。ErrorTest 的 ExceptionHierarchy 嵌套类(ErrorTest.java)明确断言:ExecutionError 默认可恢复且非致命,并验证了 GraphError 的父类链路(GraphError 属于 BaseError 与 ExecutionError 的子类族)。

四、StatusMapping 如何解析出 GraphError

在框架中,开发者通常不直接 new 异常,而是通过 ErrorHelper.buildError(StatusCode) / ErrorHelper.raiseError(StatusCode) 按状态码自动解析出最合适的异常类型。这一解析由 StatusMapping(StatusMapping.java)完成,其优先级为:

  1. 手动覆盖表(MANUAL_OVERRIDES):针对个别状态码显式指定异常类型;
  2. 关键字规则(KEYWORD_RULES):按枚举名包含的关键字(如 INVALID、PARAM、EXECUTION、TIMEOUT)匹配 ValidationError、FrameworkError、ExecutionError 等;
  3. 编码区间规则(RANGE_BOUNDS):按整数编码落入的区间匹配域异常类型;
  4. 兜底:以上均未命中时使用 ExecutionError。

从源码结构看,GraphError 与编码区间 140000–149999 绑定(RANGE_EXCEPTION_NAMES 中该区间对应 "GraphError"),同时 EXCEPTION_REGISTRY 中注册了 GraphError::new 工厂。ErrorHelper.createWithDetails 的 switch 分支中也包含 case "GraphError" -> new GraphError(status, msg, details, cause, params)(ErrorHelper.java),因此经由 ErrorHelper.buildError 构造带完整上下文参数的图异常时,最终落地为 GraphError 实例。

需要注意的一个实现细节:StatusCode 中图引擎自身的错误码(GRAPH_*、PREGEL_*、DRAWABLE_*,编码位于 112000–112999)落在 100000–119999 区间,会被 StatusMapping 解析为 WorkflowError 而非 GraphError;GraphError 的解析区间是 140000–149999。因此"图引擎状态码"与"GraphError 类型"并非一一对应,实际解析结果以 StatusMapping 的区间规则为准。若需要精确控制异常类型,可以直接使用 new GraphError(...) 构造。

五、图执行相关的 StatusCode 参考

GraphError 实例携带的 StatusCode 决定了错误码与消息模板。图执行域的状态码集中在 StatusCode 的 "Graph Engine 112000–112999" 区块(StatusCode.java),代表性的有:

枚举成员 编码 消息模板(节选)
GRAPH_STATE_COMMIT_ERROR 112030 graph commit state error, error=''{reason}''
GRAPH_VERTEX_EXECUTION_ERROR 112050 vertex execute error, error=''{reason}'', node_id={node_id}
GRAPH_VERTEX_STREAM_CALL_TIMEOUT 112051 vertex stream timeout, timeout={timeout}, node_id={node_id}
GRAPH_VERTEX_STREAM_CALL_ERROR 112052 vertex stream call error, error=''{reason}'', node_id={node_id}
GRAPH_VERTEX_ABILITY_LATCH_TIMEOUT 112053 vertex ability latch await timeout, timeout={timeout}ms, node_id={node_id}
GRAPH_VERTEX_FUTURE_TIMEOUT 112054 vertex future get timeout, timeout={timeout}ms, node_id={node_id}
PREGEL_GRAPH_NODE_ID_INVALID 112100 node id is invalid, node_id={node_id}, error=''{reason}''
PREGEL_GRAPH_EDGE_INVALID 112102 edge is invalid, source_id={source_id}, target_id={target_id}, error=''{reason}''
STREAM_PROCESSOR_QUEUE_TIMEOUT 111136 stream processor queue poll timeout, timeout={timeout}ms, source={source}

这些模板中的 {node_id}、{timeout}、{reason}、{source} 等占位符,正是构造 GraphError(status, params) 时应传入的 params 键。

六、真实使用示例:StreamProcessor 中的 GraphError

图引擎源码中已存在 GraphError 的实际用法。在 StreamProcessor.java 中,当流处理器从阻塞队列轮询消息超时(收到 TIMEOUT_SENTINEL)时,会抛出 GraphError:

throw new GraphError(
        StatusCode.STREAM_PROCESSOR_QUEUE_TIMEOUT,
        Map.of("timeout", TimeoutConstants.BLOCKING_QUEUE_MS,
                "source", nodeId + "." + keyPath));

这段代码展示了 GraphError(StatusCode, Map<String, Object>) 这一构造方式的典型场景:

  1. 选定语义匹配的状态码 STREAM_PROCESSOR_QUEUE_TIMEOUT;
  2. 以 params Map 提供 timeout 与 source 两个键;
  3. 最终消息由模板渲染为形如 stream processor queue poll timeout, timeout=30000ms, source=nodeId.keyPath 的可读文本。

由此可见,GraphError 被实际用于图执行链路(此处为流式 actor 处理)中的执行期异常表达,与"可恢复、非致命"的语义定位一致——流式轮询超时属于可重试的执行问题。

七、实践建议与编码规范

结合文档与源码,在业务代码中使用 GraphError 时建议遵循以下规范:

  1. 优先复用状态码:能通过 StatusCode 表达的错误,优先使用 GraphError(status, params) 或 ErrorHelper.buildError(status),避免为每个错误手写消息字符串,从而获得统一的错误码与消息模板。
  2. 保持图异常语义纯净:GraphError 不新增字段,不要在捕获后依赖类型强转取私有状态;需要上下文时,把信息放入 params(模板占位符)或 details(可序列化细节对象)。
  3. 按可恢复性分流处理:由于 GraphError.isRecoverable() 恒为 true,捕获后应走重试/降级路径;框架级致命错误则应交给 FrameworkError(isFatal() 为 true)表达。
  4. 完整信息构造优先:当需要保留根因时,使用五参构造 GraphError(status, msg, details, cause, params),通过 cause 保留底层 Throwable 的调用链。
  5. 注意解析区间差异:若依赖 StatusMapping 自动解析,需知 140000–149999 区间才映射到 GraphError;图引擎自身的 112xxx 状态码会解析为 WorkflowError。需要精确类型时直接显式构造。

八、相关文档与源码索引

登录后查看全文
agent-core-java