错误处理

Vivid 使用 *vivid.Error 表示框架内可序列化、带错误码与错误链的异常。可与 Go 标准库 errors.Is、errors.As 配合做精确判定或统一兜底。本文说明错误类型的设计、判定方式、错误链与 cause 的含义，以及预定义错误码分类。监督与故障上报见 监督策略、创建与生命周期 - Failed。

概述

因此你可以：按错误码做细粒度处理或监控；用 errors.Is(err, vivid.ErrorXxx) 做语义判定；用 errors.Is(err, vivid.ErrorNotFound) 等做统一兜底。

核心类型：*vivid.Error

*vivid.Error 是框架内错误的统一表示，可在分布式环境中序列化传播（仅 code 与 msg 参与序列化；包装的底层错误不参与，反序列化时通过 QueryError(code) 还原为注册的 *Error 实例）。

常用方法与行为

判定方式：errors.Is 与 errors.As

使用标准库 errors.Is 判断“是否等同于某预定义错误”；使用 errors.As 将错误断言为 *vivid.Error 后读取 code 或 message：

if errors.Is(err, vivid.ErrorActorAlreadyExists) {
    // 同父下名称重复
}
if errors.Is(err, vivid.ErrorFutureTimeout) {
    // Ask 超时
}
var vividErr *vivid.Error
if errors.As(err, &vividErr) {
    code := vividErr.GetCode()
    msg := vividErr.GetMessage()
}

错误链与 cause（统一兜底）

部分预定义错误在注册时就挂载了底层 cause，形成一条短链。这样做的目的是：保持该错误的 code 与 message 不变，同时让 errors.Is 能同时命中具体错误和父类错误，便于统一兜底。

例如：ErrorRefNilAgent（AgentRef 为 nil）在语义上属于“资源不存在”，因此注册时挂载 ErrorNotFound 为 cause。返回给调用方的仍是 code=130005、message=agent ref is nil，但 errors.Is(err, vivid.ErrorRefNilAgent) 与 errors.Is(err, vivid.ErrorNotFound) 均为 true。

概念关系如下：

两类父类错误

因此可以按需编写：细粒度逻辑（如针对 ErrorRefNilAgent 单独提示）或粗粒度兜底（如对所有 ErrorNotFound 统一返回 404、对所有 ErrorIllegalArgument 统一返回 400）。

判定流程示意

errors.Is(err, target) 会沿 Unwrap 链递归：先看当前节点是否与 target 匹配（对 *Error 比较 code），若不匹配且存在 Unwrap()，则对底层错误继续 Is。因此“带 cause 的预定义错误”会同时匹配自身与 cause。

预定义错误码一览

预定义错误按功能领域分组，错误码按区间划分，与代码中 RegisterError 一致，便于查找与扩展。完整列表与错误码见 pkg.go.dev - vivid。

系统与运行时

ActorSystem 生命周期、重复启停及通用“资源不存在”。

Actor 与生命周期

Actor 创建、预启动及存活状态。

Future 与消息

Ask/Result、Future 生命周期及消息长度与缓冲读取。

参数与调度

调用参数不合法及调度器（如 Cron）解析失败。

ActorRef

ActorRef 解析、格式及 Agent 引用。

远程通信

跨节点消息发送、编解码、握手与处理。

集群

集群名称校验、加入控制及未启用时的调用。详细说明见 集群错误。

RegisterError 用于在包 init 或启动阶段注册自定义错误码，供跨节点一致识别；可选 optionalCauses 在注册时挂载父类错误，不改变 code 与 message，仅便于 errors.Is / errors.As 命中。