mirai

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 中当前登录的账号或登录的下一个可用账号. 当环境中存在多个账号时, 可能产生不确定行为, 请保证使用 singeMode 时 Mirai Console 中只有一个账号登录中

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

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

涉及接口如下:

  • /friendList
  • /groupList
  • /memberList

errorMessage, msg 字段归一化

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

对此, 本次重构统一修改为 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, 配置文件有变更

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