发生了什么
商户小程序里有一个消息中心,平台把要通知商户的事情做成站内信放进去,商户打开小程序就能看到。这个页面有两个互相关联的数字:一个是未读数,入口和列表顶部会显示还有多少条没看;另一个是消息列表,商户往下滑,页面继续往后加载剩下的消息,直到全部看完。
正常情况这两个数字应该能对上:未读数说还有一百多条,列表一路往下滑就应该能把这些消息都翻出来,看完一条少一条。这次反馈的现象是,未读数显示 176 条,列表往下滑十几条就滑不动了,再滑也不加载新内容,商户只能看到最前面的一小段,于是认为消息丢了或者没有发全。
这两个数字来自两个不同的接口:未读总数由一个“查未读总数”的接口给出,消息列表由另一个“查消息列表”的接口给出。列表这段调用逻辑来自 2026 年 2 月初的一次改动,它的数据取自承载消息内容的外部服务。外部服务对单次返回条数有上限,最多给 20 条,想取下一页必须把上一页最后一条消息的消息 id 传回去。这次的后端调用从头到尾没有传这个 id,每次拿到的都只是同一段最新消息。产品文档当时也没有把“要翻页”写成明确要求,后端技术方案里就漏掉了这一项。
本质
错误出在“取下一页”这一步:外部服务要求用消息 id 当游标,后端既没有在请求里带上它,也没有在响应里把它交给前端,翻页能力整条链路都没接上。
- 页面加载:前端调用查消息列表接口,请求里没有任何“从哪条之后开始取”的参数。
- 后端转调外部服务:只传商户标识和条数,不传游标。外部服务按缺省行为从最新一条开始,返回最多 20 条。
- 后端组装响应:把这一页消息转成页面要的结构返回,响应里没有“本页最后一条消息 id”,前端不知道下一页从哪里接。
- 前端下滑:前端只能再发一次同样的请求,取回的仍是从最新一条开始的那一段,剩下的消息始终没有出口,列表滑到第一页末尾就停住。
- 未读数:由另一个接口单独统计,没有经过这次被截断的列表调用,所以仍然是完整的 176。一个接口给全量、一个接口只给第一页,页面就出现“还有上百条未读”和“已经滑到底”同时成立。
这里缺的不是“加载更多”按钮,而是外部服务已经支持的游标没有透传出来;接口不报错,只是安静地少给数据,自测时很难发现。
修复方向是给查消息列表接口加上 lastMsgId 入参:首次调用不传,响应里带回本页最后一条消息的 id,前端保存它,下次加载更多时带上,从上次的位置继续往后取。记录写的是按这个方向改造,没有写上线时间和回归结果,这里不声称已经验证过。
错误代码
// 查消息列表:外部服务单次最多返回一页,这里只按条数取(教学示意)
public class MessageQueryService {
private static final int MAX_PAGE_SIZE = 20; // 外部服务单次返回上限
public List<MessageVO> queryList(long merchantId) {
// 为什么错:没有把上一页最后一条消息的 id 传给外部服务,
// 外部服务每次都从最新一条开始返回,永远只能拿到第一页
ExternalMessagePage page = externalClient.fetch(merchantId, MAX_PAGE_SIZE);
// 响应里也没有带回本页最后一条消息 id,前端无法继续往下取
return page.getItems().stream()
.map(MessageVO::of)
.collect(Collectors.toList());
}
}
修复代码示例
// 同一处取数:把上一页最后一条消息 id 当游标传给外部服务,并回传给前端
public class MessageQueryService {
private static final int MAX_PAGE_SIZE = 20;
public MessageListVO queryList(long merchantId, String lastMsgId) {
// 首次调用 lastMsgId 为空,外部服务从最新一条开始
ExternalMessagePage page = externalClient.fetch(merchantId, lastMsgId, MAX_PAGE_SIZE);
List<MessageVO> items = page.getItems().stream()
.map(MessageVO::of)
.collect(Collectors.toList());
MessageListVO vo = new MessageListVO();
vo.setItems(items);
// 修复:把本页最后一条消息 id 交给前端,加载更多时原样带回
vo.setLastMsgId(items.isEmpty() ? lastMsgId : items.get(items.size() - 1).getMsgId());
vo.setHasMore(items.size() == MAX_PAGE_SIZE);
return vo;
}
}
下次遇到这些场景要警惕
- 接一个“单次只给一页”的外部列表接口时:先读它的翻页约定,确认下一页靠页码、时间还是上一页末条 id 取。把游标在入参、透传、响应、前端回传四个环节逐一列出来,缺哪一环都会静默丢数据。
- 产品文档没写翻页时:不要当成“不需要翻页”,而要当成“需要确认”。消息、账单、流水这类只增不减的列表,默认按有翻页设计,先向产品确认单页条数和加载方式再写技术方案。
- 自测这类列表接口时:不要只测第一页。造出超过单页上限的数据,从第一页一路加载到底,核对加载出的总条数与未读数是否一致;第一页正常不代表能翻页。
- 看到“未读数”和“列表条数”对不上时:先确认两个数字分别由哪个接口、按什么口径给出,再判断是统计错了还是列表取数被截断,不要一上来就按“未读数计算错误”排查。