发生了什么

换电是把用户车上没电的电池取下来,换一颗满电电池。电柜是放在点位上的设备,里面存着待换的电池;一台电柜在系统里有一条记录,记着编号和经纬度。运维人员在后台打开换电任务地图,按地图上的电柜点位安排运维任务,所以地图上少画一个柜子,就等于这个点位在任务视图里不存在。

地图的数据来自“查某个坐标周边有哪些电柜”的接口。页面每次加载或移动视图,都会拿当前中心点的经纬度去请求一次,接口返回电柜列表,前端把每台柜子画成一个点位。正常应该返回当前视野里需要展示的电柜;数量上限只用于防止一次返回太多,不该把视野里的柜子挡在外面。

这次反馈的是:打开换电任务地图后平移视图,原本应该出现的电柜没有画出来,点位显示不全。核对调用参数发现,地图请求周边电柜时没有传“要取多少台”,下游一直按默认的 30 台处理:按电柜与中心点的距离排序,取最近的 30 台返回。地图拿到这 30 台后,还会按换电权限再过滤一次,去掉这份地图不该展示的柜子。被去掉的名额没有补上,最后落到图上的电柜不足 30 台。平移之后中心点变了,最近 30 台的集合也跟着变,一些原来在视野里的柜子不再出现在返回结果里,看起来就是点位丢失。确认的影响是地图上少画了部分电柜;是否因此漏派任务、涉及多少台,记录没有说明。

本质

一句话:地图要的是“视野内的电柜”,接口给的是“离中心点最近的 30 台”,中间又夹了一层权限过滤,三个数量对不上,视野内的柜子就被截掉了。

  1. 地图取数代码调用周边电柜接口时没有传数量参数。
  2. 下游把“没传”解释成“用默认值”,固定按 30 台处理;它不知道地图这次视野里实际有多少台柜子。
  3. 下游在缓存里按与中心点的距离排序,取最近 30 台。截断发生在这里,而权限过滤还没发生。
  4. 地图调用方拿到 30 台后,按换电权限再过滤,去掉不该展示的柜子。30 台里被去掉几台,图上就只剩二十几台;被去掉的位置不会用第 31 台补上。
  5. 平移视图后中心点变化,按距离排序的前 30 台换了一批:本来在视野内、但距离排在 30 名之后的柜子,这次即使进入视野也不会返回;原来图上的柜子也可能换到 30 名之外而消失。地图上看到的点位随视图变化而增减,实际是取数范围被固定数量卡住,又被权限过滤二次削减。

数量用了默认的 30 台,截断又发生在权限过滤之前,地图要的“视野内全部”被换成了“最近 30 台里过滤后剩下的”。

修复方向是:给周边电柜接口补上数量和视野范围参数,由地图按当前比例算出这次要取多少台;同时把换电权限条件下推到取数一侧,先过滤再按距离取数,或者按“过滤后仍够 N 台”的方式取,避免过滤把名额占掉。接口改造涉及地图和电柜服务两端,是否已经上线、是否还有别的调用方沿用缺省值,记录没有说明。

错误代码

// 换电任务地图取数(脱敏教学示例)
public List<CabinetMarker> loadMarkers(double lng, double lat) {
    // 为什么错:调用周边电柜接口时没有传数量,
    // 下游按缺省的 30 台处理,而地图这次视野里可能不止 30 台
    List<Cabinet> around = cabinetService.getCabinetsAround(lng, lat);

    // 为什么错:30 台先被距离截断,再按权限过滤;
    // 被过滤掉的名额不会由后面的柜子补上,落图数量必然少于 30
    List<CabinetMarker> markers = new ArrayList<>();
    for (Cabinet cabinet : around) {
        if (!swapPermissionService.canShow(cabinet.getCabinetNo())) {
            continue;
        }
        markers.add(new CabinetMarker(
                cabinet.getCabinetNo(), cabinet.getLng(), cabinet.getLat()));
    }
    return markers;
}

修复代码示例

// 修复方向:数量与权限条件随请求一起下推(脱敏教学示例)
public List<CabinetMarker> loadMarkers(double lng, double lat, int zoom) {
    // 修复:按当前比例估算视野内需要多少台,明确传给下游,
    // 不再让接口用缺省 30 台
    int need = estimateMarkerCount(lng, lat, zoom);
    // 修复:换电权限条件一起下推,下游先过滤再按距离取前 need 台,
    // 返回的每一台都是地图可以画的
    List<Cabinet> around = cabinetService.getCabinetsAround(
            lng, lat, need, swapPermissionService.currentScope());

    List<CabinetMarker> markers = new ArrayList<>(around.size());
    for (Cabinet cabinet : around) {
        markers.add(new CabinetMarker(
                cabinet.getCabinetNo(), cabinet.getLng(), cabinet.getLat()));
    }
    return markers;
}

下次遇到这些场景要警惕

  • 给地图或列表页接周边查询接口时:确认请求把数量或范围传下去了,别让缺省值决定结果集。构造视野内电柜数超过默认值的场景,平移一次后逐台核对,确认视野里的柜子都在图上。
  • 查询里同时有权限过滤和数量截断时:先确认两者的先后。构造“前 N 台里有几台无权限”的数据,看返回数量是否被过滤打到 N 以下;应该先在过滤后的集合上截断。
  • 视图移动后点位变少时:把中心点、请求数量、过滤前和过滤后的条数记进日志,比较两次请求的差集,确认减少的柜子是移出了视野,还是被数量上限截掉了。
  • 给接口增加可选的数量参数时:列出所有调用方,逐个确认缺省值对它们是否成立;不成立就改成必填,或由调用方按自己的视野计算后传入。