mirai/docs/MigrationFrom1x.md
2021-01-13 17:19:05 +08:00

117 lines
4.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Mirai - Migration From 1.x
本文介绍如何从 1.x 升级到 2.x。
根据你的语言选择:[Kotlin](#使用-kotlin) | [Java](#使用-java)
## 使用 Kotlin
### 如何自动完成 Kotlin 的错误替换
仅 IntelliJ IDEA 和 Android Studio 支持这个功能。
把光标放在一个错误中间(或者按 F2 自动跳转到错误),使用 `Alt + Enter` 快捷键,会得到弹窗如下图。
![YBP47V_Z640J_YU5WZ_JVPW.png](https://i.loli.net/2020/12/18/CiX9qApu5BnVPch.png)
第一项为仅替换这一个错误,第二项为替换项目中的所有这个错误。一般推荐选择第二项并回车即可。
**Mirai 的修改都尽可能地提供了这样的替换,请依次按如下步骤更新以下几个版本,才能使用这些替换。**
部分无法提供自动替换的修改会在下文说明。
### `1.x` -> `2.0-M1-1`
替换依赖(可以直接全局搜索替换):
- `net.mamoe:mirai-core` -> `net.mamoe:mirai-core-api`
- `net.mamoe:mirai-core-qqandroid` -> `net.mamoe:mirai-core`
**Kotlin**:
1.`MessageChain[Image]` 等 IDE 会提示错误的调用调整为:
- `.findIsInstance<Image>()` `Image` 不存在时返回 `null`
- `.firstIsInstance<Image>()` `Image` 不存在时抛出异常)
**提示**: 如果你是想获取消息的内容,可以使用 `messageChain.content` 扩展,而不需要使用 `MessageChain[PlainText]`
2. `Bot.getFriend` 等函数以前在找不到好友时会抛出异常,现在它们会返回 `null`
请替换 `Bot.getFriend``Bot.getFriendOrFail`
只要能通过编译就可以适配下一个版本。
### `2.0-M1` -> `2.0-M2`
修改都可以自动替换完成。**但请不要跳过 `2.0-M2` 这一步骤。**
### `2.0-M2` -> `2.0-RC`
1. 戳一戳事件由以前的多个事件变为了统一的单个 `NudgeEvent`。若有使用请直接参考 `NudgeEvent` 源码修改。
2. `Listener.ConcurrencyKind``Listener.EventPriority` 由嵌套类移动到顶层,请执行全局替换:
- `Listener.ConcurrencyKind` -> `ConcurrencyKind`
- `Listener.EventPriority` -> `EventPriority`
3. `IMirai` 低级 API 函数名现在不再带有 `_lowLevel` 前缀, 直接删除前缀即可。
其他修改都可以自动替换完成。
### `2.0-RC` -> `2.0.0`
本文编写时 `2.0.0` 还未发布。如果你阅读时已经发布了,请更新到 `2.0.0`。不需要额外迁移。
至此你已经成功升级到了 mirai 2.0。[回到 Mirai 文档索引](README.md#jvm-平台-mirai-开发)
## 使用 Java
**请依次按如下步骤更新以下几个版本**
### `1.x` -> `2.0-M1`
- 消息事件包名有调整, 请根据 IDE 提示自动导入引用失效的包.
- Bot 构造方法调整, 将原 `BotFactoryKt.newBot(...)` 替换为 `BotFactory.INSTANCE.newBot(...)`
- 如果有调用 `Utils.getDefaultLogger().invoke(...)`,替换为 `MiraiLogger.create(...)`
- `Bot.getFriend` 等方法以前在找不到好友时会抛出异常,现在它们会返回 `null`
请替换为 `Bot.getFriendOrFail`
### `2.0-M1` -> `2.0-M2`
图片和语音上传的 API 有更改。
新增了资源 API可以统一缓存文件。
```
ExternalResource.create(file);
ExternalResource.create(inputStream);
```
上传一个资源为图片或语音:
```
contact.uploadImage(resource);
contact.uploadVoice(resource);
```
或者使用工具方法直接发送一个 `File``InputStream` 为图片:
```
Contact.sendImage(contact, inputStream); // 返回 MessageReceipt
Contact.sendImage(contact, file); // 返回 MessageReceipt
Contact.uploadImage(contact, inputStream); // 返回 Image 消息
Contact.uploadImage(contact, file); // 返回 Image 消息
```
### `2.0-M2` -> `2.0-RC` (`2.0.0`)
本文编写时 `2.0.0` 还未发布。如果你阅读时已经发布了,请更新到 `2.0.0` 而不需要更新到 `2.0-RC`
1. 戳一戳事件由以前的多个事件变为了统一的单个 `NudgeEvent`。若有使用请直接参考 `NudgeEvent` 源码修改。
2. `Listener.ConcurrencyKind``Listener.EventPriority` 由嵌套类移动到顶层,请执行全局替换:
- `Listener.ConcurrencyKind` -> `ConcurrencyKind`
- `Listener.EventPriority` -> `EventPriority`
3. `IMirai` 低级 API 方法名现在不再带有 `_lowLevel` 前缀, 直接删除前缀即可。
至此你已经成功升级到了 mirai 2.0。[回到 Mirai 文档索引](README.md#jvm-平台-mirai-开发)