mirai/docs/README.md

MiraiConsole

欢迎来到 mirai-console 开发文档!

准备工作

开发 mirai-console 插件的准备工作

• 需使用 IDE: IntelliJ IDEA
• IntelliJ 需装有 Kotlin Jvm Blocking Bridge 插件 (启动 IntelliJ, 点击 一键安装)
• 安装并配置 JDK 8

前置知识

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

• 掌握 Java 基础.
• 了解 Kotlin 基础语法:
  • 基本类型
  • 类与继承
  • 属性与字段
  • 接口
  • 扩展
  • 数据类
  • 对象
  • 密封类
  • Java 中调用 Kotlin
• 至少能使用 Java 或 Kotlin 一种一门语言解决问题
• 了解 JVM 和 Java 等同类编程语言的关系
• 对于 Kotlin 使用者，请熟知 Kotlin 1.4 版本带来的新特性

目录

后端插件开发基础

• 插件 - Plugin 模块
• 指令 - Command 模块
• 存储 - PluginData 模块
• 权限 - Permission 模块

后端插件开发进阶

• 扩展 - Extension 模块和扩展点
• 扩展 - 实现 PluginLoader
• 扩展 - 实现 PermissionService

实现前端

• FrontEnd

附录

Java 用户的使用指南

• 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 是内部实现，不公开
}