发生了什么

收益账单是平台给联营商(在平台开店的商户)结算用的账。一张账单按结算周期汇总应结金额,账单明细再逐笔列出这笔账由哪些收入、扣款构成。联营商在商户端打开收益账单页面,点开一张账单看明细,就是用来核对平台算得对不对。

正常流程是:账单生成后,页面按当前登录商户所属门店和账单号去查明细,只取本门店的数据;查到了就展示列表,确实没有就展示空列表。也就是说,这一步正常的结果是“有明细”或“没有明细”,不应该打不开页面。

这次不同在于,某次迭代的新代码改动了查账单表的 SQL,门店条件里写的 shop_id 和表里的字段对不上。数据库执行这条语句时直接报错:不是没查到数据,而是整条查询没有跑完,接口返回失败,页面拿不到明细,联营商只能反馈“无法查看账单明细”。

受影响用户是 1 位,由业务侧上报。处置分两步:临时把收益账单页面切回老页面版本,让老查询绕开新 SQL;长期方案是当天晚上发布代码修复。复盘把主要责任归在开发侧:这次只改了 SQL,发版前没有自测,也没有通知测试回归;而查看账单明细属于常规回归场景,测试没有覆盖到。问题单状态为已完成,修复上线状态待确认。

本质

一句话:新查询里的门店字段名写错了,数据库无法解析这条语句,明细接口整个失败,页面自然打不开;这不是这个联营商没有明细。

  1. 正常时,明细查询按账单号和门店过滤,字段名与表结构一致,数据库能解析,返回该门店的明细;真的没有明细就是 0 行。
  2. 这次迭代里,新查询把门店条件写成了 shop_id,而这张表里门店维度用的是另一个字段名(教学示例中示意为 store_id)。字段名对不上,数据库在解析阶段就报“列不存在”一类的错误,语句没有机会返回结果。
  3. 报错沿数据访问层抛到接口,接口返回失败,页面拿不到数据,联营商看到的就是打不开明细。
  4. 这里要分清两种结果:条件值不对只是查不到,返回 0 行,页面还能展示空列表;字段名写错是整条 SQL 执行失败,接口直接报错。两者的现象、排查方向和修复位置都不一样,这次是后者。
  5. 临时切回老页面版本,是让老查询绕开新 SQL,新代码的问题还在;长期方案是当晚改字段发版。问题单后来标记为已完成,但还没有修复验证的结论,不能把“已完成”当成“已验证”。

字段名对不上时,数据库不会返回空列表,而是让整条查询直接失败;页面打不开和“这个商户没有明细”是两回事。

修复方向是:把门店条件改成表里真实存在的字段,发版前用真实门店的账单数据把明细页完整跑一遍;查询失败要打出能定位的日志并告警,不要把异常吞成“暂无数据”。两段代码是按这条链路写的脱敏教学示例,不代表实际项目源码或已上线实现。

错误代码

@Mapper
public interface BillMapper {

    // 按账单号 + 门店取账单,明细随后按账单编号关联
    @Select("SELECT id, bill_no, total_amount, status " +
            "FROM bill " +
            "WHERE id = #{billId} " +
            "  AND shop_id = #{shopId}")     // 为什么错:bill 表没有 shop_id 列,SQL 解析即报错
    Bill selectForShop(@Param("billId") Long billId, @Param("shopId") Long shopId);
}

public BillDetailVO queryDetail(Long billId, Long shopId) {
    Bill bill = billMapper.selectForShop(billId, shopId);
    if (bill == null) {
        throw new BizException("账单不存在");
    }
    // 查询失败会直接抛到这里,既没有兜底,也没有告警
    return assemble(bill, detailMapper.selectByBillId(billId));
}

修复代码示例

@Mapper
public interface BillMapper {

    // 门店列名与表结构一致;只改字段,业务含义不变
    @Select("SELECT id, bill_no, total_amount, status " +
            "FROM bill " +
            "WHERE id = #{billId} " +
            "  AND store_id = #{shopId}")
    Bill selectForShop(@Param("billId") Long billId, @Param("shopId") Long shopId);
}

public BillDetailVO queryDetail(Long billId, Long shopId) {
    Bill bill = billMapper.selectForShop(billId, shopId);
    if (bill == null) {
        throw new BizException("账单不存在或不属于当前门店");
    }
    List<BillDetail> details = detailMapper.selectByBillId(billId);
    // 确实没有明细时返回空列表,与查询失败区分开
    return assemble(bill, details == null ? Collections.emptyList() : details);
}

下次遇到这些场景要警惕

  1. 改查询 SQL(尤其新增或替换过滤字段)后,不要只在列表页点一遍:拿一个真实门店的真实账单,把列表、明细、导出都走完,确认每一步都能返回结果;字段名以表结构为准,不要凭记忆或从旧代码里抄。
  2. 新页面接新查询时,把老页面同一功能的结果当对照:同一张账单、同一个门店,新老页面的明细条数和金额要对得上;对不上先查过滤字段和关联键,不要先怀疑数据。
  3. 把“只改 SQL”的改动列进发版前回归清单并通知测试:SQL 改动没有编译错误可拦,列名写错也过不了静态检查,只有用真实数据执行才能暴露。
  4. 明细接口失败时,日志要能直接看到执行的语句、绑定参数和数据库错误;不要统一转成“暂无数据”,否则线上只看到“用户看不到明细”,定位不到是哪一列。