错误（Error）

error 声明错误类型。错误是轻量值：统一用 new 构造，沿 fail 通道流动，被消费之后与普通数据无异，可打印、可比较引用、可读载荷。本页讲错误的声明面，抛出与消费的完整口径见失败。

声明形态


error NotFound(key: string);      // 简写：位置载荷
error Boom();                     // 空载荷
error Bad(code: int, msg: string);  // 多字段

简写形必须带载荷，裸 error Name; 不合法。
完整体形 error Name(key: int) { func Hint() -> string { ... } } 可以带方法。
泛型错误 error Bad<T>(value: T); 合法，实例化即类型（Bad<int> 与 Bad<string> 是不同错误），构造时实参可推断（new Bad(42) 推成 Bad<int>）。
sealed error Name(...); 禁止再被继承。

继承与载荷前缀

错误单继承，冒号写基错误。派生的载荷必须以基载荷为前缀（同序同名同型，可追加）：


error NotFound(key: string);
error Wrapped(key: string, msg: string) : NotFound;
 
val w = new Wrapped("银", "补充");
print(w.key, w.msg);


银 补充

w 同时携带两个自己的字段。基错误臂能接住派生值（match / recover 里写基错误名臂，载荷按基声明前缀位读取），fail 契约沿继承链覆盖。

errors 并集

errors 把几个错误并成一个名字，专门用于 fail 子句：


errors App = NotFound | Boom;
 
func Load(key: string) fail App -> int
{
    if key == "金"
    {
        return 7;
    }
    fail new NotFound(key);
}

并集只出现在 fail 子句位，不是值类型，拿它当参数或变量类型报未知类型。

构造点出处 @site

每个错误值自动携带构造点的 file:line:col，经隐藏字段 @site 读取：


val b = capture Load("银");
match b
{
    Success(v) => print("得到", v),
    Failure(e) => print("失败", e.key, e.@site is string),
}


失败 银 True

@site 不占载荷位、不参与相等比较（错误相等是引用比较）。

错误值的判别

错误值支持 is 类型测试与 as 转换，继承链语义随行，派生值 is 基错误为 True，反向为 False：


func LoadWrap(key: string) fail Wrapped -> int
{
    if key == "金" { return 7; }
    fail new Wrapped(key, "补充");
}
 
val e = recover capture LoadWrap("银")
{
    Success(x) => new NotFound("空"),
    Failure(err) => err,
};
print(e is NotFound, e is Wrapped);
if e is Wrapped
{
    val wr = e as Wrapped;
    print(wr?.msg);
}


True True
补充

e 装的是派生错误 Wrapped：e is NotFound 沿继承链判 True，e is Wrapped 自身判 True。反过来普通 NotFound 传进 is Wrapped 得 False。

注意

判断错误种类优先用 match 错误名臂（可顺带解构载荷），is / as 适合轻量分支，见失败。
错误相等是引用比较。

最后更新于 2026年10月9日