From 55688f3193da03248ff7d8aaada10005b012f2a5 Mon Sep 17 00:00:00 2001 From: Him188 Date: Mon, 11 Jan 2021 21:11:33 +0800 Subject: [PATCH] Update docs --- docs/ConfiguringProjects.md | 18 ++- docs/Evolution.md | 2 +- docs/KotlinAndJava.md | 303 ++++++++++++++++++++++++++++++++++++ docs/Preparations.md | 47 ++---- docs/README.md | 61 ++++---- 5 files changed, 367 insertions(+), 64 deletions(-) create mode 100644 docs/KotlinAndJava.md diff --git a/docs/ConfiguringProjects.md b/docs/ConfiguringProjects.md index 1f82eb8c9..614e4acc3 100644 --- a/docs/ConfiguringProjects.md +++ b/docs/ConfiguringProjects.md @@ -1,8 +1,6 @@ # Mirai - Configuring Projects -本文介绍如何在一个项目中使用 mirai。 - -mirai 使用纯 Kotlin 开发，兼容 JVM 平台语言如 Java，最低要求 `JDK 1.8`，`Kotlin 1.4`。 +本文介绍如何在一个 JVM 项目中使用 mirai。 ### 选择版本 @@ -21,7 +19,8 @@ mirai 使用纯 Kotlin 开发，兼容 JVM 平台语言如 Java，最低要求 ` ### 配置项目 -如果你熟悉 Gradle，只需要添加 `jcenter` 仓库和依赖 `net.mamoe:mirai-core:VERSION` 即可而不需要继续阅读。下文将详细解释其他方法。 +- 如果你熟悉 Gradle，只需要添加 `jcenter` 仓库和依赖 `net.mamoe:mirai-core:VERSION` 即可而不需要继续阅读。下文将详细解释其他方法。 +- 如果你熟悉 Maven，只需要添加 `jcenter` 仓库和依赖 `net.mamoe:mirai-core-jvm:VERSION` 即可而不需要继续阅读。下文将详细解释其他方法。 本文提供如下三种配置方法，但推荐使用 Gradle 构建。 @@ -70,6 +69,17 @@ dependencies { } ``` +### 分离 API 和实现（可选） + +mirai 在开发时需要 `net.mamoe:mirai-core-api`, 在运行时需要 `net.mamoe:mirai-core`。可以在开发和编译时只依赖 `mirai-core-api`。 +```kotlin +dependencies { + val miraiVersion = "1.3.3" // 替换为你需要的版本号 + api("net.mamoe", "mirai-core-api", miraiVersion) // 编译代码使用 + runtimeOnly("net.mamoe", "mirai-core", miraiVersion) // 运行时使用 +} +``` + ## B. 使用 Maven diff --git a/docs/Evolution.md b/docs/Evolution.md index 3f5aaaf8a..ed6f55b32 100644 --- a/docs/Evolution.md +++ b/docs/Evolution.md @@ -2,7 +2,7 @@ ### Mirai 演进 -Mirai 是不断前进的库，将来必定会发生 API 弃用和重构。 +Mirai 是不断前进的库，目标是提供稳定且高效的 API。 维护者会严谨地推进每一项修改，并提供迁移周期（至少 2 个次版本）。 ### 版本规范 diff --git a/docs/KotlinAndJava.md b/docs/KotlinAndJava.md new file mode 100644 index 000000000..19f687d33 --- /dev/null +++ b/docs/KotlinAndJava.md @@ -0,0 +1,303 @@ +# Mirai - Kotlin And Java + + +本章介绍部分 Kotlin 定义对应的 Java 定义，以帮助 Java 使用者理解 Mirai 的源代码。 + +每部分第一个代码块为 Kotlin 代码，第二个代码块为 Java 代码。 + +预计阅读时间：5 分钟 + +#### 通用 +- Kotlin 的定义都默认是 `public` 和 `final` +- Kotlin 不需要句末分号，通常以换行作为一个语句的结束 + +#### `class` +```kotlin +class A +``` +```java +public final class A { +} +``` + +#### 构造器定义 + +以下几种 Kotlin 定义是等价的。 + +```kotlin +class A { + private val value: String + + constructor(value: String) { + this.value = value + } + + constructor(integer: Int) { + this.value = integer.toString() + } +} +``` + +```kotlin +class A(val value: String) { // 类定义后面的括号表示主构造器 + constructor(integer: Int) : this(integer.toString()) +} +``` + +对应的 Java 定义为： +```java +public final class A { + private final String value; + + public A(String value) { + this.value = value; + } + + public A(int integer) { + this.value = String.valueOf(integer); + } +} +``` + +通常 Kotlin class 都会有一个主构造器。 + +#### 构造器调用 + +Kotlin 不需要 `new` 关键字。 + +```kotlin +val a = A("test") +``` + +```java +A a = new A("test"); +``` + +#### 函数 +```kotlin +class A { + fun test(string: String): Int = 1 +} +``` + +```java +public final class A { + public int test(String string) { + return 1; + } +} +``` + +#### 属性 `val` +- Kotlin 的 `val` 是不可变的，只能被赋值一次 +- 编译器为 `val` 创建 `getter` + +```kotlin +class A { + val value: String = "test" +} +``` + +```java +public final class A { + private final String value = "test"; + public final String getValue() { + return value; + } +} +``` + +#### 属性 `var` +- Kotlin 的 `var` 相较于 `val` 是可变的，可以被多次赋值。 +- 编译器为 `var` 创建 `getter` 和 `setter` + +```kotlin +class A { + var value: String = "test" +} +``` + +```java +public final class A { + private String value = "test"; + public final String getValue() { + return value; + } + public final String setValue(String value) { + this.value = value; + } +} +``` + +#### 顶层定义和 `const` +- Kotlin 的定义不一定需要在 `class` 中，允许直接存在于文件中的「顶层函数」和「顶层属性」 +- `XXX.kt` 中的顶层定义会被编译为名为 `XXXKt` 的 `class` +- 顶层定义会被编译为 `static` +- `const` 可以修饰一个属性，编译器会把它编译为 Java 静态字段。 + +```kotlin +// Test.kt +val x: String = "xx" + +const val CONST_VALUE: String = "cc" + +fun foo() { } +``` + +```java +// TestKt.java +public final class TestKt { + public static final String CONST_VALUE = "cc"; // const val 没有 getter + + private static final String x = "xx"; + public static String getX(){ + return x; + } + + public static void foo() { } +} +``` + +#### 单例对象 +- Kotlin `object` 定义一个单例对象 + +```kotlin +object Test +``` + +```java +public final class Test { + public static final Test INSTANCE = new Test(); + + private Test() {} +} +``` + +#### 静态 + +```kotlin +object Test { + val x = "x" // public String getX() + @JvmField val y = "y" // public static final String y; + @JvmStatic val z = "z" // public static String getZ() +} +``` + +```java +public final class Test { + public static final Test INSTANCE = new Test(); + private Test() {} + + private final String x = "x"; // val + public String getX() { + return x; + } + + public static final String y = "y"; // @JvmField val + + private final String z = "z"; // @JvmStatic val + public static String getZ() { + return z; + } +} +``` + + +#### 静态 + +- Kotlin 没有 `static` 关键字，但可以通过 `@JvmStatic` 将一个函数编译为 `static` + +```kotlin +object Test { + fun a() { } + @JvmStatic + fun b() { } +} +``` + +```java +public final class Test { + public static final Test INSTANCE = new Test(); + private Test() {} + + public void a() { } + public static void b() { } +} +``` + +#### 伴生对象 + +- `class` 可以拥有 `companion object` +- 伴生对象内的 `@JvmField` 定义将会被编译到外部 `class` +- 伴生对象内的 `@JvmStatic` 函数以成员方法编译到伴生对象，然后以静态方法编译到外部 `class` + +```kotlin +class Test { + companion object { + @JvmField + val CONST: String = "" + + fun a() { } + @JvmStatic + fun b() { } + } +} +``` + +```java +public final class Test { + public static final Companion Companion = new Companion(); + public static final String CONST = ""; + + public static void b() { + Companion.b(); + } + + public static final class Companion { + public void a() { } + public void b() { } + } +} +``` + +#### 协程 + +Kotlin 协程是语言级特性，`suspend` 修饰的函数会在编译期被处理。 + +```kotlin +class A { + suspend fun getValue(): String { /* ... */ } +} +``` + +```java +public final class A { + public Object getValue(Continuation $completion) { + // 由 Kotlin 编译器生成非常复杂的方法体 + } +} +``` + +`$completion` 参数类似于一个回调。需要熟悉 Kotlin 协程原理才能实现。为帮助 Java 用户，mirai 使用编译器插件处理 `suspend` 函数。 + +```kotlin +class A { + @JvmBlockingBridge + suspend fun getValue(): String { /* ... */ } +} +``` + +```java +public final class A { + public Object getValue(Continuation $completion) { + // 由 Kotlin 编译器生成非常复杂的方法体 + } + + // 通过 @JvmBlockingBridge 生成的方法 + public String getValue() { + // 由 @JvmBlockingBridge 的编译器生成方法体，调用 getValue(Continuation) + } +} +``` + +Java 使用者可以认为 `@JvmBlockingBridge suspend fun getValue(): String` 相当于 `fun getValue(): String`。 \ No newline at end of file diff --git a/docs/Preparations.md b/docs/Preparations.md index 4f9f3ea05..1bf488880 100644 --- a/docs/Preparations.md +++ b/docs/Preparations.md @@ -2,13 +2,19 @@ ***此文档假设你是 JVM 平台的开发者。若不是，请参考 [其他语言 SDK](README.md#确定-sdk)*** +本章节介绍 Mirai 的环境和开发要求。预计阅读时间 2 分钟。 + ## JVM 环境要求 - 桌面 JVM：最低 Java 8，但推荐 Java 11（要使用一键启动器，需要 11） - Android：Android SDK 26+ （Android 8.0，Oreo) -**但注意不要使用 Oracle JDK**（[原因](https://github.com/mamoe/mirai/discussions/779)），推荐使用 OpenJDK（可以在 [Red Hat Developer](https://developers.redhat.com/products/openjdk/download) 下载）。 +**但注意不要使用 Oracle JDK**（[原因](https://github.com/mamoe/mirai/discussions/779)），可以使用其他任何 JDK。 + +> 实用链接： +> [AdoptOpenJDK 下载](https://adoptopenjdk.net/) +> 如果你使用 IntelliJ IDEA，可以在 `Project Structure`(`Ctrl+Shift+Alt+S`) -> `SDKs` -> `+` -> `Download JDK` 下载 JDK。 ## 开发的准备工作 @@ -16,39 +22,20 @@ 推荐使用 [IntelliJ IDEA](https://www.jetbrains.com/idea/) 或 [Android Studio](https://developer.android.com/studio)。Mirai 提供一系列 IntelliJ 插件来提升开发体验。 -- [Kotlin Jvm Blocking Bridge](https://github.com/mamoe/kotlin-jvm-blocking-bridge) ([JetBrains 插件仓库](https://plugins.jetbrains.com/plugin/14816-kotlin-jvm-blocking-bridge), [一键安装](https://plugins.jetbrains.com/embeddable/install/14816))：**帮助 Java 用户调用 Kotlin suspend 函数** -- [Mirai Console IntelliJ](https://github.com/mamoe/mirai-console/tree/master/tools/intellij-plugin) ([JetBrains 插件仓库](https://plugins.jetbrains.com/plugin/15094-mirai-console), [一键安装](https://plugins.jetbrains.com/embeddable/install/15094))：提供错误检查等功能 +- [Kotlin Jvm Blocking Bridge](https://github.com/mamoe/kotlin-jvm-blocking-bridge) ([查看 JetBrains 插件仓库](https://plugins.jetbrains.com/plugin/14816-kotlin-jvm-blocking-bridge) / [点击一键安装](https://plugins.jetbrains.com/embeddable/install/14816))：**帮助 Java 用户调用 Kotlin suspend 函数** +- [Mirai Console IntelliJ](https://github.com/mamoe/mirai-console/tree/master/tools/intellij-plugin) ([查看 JetBrains 插件仓库](https://plugins.jetbrains.com/plugin/15094-mirai-console) / [点击一键安装](https://plugins.jetbrains.com/embeddable/install/15094))：提供 mirai-core 的错误检查和 mirai-console 的插件开发辅助 -*如果你不知道这俩是什么，安装就对了。* +如果使用 Kotlin 开发，可以不安装插件。但非常推荐安装 Mirai Console IntelliJ 以获得一些错误检查功能。 + +如果使用 Java 或其他语言，请务必安装 Kotlin Jvm Blocking Bridge，否则会无法使用（[为什么？](KotlinAndJava.md#协程)）。同时请确保 Kotlin 插件是最新版本（在 `Settings -> Plugins` 启用并更新 Kotlin 到最新）。 + +*如果你不知道这俩是什么，都安装就对了。* ## 前置知识 -要能流畅使用 Mirai, 建议学习： +Kotlin 是[让开发人员更快乐的一门现代编程语言](https://www.kotlincn.net/)，由 [IntelliJ IDEA](https://www.jetbrains.com/idea/) 的开发公司 [JetBrains](https://www.jetbrains.com/) 维护，被 Google 推举为 Android 首选编程语言。 -- 掌握 Java 基础 -- 粗略了解 Kotlin 基础语法（15 分钟）: - - [基本类型](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 使用者，请阅读（1 分钟）： - - [在 Java 使用 Kotlin `suspend` 函数](#在-java-使用-kotlin-suspend-函数) +使用 Mirai 是一个不错的学习 Kotlin 机会，使用者可以在 [官方中文文档](https://www.kotlincn.net/docs/reference/) 学习 Kotlin。 -### 在 Java 使用 Kotlin `suspend` 函数 - -`suspend` 函数中文是「挂起函数」，是 Kotlin 「[协程](https://www.kotlincn.net/docs/reference/coroutines/coroutines-guide.html)」的一部分。例如 `public suspend fun foo(): String` 被 `suspend` 修饰，它就是一个挂起函数。 - -对于一个挂起函数: -```kotlin -suspend fun test(): String -``` - -它会被 Kotlin 编译器编译为等同于 Java 的 `public Object test(Continuation $completion)`。`Continuation` 类似一个回调，要实现它需要熟悉 Kotlin 协程实现原理。 - -Mamoe 为此开发了 Kotlin 编译器插件 [Kotlin Jvm Blocking Bridge](https://github.com/mamoe/kotlin-jvm-blocking-bridge)，通过 `@JvmBlockingBridge` 注解，在编译期额外生成一个供 Java 使用的方法，让 Java 用户可以使用拥有源码内相同的函数签名的方法。 \ No newline at end of file +Java 开发者如果只希望使用 Mirai 而不学习 Kotlin，可以阅读 [KotlinAndJava.md](KotlinAndJava.md)（5 分钟）。 \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index ee2589edd..33b9820a0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,13 +8,11 @@ ## 确定 SDK -mirai 官方提供 Kotlin/Java 等 JVM 平台语言开发支持。如果你不熟悉该语言，请使用以下社区提供的 SDK： - -### 基于 [`mirai-console`] +**mirai 官方提供 Kotlin/Java 等 JVM 平台语言开发支持。如果你不熟悉该语言，请使用以下社区提供的 SDK：** [`mirai-console`]: https://github.com/mamoe/mirai-console -这些 SDK 基于 [`mirai-console`]，意味着需要使用 [`mirai-console`] 框架。[`mirai-console`] 也是 mirai 的官方项目之一。 +这些 SDK 基于 [`mirai-console`]。[`mirai-console`] 是 mirai 官方维护的一个*应用程序*。可以在 [这里](https://github.com/mamoe/mirai-console/blob/master/docs/Run.md) 了解如何启动 [`mirai-console`]（也可以稍后在各 SDK 的说明中了解）。 [mamoe/mirai-api-http]: https://github.com/mamoe/mirai-api-http [iTXTech/mirai-native]: https://github.com/iTXTech/mirai-native @@ -32,43 +30,48 @@ mirai 官方提供 Kotlin/Java 等 JVM 平台语言开发支持。如果你不 [theGravityLab/ProjHyperai]: https://github.com/theGravityLab/ProjHyperai [yyuueexxiinngg/cqhttp-mirai]: https://github.com/yyuueexxiinngg/cqhttp-mirai -| 技术 | 维护者及项目地址 | 描述 | -|:----------------|:--------------------------------------------|:-----------------------------------------------------------------------| -| *Http* | [mamoe/mirai-api-http] | Mirai 官方维护的 HTTP API 插件 | -| `JavaScript` | [iTXTech/mirai-js] | 支持使用 `JavaScript` 编写插件并**直接**与 mirai 交互 | -| `Python` | [Graia Framework][GraiaProject/Application] | 基于 `mirai-api-http` 的机器人开发框架 | -| `Node.js` | [RedBeanN/node-mirai] | mirai 的 Node.js SDK | -| `Go` | [Logiase/gomirai] | 基于 mirai-api-http 的 GoLang SDK | -| `Mozilla Rhino` | [StageGuard/mirai-rhinojs-sdk] | 为基于 Rhino(如 Auto.js 等安卓 app 或运行环境)的 JavaScript 提供简单易用的 SDK | -| `C++` | [cyanray/mirai-cpp] | mirai-http-api 的 C++ 封装，方便使用 C++ 开发 mirai-http-api 插件 | -| `C++` | [Chlorie/miraipp] | mirai-http-api 的另一个 C++ 封装，使用现代 C++ 特性，并提供了较完善的说明文档 | -| `C#` | [Executor-Cheng/mirai-CSharp] | 基于 mirai-api-http 的 C# SDK | -| `Rust` | [HoshinoTented/mirai-rs] | mirai-http-api 的 Rust 封装 | -| `TypeScript` | [YunYouJun/mirai-ts] | mirai-api-http 的 TypeScript SDK，附带声明文件，拥有良好的注释和类型提示 | -| `易语言` | [only52607/e-mirai] | mirai-api-http 的 易语言 SDK，使用全中文环境开发插件，适合编程新手使用 | -| `.Net/C#` | [Hyperai][theGravityLab/ProjHyperai] | 从 mirai-api-http 对接到机器人开发框架再到开箱即用的插件式机器人程序一应俱全 | -| *酷 Q 插件* | [iTXTech/mirai-native] | 支持酷 Q 插件在 mirai 上运行 | -| *酷 Q HTTP* | [yyuueexxiinngg/cqhttp-mirai] | 在 mirai-console 开启酷 Q HTTP 服务。 | +| 技术 | 维护者及项目地址 | +|:----------------|:--------------------------------------------| +| *Http* | [mamoe/mirai-api-http] | +| `JavaScript` | [iTXTech/mirai-js] | +| `Python` | [Graia Framework][GraiaProject/Application] | +| `Node.js` | [RedBeanN/node-mirai] | +| `Go` | [Logiase/gomirai] | +| `Mozilla Rhino` | [StageGuard/mirai-rhinojs-sdk] | +| `C++` | [cyanray/mirai-cpp] | +| `C++` | [Chlorie/miraipp] | +| `C#` | [Executor-Cheng/mirai-CSharp] | +| `Rust` | [HoshinoTented/mirai-rs] | +| `TypeScript` | [YunYouJun/mirai-ts] | +| `易语言` | [only52607/e-mirai] | +| `.Net/C#` | [Hyperai][theGravityLab/ProjHyperai] | +| *酷 Q 插件* | [iTXTech/mirai-native] | +| *酷 Q HTTP* | [yyuueexxiinngg/cqhttp-mirai] | > *想在这里添加你的项目？欢迎提交 PR。* -### 基于 `mirai-core` 的 SDK +特别的，有一些 SDK 直接基于 mirai-core 开发，不需要 [`mirai-console`] - `Lua`: [lua-mirai](https://github.com/only52607/lua-mirai) 基于 mirai-core 的 Lua SDK，并提供了 Java 扩展支持，可在 Lua 中调用 Java 代码开发机器人 -## 开发 +## JVM 平台 Mirai 开发 -- [准备工作](Preparations.md#mirai---preparations) +**Mirai 文档没有废话，请务必仔细阅读每一个字。仔细阅读文档花费的 1 分钟可能相当于不阅读文档而自己摸索解决办法的 1 小时。** -### 配置 JVM 项目使用 mirai +1. [准备工作（2 分钟）](Preparations.md#mirai---preparations) -> 可以首先体验让机器人发送消息：在 IDE 克隆 [mirai-hello-world](https://github.com/project-mirai/mirai-hello-world) 并运行其中入口点。 +2. 配置项目 -要把 mirai 作为一个依赖库使用，请参考 [Configuring Projects](ConfiguringProjects.md)。 + - 要把 mirai-core 嵌入一个应用使用，请阅读 [配置项目依赖](ConfiguringProjects.md)。 + - 要为 [`mirai-console`] 框架开发插件，请阅读 [mirai-console 的配置插件项目](https://github.com/mamoe/mirai-console/blob/master/docs/ConfiguringProjects.md)。 -要使用 mirai-console 框架，请前往 [mirai-console](https://github.com/mamoe/mirai-console)。 -### API 文档 +> 如果你不知道 [`mirai-console`] 是什么，请阅读 [Mirai 生态概览](mirai-ecology.md)。 +> +> 如果你希望先确认 mirai 能够正常运行才能安心阅读文档，可克隆 [mirai-hello-world](https://github.com/project-mirai/mirai-hello-world) 并运行其中 Kotlin 或 Java 入口点 `main`。 + + +### mirai-core API 文档 ***本文档正在更新中***