发生了什么
用户租用电池后,App 里有一个「我的电池」页面,列出他名下已经绑定的电池编号,以及每颗电池的剩余电量。用户可以同时绑定多颗电池,所以这个页面经常要一次展示好几颗。电量不在页面本地,要实时向电池服务查:调用方把电池编号批量传过去,换回每颗电池的电量。
正常链路是这样:页面请求用户侧服务,服务查出用户名下已绑定的电池编号,再把这些编号一次性交给电池服务做批量电量查询;电池服务逐颗返回电量,页面按编号对上,把电量显示在每颗电池旁边。
这次的不同在绑定数量。电池服务的批量查询接口对入参条数设了上限,一次最多 5 颗,超过就整批返回查询失败:既不截断成前 5 颗,也不返回部分结果。有位用户名下绑了 6 颗电池,用户侧服务把这 6 个编号一次全部传了过去,电池服务判定整批查询失败。
用户侧服务收到失败后,没有把失败往上抛,而是把结果封装成「这些电池都没有电量」,按正常结果交给前端。前端拿到的是一个正常响应,只是电量字段为空,于是照常渲染,每颗电池的电量位置都是空的。用户看到的是电量读不出来,而不是一个报错。影响是这个页面对这类用户不可用:他没法从页面上判断名下任何一颗电池还剩多少电。
本质
一句话:一次批量查询因为条数超过上限而整批失败,上层又把失败改写成「没有电量」的正常结果,所以一个错误的入参条件最终表现成了一张空页面。
- 「我的电池」页面自己不存电量。用户侧服务查到的只是绑定关系,也就是用户名下有哪些电池编号,真正的电量每次都要向电池服务现查。
- 用户侧服务把这些编号全部交给电池服务,走的是批量查询接口。该接口有条数上限,一次最多 5 颗,而且上限是对整批生效的:只要多出一颗,整批请求就作废。
- 这位用户绑了 6 颗,正好越过上限。电池服务返回的是「这次查询失败」,不是「第 6 颗查不到」,前 5 颗的电量也一并没取到。
- 用户侧服务收到失败后走了兜底分支:把结果包装成每颗电池都没有电量,再当作成功返回。这一步把「查询没做成」和「电池本来就没有电量数据」写成了同一种返回,前端无法区分。
- 前端按正常响应渲染,电量字段为空就显示为空。用户既看不到错误提示,也无从知道要少绑一颗才能正常查看。
- 漏掉的校验有两处:绑定环节没有提示或拦住超过上限的数量;调用批量接口前也没有按上限分批。上限是下游定的,越限的入参是上游拼的,失败又是在上游被抹平的——两头都不拦,页面就只能给出一片空白。
修复方向是:产品在绑定环节明确提示最大可绑定数量,前端和后端用同一个上限做校验;调用批量查询时按上限分批,单批失败只降级这一批并留下告警,不再把整批失败当成「没有电量」。修复上线状态未确认。
错误代码
// 用户侧服务:查绑定关系并批量取电量(脱敏教学示例)
public List<BatteryView> loadMyBatteries(long userId) {
List<String> codes = bindingRepo.listBoundCodes(userId); // 6 个编号
// 为什么错:条数由用户绑定数量决定,这里没有按批量接口
// 的上限分批,6 颗一次全传,整批请求必然被下游拒绝
BatchPowerResp resp = batteryClient.batchQueryPower(codes);
if (!resp.isSuccess()) {
// 为什么错:整批失败被降级成“每颗电池都没有电量”,
// 前端收到的是成功响应,只看到电量空白,不会提示重试
return codes.stream()
.map(code -> new BatteryView(code, null))
.collect(Collectors.toList());
}
return resp.toViews();
}
修复代码示例
private static final int MAX_BATCH = 5; // 与电池服务的批量上限保持一致
public List<BatteryView> loadMyBatteries(long userId) {
List<String> codes = bindingRepo.listBoundCodes(userId);
List<BatteryView> views = new ArrayList<>();
// 修复:按上限分批,6 颗拆成 5 + 1,两批各自成败
for (int i = 0; i < codes.size(); i += MAX_BATCH) {
List<String> part = codes.subList(i, Math.min(i + MAX_BATCH, codes.size()));
BatchPowerResp resp = batteryClient.batchQueryPower(part);
if (!resp.isSuccess()) {
// 修复:只降级这一批,并打点告警,让失败可见
log.warn("batch power query failed, batchSize={}", part.size());
metric.counter("power_batch_failed").increment();
views.addAll(BatteryView.emptyOf(part));
continue;
}
views.addAll(resp.toViews());
}
return views;
}
下次遇到这些场景要警惕
- 要调用一个带数量上限的批量接口时:先问清上限是多少、越限是整批失败还是返回部分结果;用上限条数、上限加一条各调一次,观察返回结构是否从「部分缺失」直接变成「整批失败」。
- 给「列表加明细属性」的页面写兜底时:构造下游返回失败,看前端收到的是错误还是成功加空字段。兜底只能降级到「该项暂无数据」,并同时留下告警,否则失败永远藏在空白里。
- 上限这类约束只在一个端校验时:绕过界面直接调接口提交上限加一条,确认后端也会拒绝;再核对前端提示的数字和后端判断的数字是同一个,别一边 6 颗一边 5 颗。
- 只看到「电量、价格、状态为空」的现象时:先怀疑那次批量查询是否整批失败,去下游日志里找这次调用的入参条数和失败返回,而不是先去查单条数据是否正确。