Skip to content

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 类 ​

spr
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())
text
9
4
Sprig!
2026
25
  • import java.lang.Math as Math 让你在这个文件里用 Math 指代这个类。java.lang 下的类也要这样导入,不会自动导入。
  • 构造器、静态方法、实例方法和静态字段都能通过这个名字使用。
  • 有重载时,Sprig 按参数类型挑选。没有匹配的方法会报 SPR-JVM-MEMBER,有好几个同样合适的会报 SPR-JVM-AMBIGUOUS。

Java 返回的值要先判空 ​

Java 方法返回的对象,包括 String 和 Integer 这类装箱类型,都被当作可能为 null,用之前要检查:

spr
import java.lang.System as System

let version = System.getProperty("java.version")
if version != null:
    print(version.length() > 0)
text
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?。

类型对照 ​

JavaSprig(基本类型)Sprig(装箱类型和对象)
longIntInt?
int、short、byteInt32Int32?
doubleFloatFloat?
floatFloat32Float32?
booleanBoolBool?
charStringString?
voidUnit—
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" 不行,"😀" 也不行,因为一个 Java char 装不下它。Sprig 自己的字符串则按 Unicode 码点计算位置,详见 sprig help strings。

捕获 Java 异常 ​

Java 的受检异常可以写进 Sprig 的 throws,也可以用 catch 捕获:

spr
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")
text
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 里的函数:

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())
text
2
3
2
  • list_snapshot 和 map_snapshot 把 Java 集合按顺序复制成只读的 Sprig List 和 Map。之后 Java 那边怎么改,快照都不受影响:上面 names 加了第三个名字,snapshot 还是两个。
  • list_copy 和 map_copy 反过来,把 Sprig 集合复制成独立的 Java ArrayList 和 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 来转换:

spr
import sprig.runtime.jvm.HostBytes as HostBytes

let bytes = HostBytes.utf8("Sprig")
if bytes != null:
    print(HostBytes.length(bytes))
    print(HostBytes.hex(bytes))
text
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 适配代码:

spr
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"))
text
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 等字段里:

bash
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 包装文件。生成的是普通源码,你可以随意修改:

bash
sprig wrap com.example.Client --out src/client.spr --classpath lib/client.jar

wrap 写文件之前,会先用同一个 classpath 检查生成的代码。已有的文件默认不会被覆盖,要覆盖得加 --force。完整规则见包装生成器(英文)。

弃用的 Java API ​

Java 库把某个东西标成 @Deprecated 之后,你的代码哪里用到了它,Sprig 会告诉你。下面这个程序照样能运行:

spr
import java.util.Date as Date

let date = Date(126, 0, 15)
print(date.getYear() + 1900)
text
2026

同时,sprig check 和 sprig run 会在标准错误里为每一处使用打印一条警告:

text
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 的数值错误。

完整列表见已知限制(英文)。

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