发生了什么

平台按商户发放一种叫“免时长”的额度:在约定期限内,用户使用服务不收费,这段可以免费使用的时间按天记账。额度会分配给商户名下的用户,每个用户留一条剩余天数;系统另有一份扣减卡数据,一张卡记着这一批分配的天数合计。这笔额度按什么方式消耗,由“扣减模式”决定。商户要把扣减模式从一种换成另一种,先走审批,审批通过后由一个后台批量任务统一执行。

正常一次就能跑完:任务先校验该商户名下已分配用户的剩余天数,确认账对得上;再逐页读出该商户的扣减卡;数据读完,商户切到新的扣减模式,审批记录留在已完成。整个过程只需要跑一次。

这次同一个商户先后跑了两次,都没成功,但失败位置不一样。第一次停在预校验:查剩余天数的语句在并行查询时数据库连接中断,属于再跑一次就能过去的瞬时异常;任务没有重试,直接判定这次切换失败,把审批记录还原,并发出一条失败通知。隔了几天重跑,失败位置换到了读扣减卡:某张卡的天数合计是 40000,程序读这个值时抛出 Bad value for type short : 40000,这一页数据一条也没读出来。第二次不是环境问题,是代码里的字段装不下这个数。

结果是这个商户没有切到新的扣减模式:第一次失败后审批记录被还原,第二次重跑又卡在读取,商户只能继续按旧模式扣减,等人来查。这一轮受影响的商户只有一个。这个字段是功能最初开发时就写成短整型的,不是后来改动带出来的。

本质

  1. 扣减卡的天数合计在数据库里用 4 字节整数存。这个商户几张卡的合计分别是 40000、57000、44500、33500 天,全部超过短整型能表示的上限 32767。
  2. 程序里这个字段声明成 Short,对应数据库的 SMALLINT。读取时驱动要把 40000 放进 short,校验发现越界,直接抛出异常,这一页的结果映射失败。
  3. 任务按页读卡,一页里只要有一条这样的记录,这一页就全部读不出来,切换停在读数据这一步,后面的动作一个都没执行。
  4. 任务的失败处理把所有异常收进同一个分支:不重试、还原审批记录、发一条失败通知。于是第一次的连接中断和第二次的类型溢出,对外是同一句“切换失败”。
  5. 类型没有改,这个商户重跑多少次都会在同一条记录上抛同一个异常,不会自愈。两次失败看起来像同一件事,真正让切换过不去的是第二步这个映射。

数据库里能存下几万天的列,程序用一个最多装 32767 的短整型去接,读到 40000 时在取值那一步就报错。

修复方向是:字段类型跟列对齐,改成 Integer 或 Long,并把同类实体里所有比列窄的整型字段一起排查;任务的失败分支按异常性质分开,连接中断这类瞬时失败进入带幂等的重试,类型映射、数据越界这类确定性失败把原始异常直接暴露出来,不要伪装成可以重跑的失败。记录里给出的处理方式是修改代码,是否已经上线、这个商户是否已经重跑成功,记录没有说明。

错误代码

public class DeductionCardInfoPO {
    private Long id;
    private Long merchantId;
    // 为什么错:库里这一列是 4 字节整数,大商户几张卡合计能到几万,
    // 用 Short 接,读到 40000 时驱动校验越界,取值当场抛异常
    private Short total;
}

public class DeductionModeSwitchJob {

    public void run(Long switchId, Long merchantId) {
        try {
            preCheckSurplusDays(merchantId);
            List<DeductionCardInfoPO> cards = cardService.getAllDeductionCards(merchantId);
            applyNewMode(cards);
        } catch (Exception e) {
            // 为什么错:连接中断和类型越界都进同一个 catch,一律不重试,
            // 直接还原审批记录,商户只能停在旧模式
            switchRecordMapper.restoreApproval(switchId);
            notifier.send("免时长扣减模式切换失败");
        }
    }
}

修复代码示例

public class DeductionCardInfoPO {
    private Long id;
    private Long merchantId;
    // 修复:与 4 字节整数列对齐,天数再大也不会在读取时溢出
    private Integer total;
}

public class DeductionModeSwitchJob {

    public void run(Long switchId, Long merchantId) {
        try {
            preCheckSurplusDays(merchantId);
            List<DeductionCardInfoPO> cards = cardService.getAllDeductionCards(merchantId);
            applyNewMode(cards);
        } catch (TransientDataAccessException e) {
            // 修复:拿到连接类瞬时异常才排队重跑,重跑前确认这一步没有已生效的写入
            retryQueue.enqueue(switchId);
        } catch (Exception e) {
            // 修复:映射失败这类确定性错误直接暴露原因,
            // 不再混进可以重跑的失败里,避免把缺陷当偶发问题拖下去
            switchRecordMapper.markFailed(switchId, e.getMessage());
            notifier.send("切换失败,需要人工核对:" + e.getMessage());
        }
    }
}

两段代码是脱敏教学示例,用来说明错误与修复思路,不代表实际项目源码或已上线实现。类名、字段和数值均为示意,实际字段类型要按列定义和业务上限确认。

下次遇到这些场景要警惕

  • 给数据库的整数列建实体字段时:先确认列的真实类型,再查这一列的实际取值分布,尤其是按商户、按用户汇总出来的合计值,然后选字段类型;把“单位是天、大商户能累计到几万”这样的量级写进字段注释,别让下一个人凭直觉用短整型。
  • 批量任务要处理天数、金额这类会累积的数值时:构造一条超过 32767 的记录,把读取、处理和落库完整跑一遍,观察是否成功;只用小数据量的对象验收,这类越界一定会漏掉。
  • 写任务的失败分支时:把瞬时异常(连接中断、超时)和确定性异常(映射失败、数据越界、校验不通过)分开处理,前者重试并确认这一步没有已经生效的写入,后者告警时带上原始异常信息。
  • 排查“重跑还是失败”的任务时:先确认两次失败是否停在同一处、同一条记录,再比较异常类型;如果对外只有一句笼统的失败提示,说明失败处理的粒度太粗,容易把确定性缺陷当成偶发问题拖上几天。