Skip to content

附录 B. 报错码速查 ​

编译器的每个诊断都带一个固定的错误码,以 SPR- 开头。码的含义不会改变:新行为用新码。这份附录按类别列出编译器当前的 100 个码,每个码一行;码和数量都会随编译器更新,最新列表永远以 sprig codes 为准。

B.1 怎么读一个错误码 ​

报错的第一行有四个部分:

text
SPR-NUM-DIVISION [TYPE] main.spr:2:7: Integer / would truncate; use a.divTrunc(b), or convert both operands explicitly (expected explicit division, actual Int / Int)
  • SPR-NUM-DIVISION:错误码,稳定不变;
  • [TYPE]:出错的阶段(词法 LEX、语法 SYNTAX、名字 NAME、类型 TYPE、流程 FLOW、运行时 RUNTIME……);
  • main.spr:2:7:文件、行号和列号(从 1 开始数);
  • 后面是消息;如果有 hint: 行,那是编辑器里"快速修复"也会用的建议。

想看完整的解释,把码交给 sprig explain:

text
$ sprig explain SPR-NUM-DIVISION
SPR-NUM-DIVISION: Integer / is rejected; use divTrunc for deliberate truncation or explicit Float/Decimal arithmetic.
Why it matters: Integer / silently truncates in many languages; Sprig requires the intent to be explicit.
Common causes:
  - Integer division was written with / instead of divTrunc.
Safe fixes:
  - Use value.divTrunc(divisor) only when truncation is intended.
  - Convert to Float or Decimal when fractional arithmetic is intended.
Good:
  let q = (7).divTrunc(2)
Bad:
  let q = 7 / 2

sprig explain <CODE> --json 给出同一份信息,还带上相关章节(relatedHelp,可以直接 sprig help 该主题)和 repair 建议,适合编辑器和 AI 助手读取。sprig check file.spr --json 则把一次检查的全部诊断按结构化 JSON 输出。

下表按前缀分类;每条只写"什么时候出现"。怎么修、为什么这样设计,用 sprig explain 看。

B.2 工具与命令行 ​

错误码什么时候出现
SPR-API-MEMBER--member 要找的声明的成员不存在。
SPR-API-TARGETsprig api 找不到要查看的 Sprig 模块或项目。
SPR-BUNDLE-JDEPSjdeps 无法分析打包的 JAR,找不到程序需要的 Java 模块。
SPR-BUNDLE-LAYOUTJava 安装或 classpath 的布局没法打 bundle:没有可链接的运行时、jlink 失败,或旧的 bundle 删不掉。
SPR-BUNDLE-TOOLSbuild --bundle 需要完整 JDK 的 jdeps 和 jlink,当前用的是 JRE。
SPR-CLI-OPTION命令行缺少必需参数,或者给了未知选项。
SPR-WRAP-CHECKsprig wrap 生成的 Java 包装代码没有通过 Sprig 检查或格式化。

B.3 词法与语法 ​

