发生了什么

门店后台的“解绑智能芯”,是用来解除车辆与车上那颗智能控制芯片之间绑定关系的操作。车辆退役、换车或者设备坏了需要拆下来时,运营在页面输入车架号,系统按这个条件分页查出候选车辆列在下方,运营点中目标车辆、确认提交,绑定关系才会解除。查不到车就选不中,也就没法解绑。

正常时,输入车架号后页面发出一次分页查询,后端返回两样东西:当前这一页的车辆列表,以及满足条件的车辆总数。前端把列表渲染成一行行候选,同时用总数决定还有没有下一页、要不要显示空态。两个值来自同一个接口,要么一起有数据,要么一起是零。

这次的现象是列表和总数对不上。运营在解绑页输入车架号,页面直接显示“暂无数据”,下方没有任何候选车辆;接口没有报错,页面也没有提示,反馈只能描述成“输入车架号不显示车辆信息”。而查询返回的结果里其实有这台车,只是总数是空的。

背景是一次查询链路改造:车辆资料迁到新服务,读取时先按灰度比例决定走新服务接口还是原来的本地查询,另外还有一个对比开关,打开时会把新老两次查询的结果都取回来做比对。出问题时灰度已经全量走新服务,对比开关是关的。处置是先把对比开关打开让页面恢复,长期改法是让涉及的分页接口直接用新服务返回的列表和总数。记录没有写受影响的门店数量、持续时长,也没有写长期改法的上线验证结果。

本质

问题不在库里有没有这台车,而在分页响应的“总数”这一半没有被填上。

  1. 本地分页插件的工作方式。系统用 PageHelper 这类分页插件做分页:调用分页方法时,插件先把页码、每页条数放进线程上下文;真正执行 SQL 时,它拦截这条语句、改写成只取一页,同时另外跑一条 count 语句,把满足条件的总条数回填到分页对象上。也就是说,total 不是查询语句的返回值,而是“拦截到本地 SQL 之后”顺带产生的。
  2. 改造后的查询入口。切面先按灰度比例选路。走旧路时执行本地 SQL,分页插件拦得到,count 会跑,total 会被填上;走新路时调用新服务接口,本地 SQL 一条都不执行,插件没有可拦的语句,count 也不会跑。对比开关打开时,切面会额外再执行一次旧查询,这个分支“顺手”让 total 有了值——总数字段实际上挂在对比逻辑上。
  3. 这次同时满足了两个条件:灰度全部走新服务,对比开关又是关闭的。切面把新服务返回的列表塞进分页对象就返回,本地 SQL 从头到尾没有执行,total 停在默认的空值(0)。
  4. 页面按 total 判断。前端拿到总数 0,认为没有符合条件的车辆,直接渲染空态,不逐条检查列表内容。于是列表里明明有这台车,页面却显示“暂无数据”,运营选不中车,解绑流程在第一屏就断了。
  5. 为什么一直没人发现。接口返回成功,没有异常也没有错误日志,从监控上看只是一次正常的空列表;而且只要灰度不是全量、或对比开关是打开的,同一段代码就正常,只在默认组合上回归就看不到这个问题。

分页的总数不是查询结果里带出来的,而是本地分页拦截器在执行 SQL 时另跑一次 count 填进去的;查询一旦改走远端、绕开本地 SQL,列表有数据、总数却是空的,页面就按空列表渲染。

记录在排查同类位置时列出的按门店开关查车辆的分页查询方法,写法相同,同样会触发拦截、出现列表有数据而总数为空。临时把对比开关打开能让页面恢复,但那是让旧 SQL 重新执行来补总数,开关一关问题就回来。修复方向是让这些分页接口在契约里直接带上新服务返回的列表和总数,总数取不到就显式报错,而不是留一个默认的 0;确实还要走本地分页的地方,必须保证分页插件真的拦到那条 SQL。

代码为脱敏教学示例,用于解释错误与修复思路,不代表实际项目源码或已上线实现。

错误代码

// 车辆分页查询(脱敏教学示例):总数全靠本地分页插件回填
public PageResult<VehicleView> pageQueryVehicle(String keyword, int pageNo, int pageSize) {
    Page<VehicleView> page = PageHelper.startPage(pageNo, pageSize);
    List<VehicleView> list = vehicleQueryFacade.query(keyword, pageNo, pageSize);
    // 为什么错:灰度全量时这里走新服务接口,本地 SQL 一条都不执行,
    // 分页插件没有可拦的语句,那条 count 根本没跑,total 还是默认的 0
    if (compareSwitch.isOn()) {
        // 为什么错:total 只在这个对比分支里被执行旧 SQL 时顺带填上,
        // 开关一关,这段跳过,总数字段就永远没人赋值
        List<VehicleView> old = vehicleMapper.selectByKeyword(keyword);
        diff(list, old);
    }
    // 为什么错:列表有数据、总数是 0,前端按 total 判断就当成没有车辆
    return PageResult.of(list, page.getTotal());
}

修复代码示例

// 同一段查询:列表和总数都取自新服务,契约里必须都返回
public PageResult<VehicleView> pageQueryVehicle(String keyword, int pageNo, int pageSize) {
    RemotePage<VehicleView> remote = vehicleQueryFacade.page(keyword, pageNo, pageSize);
    if (remote.getTotal() < 0) {
        // 之所以这样改:取不到总数就明确失败,不要让默认值变成“没有数据”
        throw new IllegalStateException("vehicle page total missing, keyword=" + keyword);
    }
    // 列表和总数来自同一次远端查询,页面判断依据与数据来源一致
    return PageResult.of(remote.getList(), remote.getTotal());
}

// 确实还要本地分页的方法:分页插件必须真的拦到 SQL,count 才会执行
public PageResult<VehicleView> pageQueryLocal(String keyword, int pageNo, int pageSize) {
    PageHelper.startPage(pageNo, pageSize);
    List<VehicleView> list = vehicleMapper.selectByKeyword(keyword);
    return PageResult.of(list, new PageInfo<>(list).getTotal());
}

下次遇到这些场景要警惕

  • 把查询从本地库迁到远端服务时:把接口返回拆成“列表”和“总数”两栏逐项核对,确认两者都来自同一次远端查询;造一条确实存在的数据跑一次,看返回的 total 是否大于 0、是否与列表自洽。
  • 用灰度比例或开关切换读写路径时:把开关的组合都过一遍(旧路、新路、对比开、对比关),每种组合都用一个“确定有数据”的输入验证;只在默认组合上回归,会漏掉这种只在某条分支里被赋值的字段。
  • 引入分页插件、拦截器、切面这类隐式生效的机制时:先写下它生效的前置条件(必须真正执行被拦截的 SQL),再检查有没有分支绕过了它;绕过时要在那一层显式取总数或直接报错,不能让框架默认值冒充结果。
  • 页面显示空态但业务方坚称数据存在时:先看接口原始响应里的列表和总数是否自相矛盾,再判断是数据问题还是展示问题;后端也不要把“没有执行 count”当成“没有数据”。