v1 迁移至 v2 接口指南

面向已有 v1 对接代码的前端开发者，帮助快速适配 v2 版本。

---

目录

• 1. 整体变化概览
• 2. /list → /v2/list 差异
• 3. /join → /v2/join 差异
• 4. /account → /v2/account 差异
• 5. 新增接口：/refreshFollowers
• 6. 不变接口
• 7. 快速适配清单

---

1. 整体变化概览

维度	v1	v2
房间列表 路径	/list	/v2/list
加入房间 路径	/join	/v2/join
查询平台账户 路径	/account	/v2/account
userxuid 参数	可选	新版中必需
平台账户粉丝、关注管理	无	有（面向前端调用的接口目前只有手动刷新粉丝、关注人员数据）
目前可用账号数	4 个	1 个

---

2. /list → /v2/list 差异

2.1 相同点

• GET 请求 + ?lang= 语言筛选
• 响应顶层结构：{ results: [...] }
• customProperties 的主要字段（hostName, ownerId, version, worldName, worldType, MemberCount, MaxMemberCount, BroadcastSetting, isHardcore, worldNameLang）完全一致
• roomfrom 字段保留

2.2 不同点

目前，/list和/v2/list两个接口返回的数据的结构都是一样的（都有ownerXuid之类的数据），下面的“新增”指API上一次变动到这一次变动新增的数据。若您的前端仍然在使用/list，多出来的数据并不会影响您现有前端的正常运行。

项目	/list本次更新前	/v2/list
对外路径	/list	/v2/list
ownerXuid	❌ 无	✅ 新增
protocol	❌ 无	✅ 新增
isEditorWorld	❌ 无	✅ 新增
RealmId	❌ 无	✅ 新增
relatedInfo	❌ 无	✅ 新增（含Xbox会话中的 maxMembersCount / membersCount）
后端数据刷新	每 20 秒	每 30 秒

2.3 v2 新增字段（完整json数据请前往v2版接口指南）

{
  "results": [{
    "ownerXuid": "1234567890123456", //该handle的发起者（和session发起者是两回事，session发起者就是房主。前端可以无视该数据）
    "customProperties": {
      "protocol": 0, //游戏协议号（游戏通过这个判断是否是相同版本/互通版本，否则直接报游戏版本不对不能加入游戏，前端可忽略也可用于做筛选显示）
      "isEditorWorld": false, //是否是编辑器世界（字面意思。前端可以无视该数据，或者自己做决定加层筛选逻辑，但这么久也没看到过几次这种房间）
      "RealmId": "" //（前端可以无视该数据，只有realm才会有这个，或者自己做决定加层筛选逻辑不显示realm）
    },
    "relatedInfo": {
      "maxMembersCount": 30,//XboxLive会话的人员上限（默认30，好像也改不了。所以通过Xbox网络联机的话，即使游戏里把人数上限调得再高，也只能进来29个人）
      "membersCount": 1 //XboxLive会话中的人员数量（和游戏里实际人数不一定一致，仅做参考）
    }
  }]
}

2.4 迁移要点

• 无需改动：读取 hostName、worldName、worldType 等已有字段的代码
• 需要改动：
  1. 请求 URL：/list → /v2/list
  2. addid 现在可能为 "8"，注意您的前端逻辑是否处理了新的账号 ID，旧版查询平台账号的接口/account不提供ID为"8"的账号，旧版加入房间的接口/join不接受ID为"8"的账号。若暂时无法改动，可先继续使用旧版接口（房间信息中无新账号的数据，不会引发问题）。

---

3. /join → /v2/join 差异

3.1 相同点

• POST 请求
• 旧版 JSON 结构（version: "1.0.0"）仍受支持
• addid、roomfrom、sessionname 含义一致
• roomid（v1）与 handleid（v2）均指向 /list 中的 id 字段，值相同

3.2 不同点

项目	/join	/v2/join
协议版本	仅 version: "1.0.0"	旧版兼容 + 新版 apiversion: 2
邀请控制 invitecontrol	可选（含 userxuid）	新版中由 joininformation.userxuid 替代，不再有邀请功能
userxuid	可选（缺失仍成功）	新版必需（缺失返回 400）
roomid 字段名	roomid	handleid（值相同）

3.3 请求体对比

v1（旧版协议）：

{
  "version": "1.0.0",
  "joininformation": {
    "addid": "6",
    "roomfrom": "6",
    "roomid": "00000000-0000-0000-0000-000000000000",
    "sessionname": "00000000-0000-0000-0000-000000000000"
  },
  "invitecontrol": {
    "userxuid": "2535408433750813"
  }
}

