发生了什么
平台里,合伙人有一份“分润城市”清单,清单中的城市是它参与分润的范围;二级商在商户下给用户开通套餐卡。开通免套餐卡时要选择城市,可选项来自该商户对应合伙人的分润城市清单。
正常流程是:二级商发起开通并进入选城市这一步,系统按商户找到对应的合伙人,把分润城市的编号交给区域 SDK,由 SDK 返回这些城市的信息,页面再列出来供选择。分润城市只有几座时,请求落在上限内,这条查询不会失败。
这一次,一位二级商给用户开通免套餐卡,城市列表里查不到任何数据,一个城市都选不了,开通卡在选城市这一步。核实后确认:该商户对应合伙人的分润城市已经超过 20 个,而免套餐的城市查询没有分批,一次性把全部分润城市传给了区域 SDK,超过 SDK 对单次调用城市的数量限制,查询因此失败。城市不超过 20 个时,请求不会触发这条限制。
受影响商户的数量,以及这些商户最终怎样完成开通,没有更多信息。
本质
问题不在城市数据本身,而在调用区域 SDK 时没有按它的单次数量限制拆分请求。
- 免套餐开通页需要城市列表,程序先取该商户对应合伙人的分润城市清单,把城市编号拼成一个请求,一次传给区域 SDK。
- 区域 SDK 内部有校验:单次请求携带的城市数量不能超过 20 个。这是 SDK 的调用约定,不是业务侧可以调整的分页参数。
- 分润城市超过 20 个时,这一次请求带着全部城市编号,直接超过上限,SDK 校验不通过,整次查询没有返回结果。超限影响的是整次查询,不是第 21 个城市被丢掉——前 20 个城市也一起查不出来。
- 页面拿到的是空的城市列表,于是开通页没有可选城市。城市不超过 20 个时,请求落在上限内,不会触发这次失败。
处理方案是:免套餐的城市查询改为按分润城市分批,每批最多 20 个城市,查完再合并结果。这个方案与 SDK 的调用约定一致,城市数量继续增长也不会再次触发上限。问题状态已标记为完成,但是否已用超过 20 个城市的商户验证过、是否已上线,没有更多信息,修复上线状态待确认。
错误代码
public class FreePackageCityService {
/** 开通免套餐时,查询该商户对应合伙人的分润城市,供页面选择 */
public List<CityVO> listSelectableCities(Long merchantId) {
Long partnerId = merchantService.getPartnerId(merchantId);
List<Long> cityGuids = profitCityMapper.listCityGuids(partnerId);
// 为什么错:分润城市有多少就传多少,超过 SDK 单次 20 个的上限后
// SDK 校验不通过,整次查询失败,页面只能拿到空的城市列表
List<CityVO> cities = regionSdk.queryCities(cityGuids);
return cities;
}
}
修复代码示例
public class FreePackageCityService {
private static final int MAX_CITIES_PER_CALL = 20; // 区域 SDK 单次携带城市数的上限
/** 开通免套餐时,查询该商户对应合伙人的分润城市,供页面选择 */
public List<CityVO> listSelectableCities(Long merchantId) {
Long partnerId = merchantService.getPartnerId(merchantId);
List<Long> cityGuids = profitCityMapper.listCityGuids(partnerId);
List<CityVO> result = new ArrayList<>();
// 按上限拆成多批,每批单独调用,再把结果合并
for (int from = 0; from < cityGuids.size(); from += MAX_CITIES_PER_CALL) {
int to = Math.min(from + MAX_CITIES_PER_CALL, cityGuids.size());
List<Long> batch = cityGuids.subList(from, to);
result.addAll(regionSdk.queryCities(batch));
}
return result;
}
}
两段代码是脱敏教学示例,用于解释错误与修复思路,不代表实际项目源码或已上线实现。
下次遇到这些场景要警惕
- 接入第三方 SDK 或批量接口:先拿到单次数量上限的说明,用上限值、上限加一各构造一次调用,观察是返回部分结果、空结果还是直接报错,不能只用正常规模的数据跑通就上线。
- 城市、门店、设备这类随商户规模增长的清单:回归时造一个超过上限的商户,完整走一次开通免套餐,确认页面城市条数与分润城市数量一致,而不是只看接口没有报错。
- 查询结果为空时:区分“确实没有可选城市”和“调用失败被当成空”,失败要抛出异常或告警,不能静默返回空列表,让页面只显示无数据。
- 把单次调用改成多批查询后:核对合并后的总数、有没有重复城市,并确认某一批失败时,已成功批次的结果不会被丢掉或重复提交。