Java友好 ♥
Lambda
simbot 中相比于 simbot3, 对于部分 lambda 的场景进行了简单的优化, 在 Java 中需要手写返回 return Unit.INSTANCE; 的地方大大减少了。
阻塞、异步与响应式
simbot 借助编译器插件 kotlin-suspend-transform-compiler-plugin 为 Java 和其他可能的平台提供阻塞、异步以及响应式风格的 API。项目中启用并配置编译器插件后, 标记 @ST (@SuspendTrans )或 @STP (@SuspendTransProperty )的挂起声明会生成相应桥接方法。 未标记的挂起函数及手写 Java 辅助方法,需要查看各自提供的入口。
例如, 一个 Kotlin 中的挂起函数:
在 Java 中是难以调用的, 因为挂起函数在编译后会经过“编译魔法”而产生一些变化。
如果启用了项目中的插件配置,并给这个挂起函数添加 @ST ,编译器插件会生成可供 Java 使用的桥接 API:
真实命名规则
最常见的 JVM 侧桥接风格可以粗略理解为下面三类:
- Blocking
阻塞调用,通常是
xxxBlocking()。例如:
bot.startBlocking()application.joinBlocking()
- Async
异步调用,通常是
xxxAsync()并返回CompletableFuture。例如:
bot.startAsync()event.replyAsync(...)
也有少数 API 会显式改名,例如
join()在 JVM 上的异步桥接是asFuture():application.asFuture()bot.asFuture()
- Reactive
自
5.0起,桥接方法返回org.reactivestreams.Publisher,通常命名为xxxReactive();属性风格的方法通常为getXxxReactive()。具体名称可通过注解参数调整。@ST各桥接的名称分别配置,例如 Kotlin 的channel(id)即使将 Reserve 方法命名为getChannelReserve(id),默认响应式方法仍是channelReactive(id)。 这类 API 使用ExperimentalReactiveBridgingApi标记,可能在后续版本变更或移除。
对于属性式、getter 风格的挂起 API,桥接命名会进一步偏向 getter。 例如 content()、 guildCount() 这类 API 在 JVM 上更常看到 getContent()、 getGuildCount() 这样的名称。
💡 文档表现
在文档中,可能会同时提供阻塞、异步、响应式三种风格的API。
此时你可以通过文档右上角的切换标签 JavaAPI风格 来修改展示的API风格。
⚠️ 注意异步中的异常处理
当你在使用异步结果时(也包括下文会提到的各响应式类型结果),你需要多一些心眼儿。
以 CompletableFuture 为例,如果不做任何操作, 你很有可能会丢失且无法感知到异常。
例如:
此时,如果 runAsync 内异步任务出现异常,代码中(或者控制台、日志等)实际上不会出现任何信息。 你需要使用明确的API进行异常处理:
下文所述的各种响应式结果通常也可能会有类似的问题,需要多加注意喔。
响应式桥接
借助编译器插件,其生成的 JVM 编译产物包含 Reactive 方法,返回 org.reactivestreams.Publisher, 以直接交给 Reactor 等响应式库处理并使用,挂起函数在订阅后执行。 返回非空值时发布该值,返回 null 时直接完成。依据响应式的特性,订阅所得元素永不为 null。
Kotlin 调用这些实验性桥接方法需要选择加入 ExperimentalReactiveBridgingApi。
顺序组合响应式操作
本文和其他章节中的响应式 Java 示例使用 Reactor,需要添加 io.projectreactor:reactor-core 依赖, 并导入 reactor.core.publisher.Mono 。将 Collectable 转为 Flux 的示例还需要 org.jetbrains.kotlinx:kotlinx-coroutines-reactor 依赖。
例如,在 Gradle Kotlin DSL 中为文档里的响应式示例添加依赖:
通过 Mono.from 接入生成的 Publisher,使用 then 等待前一个操作完成后执行下一个操作:
响应式链需要订阅后才会执行。返回 null 的桥接调用只发送完成信号,后续操作应通过 then 组合。
集成 Spring Boot
simbot 提供 Spring Boot starter 模块,具有对 Spring Boot 的集成能力。 Spring Boot starter 模块也实现了 量子猫 模块, 提供基于注解的高效开发方案。
有关集成SpringBoot的更多信息可以前往 集成SpringBoot。