发生了什么

换电柜用来给用户更换电池,柜内有多个格口,一块电池放在一个格口里。电池出现故障时,平台先给这块电池打上故障标记,让它停止流转,再下发一次重启指令,希望电池复位后恢复可用。正常流程是:重启指令从电柜的格口下发,由电柜对插在该格口里的电池执行重启,执行完成后电池回到可用状态。也就是说,一条重启记录应当对应一次真实执行,电池才算完成复位。

这次上线的电池故障打标重启功能,正是为了把“打标”和“重启”串起来。功能上线次日上午,产品查看重启记录时发现,所有记录返回的都是“该电池无需重启”,没有一块电池真正执行重启,功能等于没有生效。

研发排查后确认,代码实际调用的不是电柜格口的下发接口,而是下游另一个“直接给电池下发重启指令”的接口。需求文档和技术方案写的都是通过电柜格口下发;开发过程中,组内有人发现下游有现成的电池直连接口,开发在没有向接口负责人确认适用条件的情况下改用了它。

测试阶段其实已经出现过同样的现象:所有电池下发后都返回“无需重启”。研发排查时发现接口还返回过“设备编号不存在”,于是找设备侧要了几个真实编号调用,其中一块电池重启成功,便判断测试环境用的都是虚拟电池,返回“无需重启”属于正常现象,没有继续追问生产上为什么也会如此。

影响是这次上线后进入重启流程的故障电池都没有被执行重启,调用侧却没有报错,业务侧缺少可用的恢复动作。此次未影响订单。

本质

问题由两个错误叠在一起:选错了下发通道,以及把“无需重启”当成了成功。

  1. 业务上有两条下发路径,动作对象不同。需求要的是格口路径:指令发给电柜,电柜对指定格口里的电池执行重启。直连路径是把指令直接发给电池本身,由电池侧自行判断要不要执行。两条路径的前置条件、执行主体和返回含义都不一样。
  2. 开发选用了直连路径,仅凭接口描述就认为“都是给电池下发重启”,没有找接口负责人确认它在什么条件下才会真正执行。直连接口会按自己的条件判断是否需要重启,判定不需要时返回“无需重启”,不执行动作。生产上这批待重启电池全部命中这一判断,因此返回了同一句话。具体按哪些字段判断,开发在切换接口前没有确认。
  3. 调用方拿到返回后没有区分“已执行”和“无需重启”,两种结果都按正常结束处理,没有记失败,也没有触发告警。
  4. 结果就是:接口调用链完整、没有报错,重启却一次都没有发生。业务侧只看到接口正常返回,电池实际仍停在故障状态。
  5. 测试阶段的集中异常被“虚拟电池”解释掉了。测试环境用的是虚拟电池,返回的同样是“无需重启”;补充验证只用一块真实编号的电池确认能下发成功,没有继续确认生产上这批电池为什么也会一律返回“无需重启”,同一个现象在测试环境被当成环境差异,到了生产环境就变成全量失效。

接口返回“无需重启”,调用方却按正常结束处理,重启从未真正发生。

修复方向是把下发通道改回电柜格口:重启时传入电柜和格口,由电柜执行;同时把下游返回的业务结果纳入判断,返回“无需重启”或明确拒绝时记为失败并保留原因,不再落成功状态。该问题在反馈次日晚上全量发布修复。

下面的 Java 代码为脱敏教学示例,用于说明“调用错接口且忽略业务返回”的机制与改法,不代表实际项目源码或已上线实现。

错误代码

public void restart(BatteryFaultTask task) {
    // 为什么错:需求要求经电柜格口下发,这里却调用了电池直连接口
    BatteryRestartResp resp = batteryClient.restart(task.getBatteryId());
    // 为什么错:没有区分“已执行”和“无需重启”,两种返回都按成功处理
    task.setStatus(RestartStatus.SENT);
    task.setSentAt(now());
    taskDao.update(task);
    log.info("battery restart sent, battery={}, msg={}",
            task.getBatteryId(), resp.getMessage());
}

修复代码示例

public void restart(BatteryFaultTask task) {
    if (task.getSlotId() == null) {
        throw new BizException("电池不在格口内,无法重启");
    }
    // 改为经电柜格口下发,由电柜对格口内的电池执行重启
    SlotRestartResp resp = cabinetClient.restartSlot(
            task.getCabinetId(), task.getSlotId());
    // 业务结果单独判断:未被受理就记失败,不落已下发
    if (!resp.isAccepted()) {
        task.setStatus(RestartStatus.FAILED);
        task.setFailReason(resp.getMessage());
        taskDao.update(task);
        return;
    }
    task.setStatus(RestartStatus.SENT);
    task.setSentAt(now());
    taskDao.update(task);
}

下次遇到这些场景要警惕

下游已有能完成相似动作的现成接口时:先向接口负责人确认它由谁执行、在什么条件下执行、返回什么含义,再对照需求里的动作对象,分清是“电柜对格口执行”还是“电池自己执行”,不要只凭接口名和描述选型。

接口返回“无需处理”“已忽略”“跳过”这类业务结果时:把它当作未完成处理,记录原始返回码和文案,并检查列表、详情、日志三处是否一致显示为未执行。

测试环境大量使用模拟设备时:至少用一条与生产同状态的样本走完整条链路,观察最终业务结果;集中出现同一返回时,先按缺陷排查,不要用“模拟数据”解释过去。

功能上线首日:按结果维度统计成功、无需处理、失败的数量;某一结果占比达到 100% 时,优先怀疑下发通道选错或判断条件不匹配。