Skip to content

Latest commit

 

History

History
132 lines (88 loc) · 3.99 KB

Migration2.md

File metadata and controls

132 lines (88 loc) · 3.99 KB

Mirai http api 2.x 迁移文档

在线插件更新

为保持旧插件的不会突然升级导致异常,2.x需要使用不同的 channel 进行更新,即 channel stable-v2

./mcl --update-package net.mamoe:mirai-api-http --channel stable-v2 --type plugin

配置文件

拆分为多模块,添加了新的参数

## 配置文件中的值,全为默认值

## 启用的 adapter, 内置有 http, ws, reverse-ws, webhook
adapters:
  - http
  - ws

## 是否开启认证流程, 若为 true 则建立连接时需要验证 verifyKey
## 建议公网连接时开启
enableVerify: true
verifyKey: 1234567890

## 是否开启单 session 模式, 若为 true,则自动创建 session 绑定 console 中登录的 bot
## 开启后,接口中任何 sessionKey 不需要传递参数
## 若 console 中有多个 bot 登录,则行为未定义
## 确保 console 中只有一个 bot 登陆时启用
singleMode: false

## 历史消息的缓存大小
## 同时,也是 http adapter 的消息队列容量
cacheSize: 4096

## adapter 的单独配置,键名与 adapters 项配置相同
adapterSettings:
  ## 详情看 http adapter 使用说明 配置
  http:
    host: localhost
    port: 8080
    cors: [*]
  
  ## 详情看 websocket adapter 使用说明 配置
  ws:
    host: localhost
    port: 8080
    reservedSyncId: -1

http 相关

认证流程

  1. authKey 修改为 verifyKey, 认证接口参数名同步修改
  2. /auth 接口修改为 /verify 接口
  3. /verify 接口修改为 /bind 接口

变更原因: 命名混淆

http 的认证流程为, 第一步先认证(verify)插件使用者身份; 第二步通过 qq 号绑定(bind)到固定的 session 中,是为了提供缓存和消息队列等连接私有的上下文. 原则上并没有鉴权(auth)的过程,因此修改接口名称

认证流程优化

  1. 可通过配置文件中 enableVerify 参数关闭认证过程, 信任所有连接连接的请求. 不建议关闭, 但用户能够保证安全或者调试环境下能有更好的体验

  2. 可通过配置文件中 singleMode 参数跳过绑定(bind)过程,默认使用 Mirai Console 中当前登录的账号或登录的下一个可用账号. 当环境中存在多个账号时, 可能产生不确定行为, 请保证使用 singeModeMirai Console 中只有一个账号登录中

若干未 Restful 包装的接口返回值进行 Restful 封装

{
    "code": 0,
    "msg": "",
    "data": null
}

涉及接口如下:

  • /friendList
  • /groupList
  • /memberList

errorMessage, msg 字段归一化

部分接口的返回值中,使用了 errorMessage 作为属性值, 而部分使用 msg. 此问题出现于 issue#59

对此, 本次重构统一修改为 msg. 涉及接口如下:

消息队列接口
  • /countMessage
  • /fetchMessage
  • /fetchLatestMessage
  • /peakMessage
  • /peekLatestMessage
  • /messageFromId

发送消息、事件处理等返回状态码的接口不受影响

上传相关

根据反映, 图片, 语言, 文件上传不再缓存到本地, 返回值将不再返回 path 参数. 如有本地上传需求, 由用户自行缓存, 以进行资源管理

websocket 相关

返回格式

由于 websocket 追加执行操作的功能,因此 websocket 接收消息的数据结构,需和 websocket 操作响应保持相同格式,以方便解析。具体为

{
    syncId: "",
    data: {}
}

data 内容和原本保持一致(除上文提到的数据变更外)

syncId

syncId 用于操作追踪,可为任意字符串。对于使用 websocket 发送的操作请求,响应数据会携带和请求相同的 syncId,用于同步追踪请求和响应。

对于由 mirai-api-http 主动发送的事件(如event、message等),使用保留字 {syncId: "-1"}, 也可在配置文件中自行定义

上报相关

上报模块现独立为 webhook adapter, 配置文件有变更

同时支持返回值进行简单操作回调