AIUI 推出已有一段时间,Rokid 也陆续迭代了多个版本。现在,开发者可以用官方 SDK 的 getProfile() 读取当前用户的昵称,也可以通过 wx.request 向自己的服务端发起网络请求。这两项能力放在一起,就可以让眼镜上的游戏显示玩家昵称、提交分数,并在结算时查榜。 AIUI 更新日志 · Rokid 账号接口
如果你已经做了一个能在眼镜上跑的游戏智能体,大概也想过给它加个排行榜。之前做《萤虫跳跳》时,我也遇到了这个问题。一局结束后,玩家除了想知道自己跳了多少分,也想看看自己在本月排第几。这个功能接起来之后,我发现真正需要考虑的是几个具体场景:昵称暂时取不到怎么办,断网时如何保存新纪录,以及榜单还没回来时,结算页能先显示什么。
这篇就用《萤虫跳跳》做例子,聊聊我怎么用 AIUI 的账号和网络能力,配合 Cloudflare Workers 和 D1,把昵称、本地积分和月榜接到同一个结算流程里。文中标为「项目源码摘录」的代码来自游戏客户端,标为「教学示例」的片段用于说明接入方法。
月榜流程总览
月榜流程总览:结算后,成绩提交和榜单查询并行进行。
1. 先确定榜单里怎么认人
我在页面加载时就开始读昵称,给账号接口留出一局游戏的时间。AIUI 的 open 由宿主提供,调用 createOpenAPI() 后就可以用 api.account.getProfile() 读取资料,昵称字段是 userName。这段教学示例兼容直接返回资料和带 data 的响应。
async function loadDisplayName(showNotice) {
try {
const { createOpenAPI } = await import('open');
const api = await createOpenAPI();
const raw = await api.account.getProfile();
const profile = raw?.data ?? raw;
if (typeof profile?.notification === 'string' && profile.notification) {
showNotice(profile.notification);
}
const name = typeof profile?.userName === 'string' ? profile.userName.trim() : '';
return Array.from(name).slice(0, 24).join('') || '游客';
} catch {
return '游客';
}
}
把 showNotice 接到页面可见的提示文字。《萤虫跳跳》用动态导入兼容缺少 open 的浏览器预览环境。游戏启动时预取昵称,提交前若仍缺少昵称,最多再等待 3 秒,失败后可以用「游客」提交。榜单身份用本地生成且成功回读的随机设备 ID,显示昵称用 userName。重名玩家仍能区分,换设备或清除应用数据会生成新身份。手机号、头像和账号原始 ID 都无需上报。
2. 设计月榜的数据和接口
我先把榜单规则定下来:谁的分数排在前面,什么时候切到下个月,同一个玩家能在榜单里占几行。积分榜的 value 越大越好,计时榜可以设为越小越好。把方向 sort 存在应用配置中。服务端采用固定时区划分月份,D1 用 (app, period, user_id) 定位某个应用中某个玩家当月的最佳成绩。这样换月会自然出现新榜,历史月份仍可查询。
| 接口 | 调用方 | 输入与输出 |
|---|---|---|
POST /v1/apps | 开发者,请求头带 x-admin-key | 传 app、title、sort,返回该应用的 api_key |
POST /v1/scores | 游戏结算与重试 | 传 app、api_key、user_id、name、value,返回保存后的最佳分、名次和是否刷新纪录 |
GET /v1/leaderboard | 结算页 | 传 app 和可选的 limit、period,返回 {period, list} |
GET /v1/rank | 结算页 | 传 app、user_id 和可选的 period,查不到时返回 404 |
教学示例默认按北京时间划分月份。Top 10 按最佳成绩排序,同分按达到最佳成绩的时间排序,再用 ID 固定输出顺序。个人名次只数严格优于自己的记录,所以同分并列。榜单行序和竞赛名次是两种数字,UI 要明确选择哪一种。《萤虫跳跳》的 Top 10 行号由列表位置计算,「我的排名」使用服务端返回值。
3. 选择排行榜的服务端方案
提交、查榜和查个人名次这几个接口确定后,就可以决定把它们跑在哪里。我主要看三件事:每月成本、自己要维护哪些东西、能控制多少。
租一台云服务器,自行部署。 如果熟悉普通 Web 开发,这是最直接的方式。买一台云主机,把 API 和数据库部署上去,再配置域名、HTTPS 和备份。语言、数据库、部署方式和数据都由自己控制,排查问题时也可以直接看日志。代价是云主机有持续费用,系统更新、监控、备份和故障恢复也需要自己负责。
使用 Cloudflare Workers 和 D1。 《萤虫跳跳》采用这条路线。Workers 运行 API,D1 保存应用和月榜成绩。两项服务各有免费额度,用量在额度内时,可以免云主机费用运行小流量榜单。部署需要理解 Worker 入口、D1 绑定、数据库初始化,以及本地和线上环境的区别。还要留意免费额度和资源限制。Workers 定价 · D1 定价
通过灵珠搭建工作流,再用官方 SDK 接入。 这条路线类似扣子(Coze)的平台编排方式。先在灵珠里搭建智能体或工作流,把成绩提交和查询编排成可调用能力,发布为 API 后,再通过 Rokid 官方 SDK 接入 AIUI。它适合已经在灵珠管理智能体的项目,可以复用工作流和平台发布能力。接入时仍要定义输入输出、成绩存储和排序规则,并排查发布权限、鉴权和工作流执行等环节。后续我会专门写一篇,把灵珠工作流搭建、API 发布和 SDK 接入串起来。灵珠平台 · Rokid AIUI 开放服务文档
| 方案 | 优点 | 缺点 | 适合场景 |
|---|---|---|---|
| 云服务器自部署 | 熟悉 Web 开发即可沿用现有技术栈,部署和数据可控 | 有持续的服务器费用,需要自己维护系统、HTTPS 和备份 | 已有服务器,或希望自由选择框架和数据库 |
| Cloudflare Workers + D1 | 免费额度内可低成本运行,无需租云主机 | 需要掌握 Worker、D1 绑定和部署配置,受平台额度约束 | 流量较小、愿意学习 Serverless 部署的独立项目 |
| 灵珠工作流 + 官方 SDK | 可复用平台工作流和发布能力,便于与已有灵珠智能体整合 | 需要熟悉工作流编排、API 发布和 SDK 鉴权,受平台能力约束 | 已在灵珠搭建智能体,希望把排行榜接入同一工作流 |
Cloudflare 实践:建表并绑定 D1
Worker 接收请求,D1 保存应用和成绩。准备一个 Cloudflare 账号和一个已有结算入口的 AIUI 项目。先在 Cloudflare 后台创建一个 D1 数据库,打开数据库的「控制台」(Console),执行下面的 SQL。确认出现 apps 和 scores 两张表。
CREATE TABLE IF NOT EXISTS apps (
app TEXT PRIMARY KEY,
title TEXT NOT NULL,
sort TEXT NOT NULL CHECK (sort IN ('asc', 'desc')),
api_key TEXT NOT NULL
);
CREATE TABLE IF NOT EXISTS scores (
app TEXT NOT NULL REFERENCES apps(app),
period TEXT NOT NULL,
user_id TEXT NOT NULL,
name TEXT NOT NULL,
value REAL NOT NULL CHECK (value >= 0),
updated_at INTEGER NOT NULL,
PRIMARY KEY (app, period, user_id)
);
CREATE INDEX IF NOT EXISTS idx_scores_app_period_value
ON scores (app, period, value);
创建或打开 Worker,在「设置 → 绑定」中点「添加绑定」,选择 D1 数据库。把变量名称填成 DB,在「生产」下拉框选中刚建好的数据库,再点「添加绑定」。保存后,Worker 代码就能通过 env.DB 访问它。
部署最小 GET 读榜路由
我建议先把积分榜的读取链路跑通。在 Worker 编辑器中放入下面的教学片段,并确认 D1 绑定名是 DB。保存后点「部署」,并从 Worker 页面复制部署后的 HTTPS 地址。这段代码按积分从高到低取当月前十名。建表后即可用 app=jump-game 验证空榜,注册应用和写入成绩可以等这条链路通了再接。
export default {
async fetch(request, env) {
const url = new URL(request.url);
if (request.method !== 'GET' || url.pathname !== '/v1/leaderboard') {
return new Response('Not found', { status: 404 });
}
const app = url.searchParams.get('app');
if (!app) return Response.json({ error: '缺少 app' }, { status: 400 });
const parts = new Intl.DateTimeFormat('en', {
timeZone: 'Asia/Shanghai', year: 'numeric', month: '2-digit'
}).formatToParts(new Date());
const part = type => parts.find(p => p.type === type).value;
const period = part('year') + '-' + part('month');
const { results } = await env.DB.prepare(
'SELECT user_id, name, value FROM scores WHERE app = ? AND period = ? ' +
'ORDER BY value DESC, updated_at ASC, user_id ASC LIMIT 10'
).bind(app, period).all();
return Response.json({ period, list: results },
{ headers: { 'Access-Control-Allow-Origin': '*' } });
}
};
在浏览器打开自己的 Worker HTTPS 地址,再拼上 /v1/leaderboard?app=jump-game。返回 HTTP 200 且 list 为 [] 时,说明查询已执行,指定应用在所查月份没有成绩。此时即使尚未注册应用,最小路由也能返回空榜。它只查询 scores 表,HTTP 200 这一关验证的是 Worker 能读 D1。
《萤虫跳跳》线上读榜接口的真实 HTTP 200 回包,JSON 已格式化,域名已隐去。这里显式查询了一个空榜月份。线上接口支持 period 和 limit,上面的最小路由只需传 app,固定查询北京时间当前月的前十名,回包只包含 period 和 list。
4. 把 GET 读榜接到 AIUI 结算页
浏览器能返回榜单后,把下面的 readRankResult() 合入游戏的 Page 对象。第一次接入时,在正式结算入口先用 setData() 显示本局分数,再调用 this.readRankResult()。把 baseUrl 换成刚验证过的 Worker HTTPS 地址,把 app 填成刚才查询用的应用名。文件顶部已有 wx 导入时,沿用原来的导入即可。
// 放在 Page 文件顶部
import wx from 'wx';
const baseUrl = 'https://你的-worker地址.workers.dev';
const app = 'jump-game';
// 放在 Page 对象中
readRankResult() {
this.setData({ boardRows: [], boardMessage: '正在获取排行榜…' });
const showError = () => this.setData({ boardMessage: '暂时无法获取排行榜' });
wx.request({
url: baseUrl + '/v1/leaderboard?app=' + encodeURIComponent(app),
method: 'GET',
responseType: 'text',
dataType: 'json',
success: ({ statusCode, data }) => {
if (statusCode !== 200 || !Array.isArray(data?.list)) return showError();
const boardRows = data.list.map((row, i) => ({
key: row.user_id, position: i + 1, name: row.name, score: row.value
}));
this.setData({ boardRows, boardMessage: boardRows.length ? '' : '暂无排行记录' });
},
fail: showError
});
}
在结算页绑定 boardMessage,并用 ink:for 遍历 boardRows,逐行显示 position、name 和 score。这里的 position 是榜单行号,个人名次在下一节接入。空榜时应看到「暂无排行记录」,有分数时应看到例如「1 测试玩家 320」。如果看到「暂时无法获取排行榜」,先回浏览器检查同一个 URL 能否返回 HTTP 200 和 list 数组。
我在《萤虫跳跳》的 finishGame() 中先保存本机最佳,再用 setData() 切到结算页,随后调用 refreshLeaderboard()。实装用 fetch 上报、可取消的 wx.request 读榜。教学示例先用同一条 GET 验证从 Worker 到结算页的路径。
5. 补上注册、成绩提交和个人名次
结算页能显示空榜后,再按第 2 节的接口约定扩展同一个 Worker,保留刚跑通的 GET 路由。把 Worker 中计算北京时间月份的代码提取成 currentPeriod(),让读榜、提交和个人名次共用。然后在 fetch() 的默认 404 之前,按下面的顺序先分发新增路由。保留原来的读榜逻辑。
// 放在 Worker 的 fetch() 内,紧跟 new URL(request.url)
if (request.method === 'POST' && url.pathname === '/v1/apps')
return registerApp(request, env);
if (request.method === 'POST' && url.pathname === '/v1/scores')
return submitScore(request, env, currentPeriod());
if (request.method === 'GET' && url.pathname === '/v1/rank')
return readRank(url, env, currentPeriod());
// 接原来的 GET /v1/leaderboard 和默认 404
三个处理函数按下面的规则写在同一个 Worker 文件里。
注册应用并配置管理员密钥
在 Worker 的「设置 → 运行时变量和密钥」中点「添加变量」,选择「生产」,勾选「值」右侧的「密钥」。名称填 ADMIN_KEY,值填自己的管理员密钥,保存并部署。实现 POST /v1/apps 时,将请求头 x-admin-key 与 env.ADMIN_KEY 比对。registerApp() 先确认 env.ADMIN_KEY 已配置,缺失或不匹配时返回 401。校验成功后读取 JSON,校验 app、title 和 sort,用 crypto.randomUUID() 生成应用提交 key。用参数化 SQL 执行 INSERT INTO apps (app, title, sort, api_key) VALUES (?, ?, ?, ?)。成功返回 201 和 {app, api_key},应用名已占用时返回 409。接着提交成绩前,先用下文的请求注册一次。AIUI 端使用服务地址、应用名和应用提交 key,管理员密钥留在服务端和开发者的注册请求中。
提交成绩并查询个人名次
submitScore() 读取 JSON,按 app 从 apps 查出提交 key。应用不存在时返回 404,key 不匹配时返回 403。再检查 user_id、name 和 value,其中 value 应为非负有限数字。下面是教学设计示例,展示积分榜如何用一条 SQL 保留最高分。
INSERT INTO scores (app, period, user_id, name, value, updated_at)
VALUES (?, ?, ?, ?, ?, ?)
ON CONFLICT (app, period, user_id) DO UPDATE SET
name = excluded.name,
value = excluded.value,
updated_at = excluded.updated_at
WHERE excluded.value > scores.value;
在 Worker 中用 env.DB.prepare(sql).bind(app, period, user_id, name, value, Date.now()).run() 写入。这个语句也可以在末尾加 RETURNING value,用 .first() 执行。有返回行就表示插入了首条成绩或刷新了纪录,可据此填 is_new_best。写入后用和个人名次接口相同的查询返回保存后的最佳分和名次。重复提交同一分数不会改写达成时间,低分也不会覆盖高分。计时榜可按应用保存的排序方向改用 <,比较符由 Worker 从固定选项中选择。D1 参数绑定
readRank() 从 URL 读取 app 和 user_id,用 SELECT value FROM scores WHERE app = ? AND period = ? AND user_id = ? 查询当月最佳,找不到时返回 404。积分榜再用 SELECT COUNT(*) + 1 AS rank FROM scores WHERE app = ? AND period = ? AND value > ? 算名次,最后一个参数绑定玩家保存后的最佳分,返回 {period, value, rank}。个人名次会统计整个月榜,包含 Top 10 之外的玩家。应用 key 放进客户端后可被提取,适合区分接入应用。需要可信竞技时,成绩应由服务端验证。
用四个请求确认后端跑通
以下是一组教学接口的最短联调示例。四条路由部署完成后,在 API 调试工具里依次发送下面的请求。每条路径前加上自己的 Worker HTTPS 地址,两个 POST 都用 Content-Type: application/json。下面假设应用和玩家都是新建的。回包中的月份以 Worker 实际运行时的北京时间为准。
POST /v1/apps x-admin-key: <管理员 Secret>
{"app":"jump-game","title":"跳台游戏","sort":"desc"}
→ 201 {"app":"jump-game","api_key":"APP_KEY"}
POST /v1/scores
{"app":"jump-game","api_key":"APP_KEY","user_id":"u_demo","name":"测试玩家","value":320}
→ 200 {"period":"2026-11","value":320,"rank":1,"is_new_best":true}
GET /v1/leaderboard?app=jump-game
→ 200 {"period":"2026-11","list":[{"user_id":"u_demo","name":"测试玩家","value":320}]}
GET /v1/rank?app=jump-game&user_id=u_demo
→ 200 {"period":"2026-11","value":320,"rank":1}
把注册响应中的真实应用 key 填进提交请求,再把提交分数改成 200 重发。教学接口应返回 value: 320 和 is_new_best: false,榜单仍是 320。正式客户端只需要服务地址、应用标识和应用 key。
在结算页确认第一条成绩和个人名次
用上面的 u_demo 提交 320 分后,重新进入测试结算页,原来的 readRankResult() 应显示「1 测试玩家 320」。为了同时确认个人名次,给结算页绑定一个 myRankText 文本,把下面的方法加到同一个 Page。测试时先传 u_demo,确认后换成游戏提交成绩时用的同一个本机 ID。baseUrl 和 app 沿用第 4 节在文件顶部定义的常量。
// 放在 Page 对象中。复用文件顶部的 wx 导入。
readMyRank(userId) {
const query = '?app=' + encodeURIComponent(app)
+ '&user_id=' + encodeURIComponent(userId);
this.setData({ myRankText: '' });
wx.request({
url: baseUrl + '/v1/rank' + query,
method: 'GET',
dataType: 'json',
success: ({ statusCode, data }) => {
if (statusCode === 200 && Number.isInteger(data?.rank)) {
this.setData({ myRankText: '我的排名 #' + data.rank });
} else if (statusCode === 404) {
this.setData({ myRankText: '本月尚未上榜' });
} else {
this.setData({ myRankText: '暂时无法获取个人名次' });
}
},
fail: () => this.setData({ myRankText: '暂时无法获取个人名次' })
});
}
联调时,在结算入口调用 this.readRankResult() 和 this.readMyRank('u_demo'),应同时看到榜单里的 320 分和「我的排名 #1」。如果榜单有 320 分但显示「本月尚未上榜」,先检查提交和查名次用的是不是同一应用、同一个 user_id 以及同一个月。
接入真实对局时,把第二条联调请求里的 value 换成本局分数,name 换成第 1 节取到的昵称,user_id 换成本地保存的设备 ID,用 wx.request 向 baseUrl + "/v1/scores" 发 POST,把 header 中的 Content-Type 设为 application/json,将第二条联调请求的 JSON 作为 data,其中 api_key 填注册响应中的应用提交 key。第一次联调游戏写入时,可以在提交请求的回调里确认 statusCode === 200,再调用 this.readRankResult() 和 this.readMyRank(userId),确认榜单和个人名次都能读到这条成绩。正式接入时,先把待传成绩保存到本地,让提交和读榜并行,再按后两节的处理方式应对断网和迟到回包。
6. 断网补交和迟到回包
我把本月最高分和待传成绩分别记为 best 和 pending。每次结算都交给 ScoreSync.queue() 比较,刷新纪录时把两个字段一起写入本地存储。断网时打出 320,再打出 350,下次只需提交 350。写入后要回读确认,页面才清除内存里的待写记录。这是项目源码摘录。
const state = this.monthlyState();
if (!state.userId) return false;
if (value <= state.best) return true;
const next = { ...state, best: value, pending: value };
this.storage.set(MONTHLY, next);
const saved = this.storage.get(MONTHLY);
return !!saved && saved.period === next.period && saved.userId === next.userId
&& saved.best === value && saved.pending === value;
客户端用设备本地月份划分待传记录。取出待传分数时,月份和设备 ID 都要与当前状态一致。第 8 节会用跨月联调区分本地队列的归月与服务端的归月。
320 分在途时,游戏仍能保存后来打出的 410 分。flush() 复用同一个在途请求。旧回包成功后,flushOnce() 重新读本地数据,发现 410 仍待提交,就只确认 320。这是项目源码摘录。
const result = await this.lb.submit({ score, nickname });
if (!result) return false;
this.revision += 1;
const latest = this.monthlyState();
if (latest.period !== state.period || latest.userId !== state.userId) return true;
this.storage.set(MONTHLY, { ...latest,
synced: Math.max(latest.synced, score),
pending: validScore(latest.pending) && latest.pending > score ? latest.pending : null
});
图 1 成功回包确认已发出的分数,更高的待传分数留给下一轮。
7. 独立读取 Top 10 和个人名次
《萤虫跳跳》v1.0.3 真机演示的结算页。右侧为旧版演示数据,用于展示榜单布局与「(我)」标记。
在眼镜上,结算页最先要告诉玩家的是这一局得了多少分。我先显示本局得分、个人最佳和已有的榜单缓存,再分别发起上报、Top 10 和个人名次请求。下面是结算页的项目源码摘录。Promise.all 跟踪两条读请求何时收尾,两条回调分别更新界面。
this.syncBest().catch(() => {});
// …合并重复读取,记录当前请求编号和月份
let rank = null, itemsLoaded = false;
const flight = Promise.all([
this.lb.fetchTop(Config.LEADERBOARD_LIMIT).catch(() => null).then((items) => {
if (!current()) return;
// …处理 items === null 的失败分支,此处接成功路径
itemsLoaded = true;
this.boardCache = { items, rank, period: this.lb.topPeriod || period,
userId: this.lb.getUserId(), fetchedAt: Date.now() };
this.saveBoardCache();
this.boardStale = false;
this.boardRetryAfter = 0;
this.renderBoardCache();
}),
this.lb.fetchMyRank().catch(() => null).then((mine) => {
if (!current()) return;
rank = mine && mine.rank ? mine.rank : null;
if (itemsLoaded && rank) {
this.boardCache.rank = rank;
this.saveBoardCache();
this.setData({ myRankText: '我的排名 #' + rank });
}
})
]).finally(() => {
if (this.boardFlight === flight) this.boardFlight = null;
if (current() && (this.scoreSync.revision || 0) !== revision) this.refreshLeaderboard();
});
图 2 同一轮读取中两种回包顺序,以及读请求收尾时因同步版本变化触发的补读。
个人名次先返回时,暂存在本轮读取的局部变量中,Top 10 成功后一起显示。Top 10 先返回就马上渲染。若本轮 Top 10 失败,则本轮个人名次不会单独写进界面。榜单成功返回空数组时显示「暂无排行记录」,网络失败时可以展示带原月份的「上次榜单」。
项目使用可取消的 wx.request 读榜,最多等 30 秒。离开结算页时取消在途读取,回调还要核对前台状态、请求编号和月份。读请求收尾时,若上报已成功且 revision 变化,就再触发一轮读榜。若上报更晚成功,下次触发读榜时再刷新。
8. 联调时,我怎么排查分数和名次
首条成绩能在结算页查到以后,我会故意交换几次回包顺序。排查时把 API 返回的月份和分数、本地待传记录、结算页显示放在一起看。同样是「打了 410 分,榜单还是 320 分」,原因可能是 410 分还在等补交,也可能是服务端已经写入,页面仍显示上一次读取的结果。
下面的例子来自本地联调。我用 Node 加载项目的 ScoreSync 和结算页脚本,通过请求桩控制回包,通过可控时钟推进重试,再观察存储和 setData() 写入的字段。
320 分已经回来了,410 分为什么还在等?
我先模拟断网结算 320 分,恢复网络后暂缓这笔提交的回包,再触发一次 410 分结算。此时两次同步调用复用同一个在途请求。放行回包后,synced 更新为 320,best 和 pending 都保留 410。排查旧回包时,最值得看的就是这一刻。如果 pending 被清空,先检查回包处理是否重读了本地记录,并用本次实际发出的 320 分与它比较。
410 分何时发出,取决于下一次同步由谁触发。我让两条读请求先收尾,再放行 320 分的回包。页面保持前台时,虚拟时钟走到 30 秒,410 分才发出。交换顺序,让 320 分先返回,仍有效的读榜在收尾时就能发现 revision 变化,触发刷新并提前提交 410 分。410 分提交成功后,synced 变为 410,pending 清为 null。这时如果结算页还显示 320 分,我会用同一个应用和月份查 API。服务端也只有 320 分,就查写入和归月。服务端已有 410 分,就查页面何时再次读榜。
名次已经查到了,为什么页面没显示?
我让个人名次先返回第 7 名,暂时挂起 Top 10。此时 myRankText 仍为空。放行 Top 10 后,榜单和「我的排名 #7」一起写到界面。再让 Top 10 失败一次,本轮名次依然没有写入界面。如果页面有旧缓存,看到的名次可能来自上一次读榜。遇到这类问题,我会先对照榜单标题和本轮 Top 10 的结果,再看名次请求是否出错。
换月后,旧回包还能改什么?
我把设备月份从 11 月切到 12 月,让上月的 320 分提交和读榜请求继续等待。12 月写入新的 50 分后,再放行旧回包。结算页没有采用旧榜单或旧名次,本月仍是 pending=50、synced=0。下一次刷新提交的是 50 分,本机历史最佳 1000 分也仍然可读。
复现跨月问题时,我会同时记录设备月份和 Top 10 回包里的 period。设备月份决定本地队列采用哪条记录,两条读榜请求省略了 period,查询月份由服务端决定。如果读榜失败后显示缓存,标题会保留缓存原来的月份。客户端的回包检查能保护新月份的页面与待传记录,服务端已经接收的写入仍按服务端的归月规则处理。
结语
如果你的 AIUI 游戏已经能算出本局分数,可以把这篇文章当作一份接入路线。每一步都能回到正文找到对应的代码、接口或验收方法。
- 定好玩家身份和月榜规则(第 1–2 节)。 用
getProfile()取展示昵称,用本地保存的设备 ID 作为接口里的user_id。确定按哪个时区划分月份、分数怎么排,以及何时更新当月最佳成绩。 - 先在结算页显示空榜(第 3–4 节)。 选定服务端方案后,先实现
GET /v1/leaderboard。按文中的 Cloudflare 示例,可以先建表、绑定 D1,再部署最小读榜路由。浏览器看到 HTTP 200 和list: []后,用wx.request查询同一地址,通过setData()在结算页显示「暂无排行记录」。 - 提交首条成绩并查到个人名次(第 5 节)。 用
POST /v1/apps注册应用,把返回的应用提交 key(api_key)填进POST /v1/scores。再查榜单和GET /v1/rank,个人名次查询沿用提交时的user_id。用正文的u_demo示例联调时,结算页应同时显示 320 分和「我的排名 #1」。 - 接入每局结算,验证异常情况(第 6–8 节)。 结算时立即显示本局得分和本地最佳,把本月新纪录保存为待传成绩,再并行处理提交和读榜。按第 8 节的案例检查本月待传高分能否补交、个人名次何时显示,以及切换月份后旧回包是否会改动新状态。
用云服务器、Cloudflare 或平台发布 API,都可以沿用这套接入顺序。做完之后,从玩家视角走一遍就能判断是否接好:结束一局,马上看见本局得分;新的月度纪录保存并同步后,再从榜单上看到自己的名次。