v2 新版（推荐）：

{
  "apiversion": 2,  //version改名apiversion，类型从string改number
  "joininformation": {
    "addid": "6",
    "roomfrom": "6",
    "handleid": "00000000-0000-0000-0000-000000000000", //roomid改名handleid
    "sessionname": "00000000-0000-0000-0000-000000000000",
    "userxuid": "2535408433750813"  //要加入游戏的玩家的xuid，现在是必须项
  }
}

3.4 响应对比

条件	v1 响应	v2 新版响应
成功	code="1"（无xuid）或 "2"（有邀请）	code="1"（统一成功）
参数缺失	400 code=1	400 code=1
addid 类型错误	400 code=2	400 code=2
userxuid 缺失	200 code=1（仍成功）	400 code=3（拒绝）
userxuid 不在 follower	不检查	403 code=4
自动添加关注失败	无此功能	xxx? code=5

3.5 迁移要点

最低成本迁移（不改逻辑，仅改 URL）：

将请求 URL 从 /join 改为 /v2/join，请求体保持 version: "1.0.0" 不变即可兼容运行。 后端会透传 v1 端口，行为与 v1 完全一致（既然完全一致了就还是不支持ID=8的账号）。

推荐迁移（使用新版协议）：

1. 修改请求体：
   • version: "1.0.0" → apiversion: 2 （搜索替换即可）
   • roomid → handleid （搜索替换即可）
   • 将 invitecontrol.userxuid 移到 joininformation.userxuid （现在是必须项）
   • 确保 userxuid 字段存在且为 16 位数字
2. 更新错误处理逻辑：新增 code=3/4/5 的展示文案。
3. /v2/join 强制要求用户的账号在Xbox关注平台账号或者在Minecraft中添加为好友（不能在Xbox发送好友申请），否则在后端无法通过校验。关注后，由于后端刷新粉丝缓存的间隔是300秒，若要立即刷新缓存，请执行GET /refreshFollowers，由于后端设计仍有缺陷，请求后请无视响应代码。

---

4. /account → /v2/account 差异

4.1 相同点

• GET 请求
• 响应为 JSON 数组，每个元素含 id、name、canaddfriends

4.2 不同点

项目	/account	/v2/account
可用账号	4 个	1 个
账号 8	❌ 无	✅ MCLobby26
账号 7 的 canaddfriends	true	无此账号

4.3 迁移要点

• 请求 URL：/account → /v2/account
• 建议以 canaddfriends 字段为准做判断，而非硬编码 id。

---

5. 新增接口：/refreshFollowers

5.1 用途

手动触发后端拉取 Xbox 账号的 followers（粉丝列表），更新本地缓存。

5.2 请求方式

GET https://api.miaaoo.com/refreshFollowers

5.3 响应码速查

由于后端设计仍有缺陷，请求后请无视响应代码。

状态码	含义
200	刷新成功（至少一个账号重新拉取）
206	无需刷新（缓存 10 秒内）
502	某账号拉取失败
500	服务器错误

5.4 全局限流

由于后端设计仍有缺陷，请求后请无视响应代码。 10 秒内全网重复调用直接返回 206，不触发真实 API 调用。

5.5 使用场景

• 用户刚在Xbox APP里关注了平台账号或者在Minecraft里添加了平台账号好友，希望立即在房间列表中看到其房间，或者希望能通过关注校验。
• 调试/测试场景

5.6 注意事项

• 调用该接口房间列表不会立即更新。
• 后端每 5 分钟自动刷新，手动刷新通常非必需

---

---

6. 不变接口

以下接口在 v2 中完全不变，无需任何迁移：

接口	路径	说明
/profile	GET /profile	获取用户资料（xuid 或 gt 查询）
/getxuid	GET /getxuid	Gamertag → XUID 转换
/roominfo	GET /roominfo	获取房间详情和成员列表（支持ID=8的账号）

注意：/getxuid 虽在官方文档标注为即将弃用，但因该接口调用的便利性，现已打算不弃用该接口。

---

7. 快速适配清单

推荐适配（30 分钟）

• [ ] /v2/join 请求体改为新版 apiversion: 2 格式
• [ ] roomid 字段名改为 handleid
• [ ] 将 userxuid 从可选改为必需参数，并从 invitecontrol 移到 joininformation 中
• [ ] 增加 /refreshFollowers 调用逻辑
• [ ] 处理 /v2/join 新增错误码 code=3/4/5 的 UI 展示
• [ ] 利用 /v2/list 新增的数据优化前端体验（可不做，没影响）

---

文档版本：v2.0.0 · 最后更新：2026-06-02