mirai/docs/MigrationFrom1x.md

Mirai - Migration From 1.x

本文介绍如何从 1.x 升级到 2.x。

根据你的语言选择：Kotlin | Java

使用 Kotlin

如何自动完成 Kotlin 的错误替换

仅 IntelliJ IDEA 和 Android Studio 支持这个功能。

把光标放在一个错误中间（或者按 F2 自动跳转到错误），在 Windows 使用 Alt + Enter 快捷键，macOS 使用 Option + Enter，会得到弹窗如下图。

第一项为仅替换这一个错误，第二项为替换项目中的所有这个错误。一般推荐选择第二项并回车即可。

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。

至此你已经成功升级到了 mirai 2.0。回到 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

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。

至此你已经成功升级到了 mirai 2.0。回到 Mirai 文档索引