错误码什么时候出现
SPR-LEX-CHAR输入里有 Sprig 词法不认识的字符。
SPR-LEX-INDENT-FIRST文件的第一行代码必须从第 1 列开始。
SPR-LEX-INDENT-INCONSISTENT减少缩进时必须退回到之前的某个缩进层级。
SPR-LEX-STRING字符串没有收尾,或者含有非法转义。
SPR-LEX-TAB不允许制表符;缩进只能用空格。
SPR-LEX-UNCLOSED(、[ 或 { 开了没有关。
SPR-LEX-UNMATCHED右括号没有对应的左括号。
SPR-SYNTAX-ERROR记号序列不符合 Sprig 语法。

B.4 名字、模块与导出 ​

错误码什么时候出现
SPR-MODULE-EXPORTexport 的目标未知、不合法,或者和可见名字冲突。
SPR-MODULE-EXPORT-ORDER顺序必须是 import、export、普通声明和语句。
SPR-NAME-DUPLICATE同一个命名空间里有两个同名声明。
SPR-NAME-DUPLICATE-MEMBER类或 variant 声明了重复的成员。
SPR-NAME-FIELD-SHADOW参数或局部变量不能和当前类的字段同名。
SPR-NAME-FORWARD-REFERENCE顶层代码使用了在它下面才运行的顶层绑定。
SPR-NAME-IMPORT导入的文件或类无法解析。
SPR-NAME-IMPORT-CYCLESprig 模块互相导入形成环。
SPR-NAME-LET-ASSIGNlet 绑定和 let 字段不能再赋值。
SPR-NAME-NOT-A-VALUE把类型名或模块名当成了值。
SPR-NAME-UNRESOLVED名字在当前作用域链里没有声明。

B.5 调用与构造 ​

错误码什么时候出现
SPR-CALL-ARITY实参个数不对。
SPR-CALL-DUPLICATE-FIELD同一个命名字段给了两次。
SPR-CALL-MISSING-FIELD必填字段没有给。
SPR-CALL-NAMED-REQUIREDSprig 类和 variant 的构造必须用命名参数。
SPR-CALL-POSITIONAL-REQUIRED普通函数和 JVM 调用必须用位置参数。
SPR-CALL-UNKNOWN-FIELD命名参数对不上任何字段。

B.6 类型与泛型 ​

错误码什么时候出现
SPR-GENERIC-CONSTRAINTrequires 写了未知的能力、把契约或类当成了约束、位置不对,或者类型实参在需要 Comparable 的地方不满足。
SPR-TYPE-ASSIGN赋的值和目标类型不匹配。
SPR-TYPE-CALLABLE-THROWS函数值的 throws 子句用在不接受它的位置:只有 fn(...) -> R throws Error 这一种,不能当不带 throws 的类型用。
SPR-TYPE-CAPTURElambda 捕获了 var 局部变量;先复制到 let 再捕获。
SPR-TYPE-CONDITION条件必须是 Bool;Sprig 没有“非零即真”。
SPR-TYPE-FUNCTION-ARITY函数类型和 lambda 只支持 0 到 3 个带类型的参数。
SPR-TYPE-GENERIC-ARGS-REQUIRED泛型调用或构造需要写出 [类型]:实参说不清某个类型参数,或者两个实参说法矛盾。
SPR-TYPE-GENERIC-ARITY泛型声明的类型实参个数不对;按声明顺序全部给出。
SPR-TYPE-GENERIC-NULLABLE这个类型参数在声明里带 ? 使用,所以它的实参必须非空。
SPR-TYPE-INFER不给标注就无法推断类型。
SPR-TYPE-MISMATCH期望类型和实际类型不兼容。
SPR-TYPE-NOT-CALLABLE被调用的东西不可调用,或者把方法名当成了值。
SPR-TYPE-NULLnull 只能赋给显式的可空类型 T?。
SPR-TYPE-NULLABLE可能为 null 的值用在了必须非空的地方;先判断 null。
SPR-TYPE-OPERAND运算符或方法不支持这个操作数类型。
SPR-TYPE-RETURN返回值和声明的返回类型不匹配。
SPR-TYPE-UNITUnit 只能作为函数或方法的结果,不能当字段、参数、集合元素或普通值。

B.7 控制流与运行时 ​

错误码什么时候出现
SPR-FLOW-BREAKbreak 只能出现在循环里。
SPR-FLOW-CATCH-NEVER-THROWNcatch 写了受检 Java 异常,但 try 块里没有任何东西可能抛出它。
SPR-FLOW-CONTINUEcontinue 只能出现在循环里。
SPR-FLOW-MISSING-RETURN非 Unit 函数必须在每条路径上都返回。
SPR-FLOW-RETHROWSrethrows 需要一个函数类型声明了 throws Error 的参数,而且函数自己不能抛别的。
SPR-FLOW-THROWS可恢复错误必须用 throws 声明,或者就地捕获。
SPR-FLOW-THROWS-UNUSED函数声明了受检 Java 异常,但函数体永远抛不出它。
SPR-FLOW-UNREACHABLE语句跟在一条必然退出的语句后面。
SPR-PROGRAM-EXITSprig 程序以非零状态退出。
SPR-RUNTIME-ERROR运行时未捕获的 Sprig Error 值;消息就是 Error 的内容。
SPR-RUNTIME-EXCEPTION运行时未捕获的 JVM 异常,带 Sprig 源码位置;--stacktrace 看完整 JVM 堆栈。

B.8 数字 ​

错误码什么时候出现
SPR-NUM-CONVERSION隐式数值转换可能丢精度或越界,必须用显式方法。
SPR-NUM-DIVISION整数 / 被拒绝;有意截断用 divTrunc,Decimal 用 divide。
SPR-NUM-MIXED二元运算混用了整数和浮点,或者二进制浮点和十进制。
SPR-NUM-RANGE数字字面量超出目标范围,或者小到变成 0。

B.9 类、契约与集合 ​

错误码什么时候出现
SPR-CLASS-ABSTRACT契约类(方法没有函数体的类)声明了字段、混有带体方法、是泛型的,或者被构造了。
SPR-COLLECTION-IMMUTABLEList/Map 是只读的;要改先 toMutableList()/toMutableMap()。
SPR-CONFORM-EFFECTS实现方法声明了 Java 接口方法不允许的受检异常。
SPR-CONFORM-MEMBER类方法没有精确匹配它要见证或覆盖的 Java 方法,或者缺少必需的抽象方法。
SPR-CONFORM-OVERLOADJava 接口要求重载的抽象方法,Sprig 类表示不了。
SPR-CONFORM-PARENT父类视图(as NAME)只能调用继承来的方法;它不是值、没有字段,也不能调用抽象方法。
SPR-CONFORM-SOURCEconform 左边必须是本模块声明的、非泛型、带方法体的 Sprig 类;没有追溯 conform,契约也不能 conform。
SPR-CONFORM-TARGETconform 目标必须是导入的 public、非泛型、非 sealed 的 Java 接口;带括号时是 public、非 final、非泛型的 Java 类(内置 Error 也在此列)。

B.10 枚举、variant 与 match ​

错误码什么时候出现
SPR-MATCH-DUPLICATEmatch 分支重复了同一个 case。
SPR-MATCH-ENUM-BINDER不带载荷的 enum case 不能写 as name。
SPR-MATCH-INFERENCEmatch 表达式的分支给不出非空结果类型,需要显式标注。
SPR-MATCH-NONEXHAUSTIVE每个 enum/variant case 都必须有分支;没有 default。
SPR-MATCH-RESULTmatch 表达式的分支结果类型和期望(或第一个非空分支)不一致。
SPR-MATCH-SCRUTINEEmatch 只能匹配非空的 enum 或 variant 值。
SPR-MATCH-UNKNOWN-CASEcase 名字在匹配的类型上不存在。
SPR-MATCH-WRONG-TYPE分支属于另一个 enum/variant。

B.11 Java 互操作 ​

错误码什么时候出现
SPR-JVM-AMBIGUOUS这些实参类型下 Java 重载有歧义。
SPR-JVM-CLASS导入的 Java 类加载不了,或者它位于无名包。
SPR-JVM-CLASSPATH--classpath 项不存在、为空,或者不是 JAR/目录。
SPR-JVM-COMPILE生成的 Java 源码没有通过 javac;可能是编译器 bug。
SPR-JVM-INTERNAL编译器或工具内部故障。
SPR-JVM-MEMBER没有 Java 方法、构造器或字段匹配这次调用。

B.12 项目与依赖 ​

错误码什么时候出现
SPR-DEP-CHECKSUM锁定的依赖字节和记录的 SHA-256 不符;不要使用损坏的缓存。
SPR-DEP-CYCLESprig 项目依赖构成环。
SPR-DEP-GITGit 依赖操作失败:缺 git、远端、引用或版本。
SPR-DEP-MAVENJVM(Maven)依赖操作失败。
SPR-DEP-NOT-FOUND声明的 Sprig 依赖或模块找不到。
SPR-DEP-OFFLINE离线模式需要的依赖资源不在缓存里。
SPR-DEP-REGISTRY包注册表读不了,或者没有列出请求的包或版本。
SPR-PROJECT-ENTRY项目入口不存在,或者 --bin 指定的名字未知。
SPR-PROJECT-LOCK-MISSING项目没有 sprig.lock;先运行 sprig resolve。
SPR-PROJECT-LOCK-SCHEMA锁文件的 schema 版本不受这个编译器支持。
SPR-PROJECT-LOCK-STALE编译器身份、sprig.toml 或某个依赖的清单和锁不一致;重新 resolve。
SPR-PROJECT-MANIFESTsprig.toml 缺失、格式错,或者缺少必需字段。
SPR-PROJECT-NOT-EXPORTED从依赖导入的模块没有被该依赖导出。
SPR-PROJECT-UNSUPPORTED项目或依赖需要这个编译器还不支持的项目特性或语言版本。

相关章节 ​

Sprig 采用 Apache-2.0 许可证 · v0.7.1-beta.1 已作为 prerelease 发布