JVM 互操作
Sprig 会先编译成 Java 再运行,所以 JDK 自带的类和 Maven 上的 Java 库都能直接用。这页讲怎么导入、调用 Java 类,以及 Sprig 在和 Java 交接的地方会做哪些检查。
总的原则偏保守:Java 没说一个返回值不会是 null,Sprig 就当它可能是 null。toString() 总是返回 String,标了非空注解的结果也是普通的值(见下面)。反过来,你传给 Java 的参数默认不能是 null,标了 @Nullable 的参数除外。
完整规则见 JVM 互操作参考(英文)。想把 Sprig 接进 Gradle、Loom 这类现有构建,见 Gradle 集成和 Fabric 模组。Java 互操作实用配方把五种反复遇到的情况各走了一遍:可空值、异常、集合、回调和重载。
导入和调用 Java 类
import java.lang.Math as Math
import java.lang.StringBuilder as StringBuilder
import java.time.LocalDate as LocalDate
print(Math.max(3, 9))
print(Math.abs(-4))
let builder = StringBuilder()
builder.append("Sprig")
builder.append("!")
print(builder.toString())
# Java reference results are nullable until checked.
let date = LocalDate.of(2026, 9, 25)
if date != null:
print(date.getYear())
print(date.getDayOfMonth())9
4
Sprig!
2026
25import java.lang.Math as Math让你在这个文件里用Math指代这个类。java.lang下的类也要这样导入,不会自动导入。- 构造器、静态方法、实例方法和静态字段都能通过这个名字使用。
- 有重载时,Sprig 按参数类型挑选。没有匹配的方法会报
SPR-JVM-MEMBER,有好几个同样合适的会报SPR-JVM-AMBIGUOUS。
Java 返回的值要先判空
Java 方法返回的对象,包括 String 和 Integer 这类装箱类型,都被当作可能为 null,用之前要检查:
import java.lang.System as System
let version = System.getProperty("java.version")
if version != null:
print(version.length() > 0)true返回基本类型(long、int、double、boolean 等)的方法不会返回 null,结果可以直接用。
反过来,传给 Java 的参数默认不能是 null,参数类型是 Object 也一样。所以 T? 类型的值要先检查,再传给 Java。Sprig 会读取可空性注解:标了 @NotNull/@NonNull(或者所在类、包标了 @NullMarked)的结果就是普通的 T,标了 @Nullable 的参数接受 T? 或 null。运行时可见的注解(JSpecify、JSR-305)通过反射读,只保留在 class 文件里的注解(比如 org.jetbrains.annotations)直接从 class 文件里读。Minecraft 本身用 JSpecify 标注,每个包都有 @NullMarked,所以 Item.use、Component.literal 拿到的就是普通值,只有标了 @Nullable 的成员才是 T?。
类型对照
| Java | Sprig(基本类型) | Sprig(装箱类型和对象) |
|---|---|---|
long | Int | Int? |
int、short、byte | Int32 | Int32? |
double | Float | Float? |
float | Float32 | Float32? |
boolean | Bool | Bool? |
char | String | String? |
void | Unit | — |
String 和其他对象类型 | — | 对应的可空类型 T? |
有几处要注意:
Int传给int会带检查地收窄。 把Int传到 Java 需要int或Integer的地方(参数、构造器参数、变长参数元素、普通的字段赋值,或者比较器这类回调的返回值)时,会做范围检查,值装不下就在运行时报错。精确匹配的long重载仍然优先,所以Math.max(a, b)还是走long版本。范围合适的整数字面量也可以传给short、byte参数,但变量不会收窄到这两种类型;Float也不会收窄成float,因为那丢的是精度而不是范围,要用toFloat32Exact()。char参数只接受一个字符的字面量。char和Character参数只接受恰好一个 UTF-16 字符的字符串字面量。"a"可以,"ab"不行,"😀"也不行,因为一个 Javachar装不下它。Sprig 自己的字符串则按 Unicode 码点计算位置,详见sprig help strings。
捕获 Java 异常
Java 的受检异常可以写进 Sprig 的 throws,也可以用 catch 捕获:
import java.net.URI as URI
import java.net.URISyntaxException as URISyntax
func parse_uri(text: String) -> String throws URISyntax:
let uri = URI(text)
if uri != null:
let host = uri.getHost()
if host != null:
return host
return ""
try:
print(parse_uri("https://example.com"))
print(parse_uri("::bad"))
catch problem: URISyntax:
print("bad uri")example.com
bad uri捕获到的 Java 异常,不管是打印、拼接还是调用 toString(),显示的都是 Java 的格式,类名在前。它的 message 是 String?,因为 Java 的 getMessage() 可能返回 null,拼接之前要先检查。Sprig 的 Error 只显示消息本身。
Java 集合和 Sprig 集合
Java 的 List、Map 不会自动变成 Sprig 的集合,Sprig 的集合也不会被悄悄当作 Java 集合传进去。需要转换时,用 @std/jvm.spr 里的函数:
import "@std/jvm.spr" as jvm
import java.util.ArrayList as ArrayList
let names = ArrayList[String]()
names.add("Ada")
names.add("Grace")
let snapshot = jvm.list_snapshot[String](names)
names.add("Linus")
print(snapshot.size())
print(names.size())
let copy = jvm.list_copy[String](snapshot)
print(copy.size())2
3
2list_snapshot和map_snapshot把 Java 集合按顺序复制成只读的 SprigList和Map。之后 Java 那边怎么改,快照都不受影响:上面names加了第三个名字,snapshot还是两个。list_copy和map_copy反过来,把 Sprig 集合复制成独立的 JavaArrayList和LinkedHashMap,两边各改各的。- Java 集合里如果有
null元素、键或值,复制时会报运行时错误,不会让null混进不允许为空的 Sprig 集合。 - 元素类型要和来源一致,写错了在检查阶段就会报错。
- 这几个函数都声明了
throws Error,在函数里调用时记得处理。
Java 泛型类
导入的 Java 类和泛型方法也可以带具体的类型参数,比如上面的 ArrayList[String]()。
- 类型参数会完整保留,
List[Map[String, Int32]]、Host.method[String](value)这样的写法都可以,经由父类或接口传下来的类型参数也能识别。 - 返回值照样被当作可能为
null,所以ArrayList[String]的get返回String?。 - 泛型方法自己的类型参数,只要实参能把每一个都唯一确定,就会自动推断(
Collections.sort(names)、List.of(1, 2, 3));只出现在返回值里的,或者只能靠 lambda 确定的,要自己写出来(Collectors.toList[Int]())。 - 没有类型参数的原始类型(raw type)不能当作带参数的类型使用。
ArrayList[String]()可以当List[String]用,没写类型参数的ArrayList()不行。 - 通配符会保留边界:
List<? extends Number>的结果读出来是Number?,List<? extends Number>形参可以接收ArrayList[Int],而任何会穿过? extends写入的成员(比如add)都会被拒绝。泛型数组(T[])不支持,用sprig api查询时会看到对应的原因代码。
数组和字节
Java 数组在 Sprig 里是一个整体,不能拆开用。你可以接收它、判空、原样传给另一个需要同类数组的 Java 方法,但不能在 Sprig 里创建、索引、修改或遍历它。Sprig 没有数组语法,这些写法在调用 javac 之前就会被拒绝,报 SPR-SYNTAX-ERROR 或 SPR-TYPE-OPERAND。重载匹配时,byte[]、int[]、String[]、Object[] 会被区分开,数组之间能否互相传递按 JVM 的实际规则判断。
二进制数据最常见的形式是 byte[],可以用 sprig.runtime.jvm.HostBytes 来转换:
import sprig.runtime.jvm.HostBytes as HostBytes
let bytes = HostBytes.utf8("Sprig")
if bytes != null:
print(HostBytes.length(bytes))
print(HostBytes.hex(bytes))5
5370726967| 方法 | 作用 |
|---|---|
HostBytes.utf8(text) | 字符串转成 UTF-8 字节 |
HostBytes.utf8String(bytes) | UTF-8 字节转回字符串;不是合法的 UTF-8 时报运行时错误 |
HostBytes.length(bytes) | 字节数,返回 Int |
HostBytes.hex(bytes) | 转成小写的十六进制字符串 |
转换都要你自己调用,Sprig 不会自动转换。
回调和变长参数
Java 方法要的是「函数式接口」(只有一个抽象方法的接口:Runnable、Comparator<T>、Consumer<? super T>、Predicate<? super T> 以及 java.util.function 里的其他接口)时,可以直接传 Sprig 的函数值。编译器按通常的类型对照从接口方法推出它要的 fn(...) -> R,并替你生成 Java 适配代码:
import java.util.ArrayList as ArrayList
import java.nio.file.Path as Path
import java.nio.file.Files as Files
import java.lang.String as JString
# A Sprig function value where Java wants a functional interface.
let names = ArrayList[String]()
names.add("grace")
names.add("ada")
names.sort(fn(a: String, b: String) => a.compareTo(b))
names.forEach(fn(name: String) => print(name))
print(names.removeIf(fn(name: String) => name.length() > 3))
# Varargs: the trailing arguments are packed, and zero of them is allowed.
let config = Path.of("etc", "sprig", "config.json")
if config != null:
print(config.getFileName())
print(Files.exists(config))
print(JString.join("/", "a", "b", "c"))ada
grace
true
config.json
false
a/b/c- 参数类型必须完全一致;方法返回
void时,lambda 返回什么都可以。Comparator.compare返回int,所以 lambda 返回Int32(a.compareTo(b)正好是)或者Int都可以;返回Int时会像传给int参数一样做运行时范围检查。 - 接口类型参数里的通配符没关系:实现了
Consumer<String>的 lambda 就是一个Consumer<? super String>。 - 方法自己的类型变量只从普通实参推断,不从 lambda 推断。
names.forEach能用是因为ArrayList[String]定下了E;stream.map(fn(...) => ...)得写成stream.map[String](...),因为只有 lambda 才能说明R是什么,它是方法自己的类型变量。 - 类型里带
throws Error的函数值不能传给 Java,因为 Java 看不到这个子句(SPR-TYPE-CALLABLE-THROWS)。把错误在具名函数里处理掉,再传一个调用它的 lambda。
变长参数(String...)接收末尾的零个或多个实参,编译器把它们打包成数组;如果传的正好是那个类的 Java 数组(不透明值),就原样传过去。固定参数个数的重载优先。Path.of("etc", "sprig")、Files.exists(path)、String.format(...)、String.join(...) 都是这样用的。只有元素是类型变量的变长参数(T...,比如 Arrays.asList)仍然不支持。
先查,再写
写调用代码之前,先用 sprig api 看看 Sprig 是怎么理解这个类的。它会列出每个成员在 Sprig 里的签名,能不能用,不能用的原因是什么。加 --json 时,这些信息在 interopLevel、interopReasonCodes 和 adaptation 等字段里:
sprig api java.time.LocalDate --member parse
sprig api com.example.Client --classpath lib/client.jar --json想继承一个 Java 类、覆盖它的 protected 方法,比如 java.util.Random 的 next?它不在公开成员的列表里,sprig api java.util.Random --member next 会把它列在 protectedMethods 下面。在用 conform C to Random(seed) as parent 声明的类里写一个签名相同的方法就能覆盖它,原来的实现用 parent.next(bits) 调用。
如果要频繁使用某个 Java 类,可以用 sprig wrap 生成一个 Sprig 包装文件。生成的是普通源码,你可以随意修改:
sprig wrap com.example.Client --out src/client.spr --classpath lib/client.jarwrap 写文件之前,会先用同一个 classpath 检查生成的代码。已有的文件默认不会被覆盖,要覆盖得加 --force。完整规则见包装生成器(英文)。
弃用的 Java API
Java 库把某个东西标成 @Deprecated 之后,你的代码哪里用到了它,Sprig 会告诉你。下面这个程序照样能运行:
import java.util.Date as Date
let date = Date(126, 0, 15)
print(date.getYear() + 1900)2026同时,sprig check 和 sprig run 会在标准错误里为每一处使用打印一条警告:
SPR-JVM-DEPRECATED [TYPE] main.spr:3:12: warning: Calling deprecated Java constructor java.util.Date(int, int, int)
hint: The Java library's documentation names the replacement; 'sprig api CLASS --member NAME' shows which overloads are deprecated.
SPR-JVM-DEPRECATED [TYPE] main.spr:4:12: warning: Calling deprecated Java method java.util.Date.getYear()
2 warning(s); run 'sprig explain <code>' for details on a diagnostic code.- 警告的错误码是
SPR-JVM-DEPRECATED,位置后面带着warning:。它不会让命令失败:退出码仍然是 0,--json里它的"severity"是"warning"。 - 这几种情况会有警告:调用弃用的构造器或方法、读写弃用的字段、在
conform到 Java 类或接口的类里覆盖弃用的方法,以及导入弃用的类。 - 消息会写明是哪一个重载,因为
URLDecoder.decode(String)已弃用,而decode(String, String)没有。带(marked for removal)表示库作者打算把它删掉。 sprig api java.util.Date --member getYear会在每个弃用成员后面标出(deprecated: true, forRemoval: false);加--json时对应deprecated和forRemoval两个字段。
Sprig 不会替你选替代品,该换成什么要看这个库自己的文档。
还不支持的
- 数组语法:没有数组字面量、数组类型标注、下标和遍历,数组只能原样传递。
- 通配符语法:带通配符类型的值可以持有和传递,但不能在 Sprig 的声明里写通配符,也不能穿过
? extends往里加元素。像 Brigadier 这样层层嵌套的 builder API 可能仍然需要一个简单的 Java 适配层,见 Fabric 模组。 - 元素是类型变量的变长参数(
T...):没有可以打包的元素类。 - 从返回值或 lambda 推断 Java 泛型:方法的类型参数能由实参唯一确定时会推断(
Collections.sort(names)、List.of(1, 2, 3)、Objects.requireNonNullElse(a, b));只出现在返回值里的,或者只能靠 lambda 确定的,要自己写(Collectors.toList[Int]()、stream.map[String](...))。Java 泛型类型始终要写类型参数,也没有协变和逆变。T extends Comparable<? super T>这样的单个递归边界会按实参检查;交集边界(Collections.max)仍然不支持。 - 没有注解的库:什么都不标的库还是按 Sprig 的保守规则,引用结果一律
T?;只有注解(运行时可见的或从 class 文件读到的)和@NullMarked这类默认声明才会改变它。 - Java 内部的计算:Java 方法里发生的
int溢出,不会触发 Sprig 的数值错误。
完整列表见已知限制(英文)。
