mirai/docs/Preparations.md

Mirai Console - Preparations

如果跳过本节内容，你很可能遇到无法解决的问题。

环境要求

不接受降低最低版本要求的建议

• JDK 11
• Android：Android SDK 26+ （Android 8.0)
• Kotlin: 1.4

Mirai Console 需要的 Kotlin 版本会与 Kotlin 最新稳定版本同步。

开发插件的准备工作

• 安装并配置 JDK 11

若使用 Java，或要修改 Mirai Console：

• 使用 IntelliJ IDEA （或 Android Studio）。
• IDE 需装有 Kotlin Jvm Blocking Bridge 插件 (先启动你的 IDE，再点击 一键安装)

若使用 Kotlin，无特别要求。

前置知识

要学习为 mirai-console 开发原生支持的插件, 需要:

• 掌握 Java 基础
• 至少粗略了解 Kotlin 基础语法（30 分钟）:
  • 基本类型
  • 类与继承
  • 属性与字段
  • 接口
  • 扩展
  • 数据类
  • 对象
  • 密封类
  • Java 中调用 Kotlin
• 对于 Java 使用者，请阅读：
  • Java 用户的使用指南
  • 在 Java 使用 Mirai Console 中的 Kotlin suspend 函数
• 对于 Kotlin 使用者，请熟知 Kotlin 1.4 版本带来的新特性

Kotlin 源码阅读帮助

• Java 中的「方法」在 Kotlin 中均被称为「函数」。
• Kotlin 默认的访问权限是 public。如 Kotlin class Test 相当于 Java 的 public class Test {}
• Kotlin 的函数定义 fun test(int: Int): String 相当于 Java 的方法定义 public String test(int int)

在 Java 使用 Mirai Console 中的 Kotlin suspend 函数

什么是 suspend 函数

suspend 函数中文是「挂起函数」，是 Kotlin 「协程」的一部分。

Kotlin 协程是语言级特性，函数的修饰符 suspend 会在编译阶段被处理。

对于一个挂起函数:

suspend fun test(): String

它会被编译为 public Object test(Continuation<String> $completion)。

这是因为 Kotlin 对所有挂起函数都有这样的内部变化，并在编译时实现了协程的一些特性。

Java 用户无法调用这样的方法，因为 Continuation 的实现很复杂。

Mamoe 为此开发了 Kotlin 编译器插件 Kotlin Jvm Blocking Bridge，通过 @JvmBlockingBridge 注解，在编译期额外生成一个供 Java 使用的方法，让 Java 用户可以使用拥有源码内相同的函数签名的方法。

要获取详细信息，参考 Kotlin Jvm Blocking Bridge 编译器插件

Mirai Console 使用的 Kotlin 1.4 版本的新特性

在官方文档的 语言特性与改进 基础上，Mirai Console 的一些设计基于 Kotlin 1.4 的更多新特性。

object 内的扩展函数的自动引用

对于如下定义：

package org.example
object Obj {
  fun String.foo()
}

在 Kotlin 1.3，要调用 foo，必须使用：

Obj.run {
  "str".foo()
}

因为 IDE 不会自动为 String.foo 添加 import。

Kotlin 1.4 解决了这个问题。在使用 "str".foo 时 Kotlin 会自动添加 org.example.Obj.foo 的引用。

Mirai Console 很多单例对象都设计为 interface + companion object INSTANCE 的接口与实现模式，需要这样的新特性。例如：

interface MiraiConsole {
    companion object INSTANCE : MiraiConsole by MiraiConsoleImpl // MiraiConsoleImpl 是内部实现，不公开
}