mirror of
https://github.com/mamoe/mirai.git
synced 2025-01-09 09:50:16 +08:00
Update docs
This commit is contained in:
Him188
parent
9a86db09a8
commit
ec03f8322d
71
README.md
71
README.md
@ -15,65 +15,32 @@ Mirai 是一个在全平台下运行，提供 QQ 协议支持的高效率机器
|
||||
|
||||
# mirai-console
|
||||
|
||||
高效率插件支持 QQ 机器人框架, 机器人核心来自 [mirai](https://github.com/mamoe/mirai)
|
||||
高效率 QQ 机器人框架，机器人核心来自 [mirai](https://github.com/mamoe/mirai)
|
||||
|
||||
## 模块说明
|
||||
|
||||
[](https://gitter.im/mamoe/mirai?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
|
||||
|
||||
console 由后端和前端一起工作. 使用时必须选择一个前端.
|
||||
## 开发
|
||||
|
||||
- `mirai-console`: console 的后端, 包含插件管理, 指令系统, 配置系统.
|
||||
- **[准备工作 - 环境和前置知识](docs/Preparations.md)**
|
||||
- **[配置项目](docs/ConfiguringProjects.md)**
|
||||
- **[启动 Console](docs/Run.md)**
|
||||
|
||||
### 后端插件开发基础
|
||||
|
||||
- 插件 - [Plugin 模块](docs/Plugins.md)
|
||||
- 指令 - [Command 模块](docs/Commands.md)
|
||||
- 存储 - [PluginData 模块](docs/PluginData.md)
|
||||
- 权限 - [Permission 模块](docs/Permissions.md)
|
||||
|
||||
|
||||
|
||||
前端:
|
||||
|
||||
- `mirai-console-terminal`: console 的 Unix 终端界面前端.
|
||||
- `mirai-console-graphical`: console 的 JavaFX 图形化界面前端. (开发中)
|
||||
|
||||
**注意：`mirai-console` 1.0-RC 发布之前, 前端请使用 `mirai-console-pure` 而不是 `mirai-console-terminal`**
|
||||
|
||||
**注意：`mirai-console` 后端和 terminal 前端正在进行完全的重构, 所有 API 都不具有稳定性**
|
||||
|
||||
### 版本
|
||||
|
||||
[Version]: https://api.bintray.com/packages/him188moe/mirai/mirai-console/images/download.svg?
|
||||
[Bintray Download]: https://bintray.com/him188moe/mirai/mirai-console/
|
||||
|
||||
详见 [版本规范](docs/README.md#版本规范)
|
||||
|
||||
| 版本类型 | 版本号 |
|
||||
|:------:|:------------:|
|
||||
| 稳定 | - |
|
||||
| 预览 | 1.0-M4 |
|
||||
| 开发 | [![Version]][Bintray Download] |
|
||||
|
||||
### 使用
|
||||
|
||||
**查看示例插件**
|
||||
**示例插件**：
|
||||
- [mirai-console-example-plugin (Kotlin DSL)](https://github.com/Him188/mirai-console-example-plugin)
|
||||
- [mirai-console-example-plugin (Groovy DSL)](https://github.com/Karlatemp/mirai-console-example-plugin)
|
||||
|
||||
正在更新中的文档：[参考文档](docs/README.md)
|
||||
### 后端插件开发进阶
|
||||
|
||||
#### Gradle
|
||||
`CORE_VERSION`: [  ](https://bintray.com/him188moe/mirai/mirai-core/)
|
||||
- 扩展 - [Extension 模块和扩展点](docs/Extensions.md)
|
||||
|
||||
|
||||
build.gradle.kts
|
||||
```kotlin
|
||||
repositories {
|
||||
jcenter()
|
||||
}
|
||||
|
||||
dependencies {
|
||||
implementation("net.mamoe:mirai-core:$CORE_VERSION") // mirai-core 的 API
|
||||
implementation("net.mamoe:mirai-console:$CONSOLE_VERSION") // 后端
|
||||
|
||||
testImplementation("net.mamoe:mirai-console-terminal:$CONSOLE_VERSION") // 前端, 用于启动测试
|
||||
}
|
||||
```
|
||||
|
||||
**注意：`mirai-console` 1.0-RC 发布之前, 前端请使用 `mirai-console-pure` 而不是 `mirai-console-terminal`**
|
||||
|
||||
#### Maven
|
||||
同理 Gradle
|
||||
### 实现前端
|
||||
- [FrontEnd](docs/FrontEnd.md)
|
||||
@ -14,8 +14,8 @@ import java.time.Instant
|
||||
|
||||
internal object MiraiConsoleBuildConstants { // auto-filled on build (task :mirai-console:fillBuildConstants)
|
||||
@JvmStatic
|
||||
val buildDate: Instant = Instant.ofEpochSecond(1599934775)
|
||||
val buildDate: Instant = Instant.ofEpochSecond(1600522812)
|
||||
|
||||
@JvmStatic
|
||||
val version: Semver = Semver("1.0-M4", Semver.SemverType.LOOSE)
|
||||
val version: Semver = Semver("1.0-RC-dev-28", Semver.SemverType.LOOSE)
|
||||
}
|
||||
|
||||
@ -54,7 +54,7 @@ internal fun org.gradle.api.Project.`publishing`(configure: org.gradle.api.publi
|
||||
inline fun Project.setupPublishing(
|
||||
artifactId: String,
|
||||
bintrayRepo: String = "mirai",
|
||||
bintrayPkgName: String = "mirai-console",
|
||||
bintrayPkgName: String = artifactId,
|
||||
vcs: String = "https://github.com/mamoe/mirai-console"
|
||||
) {
|
||||
|
||||
|
||||
49
docs/Appendix.md
Normal file
49
docs/Appendix.md
Normal file
@ -0,0 +1,49 @@
|
||||
# Mirai Console - Appendix
|
||||
|
||||
### Mirai Console 演进
|
||||
|
||||
Mirai Console 是不断前进的框架，将来必定会发生 API 弃用和重构。
|
||||
维护者会严谨地推进每一项修改，并提供迁移周期（至少 2 个次版本）。
|
||||
|
||||
#### 版本规范
|
||||
|
||||
Mirai Console 的版本号遵循 [语义化版本 2.0.0](https://semver.org/lang/zh-CN/#spec-item-9) 规范。
|
||||
|
||||
在日常开发中, Mirai Console 会以 `-dev-1`，`-dev-2` 等版本后缀发布开发预览版本。这些版本仅用于兼容性测试等目的，无稳定性保证。
|
||||
|
||||
在大版本开发过程中，Mirai Console 会以 `-M1`, `-M2` 等版本后缀发布里程碑预览版本。代表一系列功能的完成，但还不稳定。
|
||||
这些版本里新增的 API 仍可能还会在下一个 Milestone 版本变化，因此请按需使用。
|
||||
|
||||
在大版本即将发布前，Mirai Console 会以 `-RC` 版本后缀发布最终的预览版本。
|
||||
`RC` 表示新版本 API 已经确定，离稳定版发布只差最后的一些内部优化或 bug 修复。
|
||||
|
||||
#### 版本选择
|
||||
|
||||
**稳定性**：稳定 (`x.y.z`) > 发布预览 (`-RC`) > 里程碑预览 (`-M`) > 开发 (`-dev`)。
|
||||
|
||||
| 目的 | 推荐至少更新到版本 |
|
||||
|:--------------------------:|:--------------:|
|
||||
| 生产环境 | `x.y.z` |
|
||||
| 希望尽早体验稳定新特性的插件作者 | `-RC` |
|
||||
| 无论如何都想体验新特性的插件作者 | `-M` |
|
||||
| 前端实现者, 底层插件作者 | `-M` |
|
||||
| 为 Mirai Console 提交 PR | `-dev` |
|
||||
|
||||
其中，‘底层插件’ 表示提供扩展等的插件。如权限系统，其他语言插件加载器等。
|
||||
|
||||
#### 更新兼容性
|
||||
|
||||
对于 `x.y.z` 版本号:
|
||||
- 当 `z` 增加时，只会有 bug 修复，和必要的新函数添加（为了解决某一个问题），不会有破坏性变化。
|
||||
- 当 `y` 增加时，可能有新 API 的引入，和旧 API 的弃用。但这些弃用会经过一个弃用周期后才被删除（隐藏）。向下兼容得到保证。
|
||||
- 当 `x` 增加时，任何 API 都可能会有变化。无兼容性保证。
|
||||
|
||||
#### 弃用周期
|
||||
|
||||
一个计划被删除的 API，将会在下一个次版本开始经历弃用周期。
|
||||
|
||||
如一个 API 在 `1.1.0` 起被弃用，它首先会是 `WARNING` (使用时会得到一个编译警告）弃用级别。
|
||||
在 `1.2.0` 上升为 `ERROR`（使用时会得到一个编译错误）；
|
||||
在 `1.3.0` 上升为 `HIDDEN`（使用者无法看到这些 API)。
|
||||
|
||||
`HIDDEN` 的 API 仍然会保留在代码中并正常编译，以提供二进制兼容性，直到下一个主版本更新。
|
||||
80
docs/ConfiguringProjects.md
Normal file
80
docs/ConfiguringProjects.md
Normal file
@ -0,0 +1,80 @@
|
||||
# Mirai Console - Configuring Projects
|
||||
|
||||
配置 Mirai Console 项目。
|
||||
|
||||
## 模块说明
|
||||
|
||||
console 由后端和前端一起工作. 使用时必须选择一个前端.
|
||||
|
||||
- `mirai-console`: Mirai Console 后端。
|
||||
|
||||
- `mirai-console-terminal`: 终端前端，适用于 JVM。
|
||||
- [`MiraiAndroid`](https://github.com/mzdluo123/MiraiAndroid): Android 应用前端。
|
||||
|
||||
**注意：`mirai-console` 1.0-RC 发布之前, 前端请使用 `mirai-console-pure` 而不是 `mirai-console-terminal`**
|
||||
|
||||
## 选择版本
|
||||
|
||||
有关各类版本的区别，参考 [版本规范](Appendix.md#版本规范)
|
||||
|
||||
[Version]: https://api.bintray.com/packages/him188moe/mirai/mirai-console/images/download.svg?
|
||||
[Bintray Download]: https://bintray.com/him188moe/mirai/mirai-console/
|
||||
|
||||
| 版本类型 | 版本号 |
|
||||
|:------:|:------------:|
|
||||
| 稳定 | - |
|
||||
| 预览 | 1.0-M4 |
|
||||
| 开发 | [![Version]][Bintray Download] |
|
||||
|
||||
## 配置项目
|
||||
|
||||
### 使用模板项目
|
||||
|
||||
Mirai 鼓励插件开发者将自己的作品开源，并为此提供了模板项目。
|
||||
|
||||
注意，模板项目依赖的 Mirai Console 不一定是最新的。请检查
|
||||
|
||||
1. 访问 [mirai-console-plugin-template](https://github.com/project-mirai/mirai-console-plugin-template)
|
||||
2. 点击绿色按钮 "Use this template"，创建项目
|
||||
3. 克隆项目，检查并修改生成的属性
|
||||
|
||||
### 使用 Gradle 插件配置项目
|
||||
|
||||
`VERSION` 可在
|
||||
|
||||
若使用 `build.gradle.kts`:
|
||||
```kotlin
|
||||
plugins {
|
||||
id("net.mamoe.mirai-console") version "VERSION"
|
||||
}
|
||||
```
|
||||
|
||||
若使用 `build.gradle`:
|
||||
```groovy
|
||||
plugins {
|
||||
id 'net.mamoe.mirai-console' version 'VERSION'
|
||||
}
|
||||
```
|
||||
|
||||
完成。Mirai Console Gradle 插件会为你配置依赖等所有编译环境。
|
||||
|
||||
### 手动配置项目
|
||||
|
||||
添加依赖：
|
||||
`build.gradle.kts`：
|
||||
```kotlin
|
||||
repositories {
|
||||
jcenter()
|
||||
}
|
||||
|
||||
dependencies {
|
||||
compileOnly("net.mamoe:mirai-core:$CORE_VERSION") // mirai-core 的 API
|
||||
compileOnly("net.mamoe:mirai-console:$CONSOLE_VERSION") // 后端
|
||||
|
||||
testImplementation("net.mamoe:mirai-console-terminal:$CONSOLE_VERSION") // 前端, 用于启动测试
|
||||
testImplementation("net.mamoe:mirai-console-terminal:$CONSOLE_VERSION") // 前端, 用于启动测试
|
||||
}
|
||||
```
|
||||
|
||||
之后还需要配置 Kotlin `jvm-default` 编译参数，Kotlin 和 Java 的编译目标等。
|
||||
在打包插件时必须将依赖一并打包进插件 JAR，且排除 `mirai-core`，`mirai-console` 和它们的间接依赖，否则插件不会被加载。
|
||||
2
docs/Contributing.md
Normal file
2
docs/Contributing.md
Normal file
@ -0,0 +1,2 @@
|
||||
# Mirai Console - Contributing
|
||||
|
||||
103
docs/Preparations.md
Normal file
103
docs/Preparations.md
Normal file
@ -0,0 +1,103 @@
|
||||
# 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](https://www.jetbrains.com/idea/) （或 `Android Studio`）。
|
||||
- IDE 需装有 [Kotlin Jvm Blocking Bridge](https://github.com/mamoe/kotlin-jvm-blocking-bridge) 插件 (先启动你的 IDE，再点击 [一键安装](https://plugins.jetbrains.com/embeddable/install/14816))
|
||||
|
||||
若使用 Kotlin，无特别要求。
|
||||
|
||||
## 前置知识
|
||||
|
||||
要学习为 mirai-console 开发原生支持的插件, 需要:
|
||||
|
||||
- 掌握 Java 基础
|
||||
- 至少粗略了解 Kotlin 基础语法（30 分钟）:
|
||||
- [基本类型](https://www.kotlincn.net/docs/reference/basic-types.html)
|
||||
- [类与继承](https://www.kotlincn.net/docs/reference/classes.html)
|
||||
- [属性与字段](https://www.kotlincn.net/docs/reference/properties.html)
|
||||
- [接口](https://www.kotlincn.net/docs/reference/interfaces.html)
|
||||
- [扩展](https://www.kotlincn.net/docs/reference/extensions.html)
|
||||
- [数据类](https://www.kotlincn.net/docs/reference/data-classes.html)
|
||||
- [对象](https://www.kotlincn.net/docs/reference/object-declarations.html)
|
||||
- [密封类](https://www.kotlincn.net/docs/reference/sealed-classes.html)
|
||||
- **[Java 中调用 Kotlin](https://www.kotlincn.net/docs/reference/java-to-kotlin-interop.html)**
|
||||
- 对于 Java 使用者，请阅读：
|
||||
- [Java 用户的使用指南](#kotlin-源码阅读帮助)
|
||||
- [在 Java 使用 Mirai Console 中的 Kotlin `suspend` 函数](#在-java-使用-mirai-console-中的-kotlin-suspend-函数)
|
||||
- 对于 Kotlin 使用者，请熟知 [Kotlin `1.4` 版本带来的新特性](#mirai-console-使用的-kotlin-14-版本的新特性)
|
||||
|
||||
|
||||
### 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 「[协程](https://www.kotlincn.net/docs/reference/coroutines/coroutines-guide.html)」的一部分。
|
||||
|
||||
Kotlin 协程是语言级特性，函数的修饰符 `suspend` 会在编译阶段被处理。
|
||||
|
||||
对于一个挂起函数:
|
||||
```kotlin
|
||||
suspend fun test(): String
|
||||
```
|
||||
|
||||
它会被编译为 `public Object test(Continuation<String> $completion)`。
|
||||
|
||||
这是因为 Kotlin 对所有挂起函数都有这样的内部变化，并在编译时实现了协程的一些特性。
|
||||
|
||||
Java 用户无法调用这样的方法，因为 `Continuation` 的实现很复杂。
|
||||
|
||||
Mamoe 为此开发了 Kotlin 编译器插件 [Kotlin Jvm Blocking Bridge](https://github.com/mamoe/kotlin-jvm-blocking-bridge)，通过 `@JvmBlockingBridge` 注解，在编译期额外生成一个供 Java 使用的方法，让 Java 用户可以使用拥有源码内相同的函数签名的方法。
|
||||
|
||||
要获取详细信息，参考 [Kotlin Jvm Blocking Bridge 编译器插件](https://github.com/mamoe/kotlin-jvm-blocking-bridge/blob/master/README-chs.md#%E7%BC%96%E8%AF%91%E5%99%A8%E6%8F%92%E4%BB%B6)
|
||||
|
||||
### Mirai Console 使用的 Kotlin `1.4` 版本的新特性
|
||||
|
||||
在官方文档的 [语言特性与改进](https://www.kotlincn.net/docs/reference/whatsnew14.html#%E8%AF%AD%E8%A8%80%E7%89%B9%E6%80%A7%E4%B8%8E%E6%94%B9%E8%BF%9B) 基础上，Mirai Console 的一些设计基于 Kotlin 1.4 的更多新特性。
|
||||
|
||||
#### `object` 内的扩展函数的自动引用
|
||||
对于如下定义：
|
||||
```kotlin
|
||||
package org.example
|
||||
object Obj {
|
||||
fun String.foo()
|
||||
}
|
||||
```
|
||||
在 Kotlin `1.3`，要调用 `foo`，必须使用：
|
||||
```kotlin
|
||||
Obj.run {
|
||||
"str".foo()
|
||||
}
|
||||
```
|
||||
因为 IDE 不会自动为 `String.foo` 添加 `import`。
|
||||
|
||||
Kotlin `1.4` 解决了这个问题。在使用 `"str".foo` 时 Kotlin 会自动添加 `org.example.Obj.foo` 的引用。
|
||||
|
||||
Mirai Console 很多单例对象都设计为 `interface + companion object INSTANCE` 的接口与实现模式，需要这样的新特性。例如：
|
||||
```kotlin
|
||||
interface MiraiConsole {
|
||||
companion object INSTANCE : MiraiConsole by MiraiConsoleImpl // MiraiConsoleImpl 是内部实现，不公开
|
||||
}
|
||||
```
|
||||
180
docs/README.md
180
docs/README.md
@ -1,183 +1,3 @@
|
||||
# Mirai Console
|
||||
|
||||
欢迎来到 mirai-console 开发文档!
|
||||
|
||||
## 目录
|
||||
|
||||
- **[准备工作](#准备工作)**
|
||||
- **[启动 Console](Run.md)**
|
||||
|
||||
### 后端插件开发基础
|
||||
|
||||
- 插件 - [Plugin 模块](Plugins.md)
|
||||
- 指令 - [Command 模块](Commands.md)
|
||||
- 存储 - [PluginData 模块](PluginData.md)
|
||||
- 权限 - [Permission 模块](Permissions.md)
|
||||
|
||||
### 后端插件开发进阶
|
||||
|
||||
- 扩展 - [Extension 模块和扩展点](Extensions.md)
|
||||
|
||||
### 实现前端
|
||||
- [FrontEnd](FrontEnd.md)
|
||||
|
||||
[`Plugin`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/Plugin.kt
|
||||
[`Annotations`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/util/Annotations.kt
|
||||
[`PluginData`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/PluginData.kt
|
||||
[`JavaPluginScheduler`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/jvm/JavaPluginScheduler.kt
|
||||
[`JvmPlugin`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/jvm/JvmPlugin.kt
|
||||
[`PluginConfig`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/PluginConfig.kt
|
||||
[`PluginLoader`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/loader/PluginLoader.kt
|
||||
[`ConsoleInput`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/util/ConsoleInput.kt
|
||||
[`PluginDataStorage`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/PluginDataStorage.kt
|
||||
[`Command`]: ../backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/Command.kt
|
||||
|
||||
## 准备工作
|
||||
***如果跳过本节内容，你很可能遇到无法解决的问题。***
|
||||
|
||||
### 环境要求
|
||||
|
||||
*不接受降低最低版本要求的建议*
|
||||
|
||||
- JDK 11
|
||||
- Android：Android SDK 26+ （Android 8.0)
|
||||
- Kotlin: 1.4
|
||||
|
||||
*Mirai Console 需要的 Kotlin 版本会与 Kotlin 最新稳定版本同步。*
|
||||
|
||||
### 开发插件的准备工作
|
||||
|
||||
- 安装并配置 JDK 11
|
||||
|
||||
若使用 Java，或要修改 Mirai Console：
|
||||
|
||||
- 使用 [IntelliJ IDEA](https://www.jetbrains.com/idea/) （或 `Android Studio`）。
|
||||
- IDE 需装有 [Kotlin Jvm Blocking Bridge](https://github.com/mamoe/kotlin-jvm-blocking-bridge) 插件 (先启动你的 IDE，再点击 [一键安装](https://plugins.jetbrains.com/embeddable/install/14816))
|
||||
|
||||
若使用 Kotlin，无特别要求。
|
||||
|
||||
### 前置知识
|
||||
要学习为 mirai-console 开发原生支持的插件, 需要:
|
||||
|
||||
- 掌握 Java 基础
|
||||
- 至少粗略了解 Kotlin 基础语法（30 分钟）:
|
||||
- [基本类型](https://www.kotlincn.net/docs/reference/basic-types.html)
|
||||
- [类与继承](https://www.kotlincn.net/docs/reference/classes.html)
|
||||
- [属性与字段](https://www.kotlincn.net/docs/reference/properties.html)
|
||||
- [接口](https://www.kotlincn.net/docs/reference/interfaces.html)
|
||||
- [扩展](https://www.kotlincn.net/docs/reference/extensions.html)
|
||||
- [数据类](https://www.kotlincn.net/docs/reference/data-classes.html)
|
||||
- [对象](https://www.kotlincn.net/docs/reference/object-declarations.html)
|
||||
- [密封类](https://www.kotlincn.net/docs/reference/sealed-classes.html)
|
||||
- **[Java 中调用 Kotlin](https://www.kotlincn.net/docs/reference/java-to-kotlin-interop.html)**
|
||||
- 对于 Java 使用者，请阅读 [Java 用户的使用指南](#java-用户的使用指南)，[在 Java 使用 Mirai Console 中的 Kotlin `suspend` 函数](#在-java-使用-mirai-console-中的-kotlin-suspend-函数)
|
||||
- 对于 Kotlin 使用者，请熟知 [Kotlin `1.4` 版本带来的新特性](#mirai-console-使用的-kotlin-14-版本的新特性)
|
||||
|
||||
|
||||
## 附录
|
||||
|
||||
### 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 「[协程](https://www.kotlincn.net/docs/reference/coroutines/coroutines-guide.html)」的一部分。
|
||||
|
||||
Kotlin 协程是语言级特性，函数的修饰符 `suspend` 会在编译阶段被处理。
|
||||
|
||||
对于一个挂起函数:
|
||||
```kotlin
|
||||
suspend fun test(): String
|
||||
```
|
||||
|
||||
它会被编译为 `public Object test(Continuation<String> $completion)`。
|
||||
|
||||
这是因为 Kotlin 对所有挂起函数都有这样的内部变化，并在编译时实现了协程的一些特性。
|
||||
|
||||
Java 用户无法调用这样的方法，因为 `Continuation` 的实现很复杂。
|
||||
|
||||
Mamoe 为此开发了 Kotlin 编译器插件 [Kotlin Jvm Blocking Bridge](https://github.com/mamoe/kotlin-jvm-blocking-bridge)，通过 `@JvmBlockingBridge` 注解，在编译期额外生成一个供 Java 使用的方法，让 Java 用户可以使用拥有源码内相同的函数签名的方法。
|
||||
|
||||
要获取详细信息，参考 [Kotlin Jvm Blocking Bridge 编译器插件](https://github.com/mamoe/kotlin-jvm-blocking-bridge/blob/master/README-chs.md#%E7%BC%96%E8%AF%91%E5%99%A8%E6%8F%92%E4%BB%B6)
|
||||
|
||||
### Mirai Console 使用的 Kotlin `1.4` 版本的新特性
|
||||
|
||||
在官方文档的 [语言特性与改进](https://www.kotlincn.net/docs/reference/whatsnew14.html#%E8%AF%AD%E8%A8%80%E7%89%B9%E6%80%A7%E4%B8%8E%E6%94%B9%E8%BF%9B) 基础上，Mirai Console 的一些设计基于 Kotlin 1.4 的更多新特性。
|
||||
|
||||
#### `object` 内的扩展函数的自动引用
|
||||
对于如下定义：
|
||||
```kotlin
|
||||
package org.example
|
||||
object Obj {
|
||||
fun String.foo()
|
||||
}
|
||||
```
|
||||
在 Kotlin `1.3`，要调用 `foo`，必须使用：
|
||||
```kotlin
|
||||
Obj.run {
|
||||
"str".foo()
|
||||
}
|
||||
```
|
||||
因为 IDE 不会自动为 `String.foo` 添加 `import`。
|
||||
|
||||
Kotlin `1.4` 解决了这个问题。在使用 `"str".foo` 时 Kotlin 会自动添加 `org.example.Obj.foo` 的引用。
|
||||
|
||||
Mirai Console 很多单例对象都设计为 `interface + companion object INSTANCE` 的接口与实现模式，需要这样的新特性。例如：
|
||||
```kotlin
|
||||
interface MiraiConsole {
|
||||
companion object INSTANCE : MiraiConsole by MiraiConsoleImpl // MiraiConsoleImpl 是内部实现，不公开
|
||||
}
|
||||
```
|
||||
|
||||
#### Mirai Console 演进
|
||||
|
||||
Mirai Console 是不断前进的框架，将来必定会发生 API 弃用和重构。
|
||||
维护者会严谨地推进每一项修改，并提供迁移周期（至少 2 个次版本）。
|
||||
|
||||
##### 版本规范
|
||||
|
||||
Mirai Console 的版本号遵循 [语义化版本 2.0.0](https://semver.org/lang/zh-CN/#spec-item-9) 规范。
|
||||
|
||||
在日常开发中, Mirai Console 会以 `-dev-1`，`-dev-2` 等版本后缀发布开发预览版本。这些版本仅用于兼容性测试等目的，无稳定性保证。
|
||||
|
||||
在大版本开发过程中，Mirai Console 会以 `-M1`, `-M2` 等版本后缀发布里程碑预览版本。代表一系列功能的完成，但还不稳定。
|
||||
这些版本里新增的 API 仍可能还会在下一个 Milestone 版本变化，因此请按需使用。
|
||||
|
||||
在大版本即将发布前，Mirai Console 会以 `-RC` 版本后缀发布最终的预览版本。
|
||||
`RC` 表示新版本 API 已经确定，离稳定版发布只差最后的一些内部优化或 bug 修复。
|
||||
|
||||
##### 版本选择
|
||||
|
||||
**稳定性**：稳定 (`x.y.z`) > 发布预览 (`-RC`) > 里程碑预览 (`-M`) > 开发 (`-dev`)。
|
||||
|
||||
| 目的 | 推荐至少更新到版本 |
|
||||
|:--------------------------:|:--------------:|
|
||||
| 生产环境 | `x.y.z` |
|
||||
| 希望尽早体验稳定新特性的插件作者 | `-RC` |
|
||||
| 无论如何都想体验新特性的插件作者 | `-M` |
|
||||
| 前端实现者, 底层插件作者 | `-M` |
|
||||
| 为 Mirai Console 提交 PR | `-dev` |
|
||||
|
||||
其中，‘底层插件’ 表示提供扩展等的插件。如权限系统，其他语言插件加载器等。
|
||||
|
||||
##### 更新兼容性
|
||||
|
||||
对于 `x.y.z` 版本号:
|
||||
- 当 `z` 增加时，只会有 bug 修复，和必要的新函数添加（为了解决某一个问题），不会有破坏性变化。
|
||||
- 当 `y` 增加时，可能有新 API 的引入，和旧 API 的弃用。但这些弃用会经过一个弃用周期后才被删除（隐藏）。向下兼容得到保证。
|
||||
- 当 `x` 增加时，任何 API 都可能会有变化。无兼容性保证。
|
||||
|
||||
##### 弃用周期
|
||||
|
||||
一个计划被删除的 API，将会在下一个次版本开始经历弃用周期。
|
||||
|
||||
如一个 API 在 `1.1.0` 起被弃用，它首先会是 `WARNING` (使用时会得到一个编译警告）弃用级别。
|
||||
在 `1.2.0` 上升为 `ERROR`（使用时会得到一个编译错误）；
|
||||
在 `1.3.0` 上升为 `HIDDEN`（使用者无法看到这些 API)。
|
||||
|
||||
`HIDDEN` 的 API 仍然会保留在代码中并正常编译，以提供二进制兼容性，直到下一个主版本更新。
|
||||
|
||||
@ -2,11 +2,11 @@
|
||||
|
||||
Mirai Console 可以独立启动，也可以被嵌入到某个应用中。
|
||||
|
||||
## 使用第三方工具自动启动
|
||||
## 使用第三方工具自动独立启动
|
||||
|
||||
https://github.com/LXY1226/MiraiOK
|
||||
|
||||
## 独立启动
|
||||
## 手动配置独立启动
|
||||
|
||||
### 环境
|
||||
- JRE 11+ / JDK 11+
|
||||
|
||||
@ -1,2 +1,47 @@
|
||||
# mirai-console-gradle
|
||||
# Mirai Console Gradle Plugin
|
||||
|
||||
Mirai Console Gradle 插件。
|
||||
|
||||
## 使用
|
||||
|
||||
参考 [ConfiguringProjects](../../docs/ConfiguringProjects.md#gradle)[
|
||||
|
||||
## 功能
|
||||
|
||||
- 为 `main` 源集配置 `mirai-core`，`mirai-console` 依赖
|
||||
- 为 `test` 源集配置 `mirai-core-qqandroied`, `mirai-console-terminal` 的依赖 (用于启动测试)
|
||||
- 添加 mirai 依赖仓库链接
|
||||
- 配置插件 JAR 打包构建任务 `buildPlugin` (带依赖)
|
||||
|
||||
|
||||
### `buildPlugin`
|
||||
|
||||
用于打包插件和依赖为可以放入 Mirai Console `plugins` 目录加载的插件 JAR。
|
||||
|
||||
#### 执行 `buildPlugin`
|
||||
```shell script
|
||||
$ gradlew buildPlugin
|
||||
```
|
||||
|
||||
打包结果存放在 `build/mirai/` 目录下。
|
||||
|
||||
## 配置
|
||||
|
||||
若要修改 Mirai Console Gradle 插件的默认配置，在 `build.gradle.kts` 或 `build.gradle` 内，使用 `mirai`：
|
||||
```kotlin
|
||||
mirai { // this: MiraiConsoleExtension
|
||||
// 配置
|
||||
}
|
||||
```
|
||||
|
||||
DSL 详见 [MiraiConsoleExtension](src/main/kotlin/net/mamoe/mirai/console/gradle/MiraiConsoleExtension.kt)。
|
||||
|
||||
#### 排除依赖
|
||||
|
||||
如果要在打包 JAR（`buildPlugin`）时排除一些依赖，请使用如下配置：
|
||||
|
||||
```kotlin
|
||||
mirai {
|
||||
excludeDependency("com.google.code.gson", "gson")
|
||||
}
|
||||
```
|
||||
Loading…
Reference in New Issue
Block a user