openJiuwen agent-core-java 图执行异常 GraphError 详解:继承链、构造方式与可恢复性语义
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)完成,其优先级为:
- 手动覆盖表(
MANUAL_OVERRIDES):针对个别状态码显式指定异常类型; - 关键字规则(
KEYWORD_RULES):按枚举名包含的关键字(如INVALID、PARAM、EXECUTION、TIMEOUT)匹配ValidationError、FrameworkError、ExecutionError等; - 编码区间规则(
RANGE_BOUNDS):按整数编码落入的区间匹配域异常类型; - 兜底:以上均未命中时使用
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>) 这一构造方式的典型场景:
- 选定语义匹配的状态码
STREAM_PROCESSOR_QUEUE_TIMEOUT; - 以
paramsMap 提供timeout与source两个键; - 最终消息由模板渲染为形如
stream processor queue poll timeout, timeout=30000ms, source=nodeId.keyPath的可读文本。
由此可见,GraphError 被实际用于图执行链路(此处为流式 actor 处理)中的执行期异常表达,与"可恢复、非致命"的语义定位一致——流式轮询超时属于可重试的执行问题。
七、实践建议与编码规范
结合文档与源码,在业务代码中使用 GraphError 时建议遵循以下规范:
- 优先复用状态码:能通过
StatusCode表达的错误,优先使用GraphError(status, params)或ErrorHelper.buildError(status),避免为每个错误手写消息字符串,从而获得统一的错误码与消息模板。 - 保持图异常语义纯净:
GraphError不新增字段,不要在捕获后依赖类型强转取私有状态;需要上下文时,把信息放入params(模板占位符)或details(可序列化细节对象)。 - 按可恢复性分流处理:由于
GraphError.isRecoverable()恒为true,捕获后应走重试/降级路径;框架级致命错误则应交给FrameworkError(isFatal()为true)表达。 - 完整信息构造优先:当需要保留根因时,使用五参构造
GraphError(status, msg, details, cause, params),通过cause保留底层Throwable的调用链。 - 注意解析区间差异:若依赖
StatusMapping自动解析,需知140000–149999区间才映射到GraphError;图引擎自身的112xxx状态码会解析为WorkflowError。需要精确类型时直接显式构造。