发生了什么

平台上的商户分上下级:一个一级商户下面挂的下一级经营者叫二级商,二级商要在系统里建出自己的档案,才能签合同、走结算。给二级商建档有一条批量的路子:业务人员在后台下载导入模板,一个二级商填一行,填完上传,系统逐行读取、校验,把每一行变成一条二级商档案。

模板里的列不都是必填的。「结算周期」是其中的选填列,用来约定这个二级商按什么周期和平台结算,空着不填是业务允许的。

正常情况,某一行的选填列没填,系统应当把这一项当成「没有提供」,这一行的其余资料照常建档,档案上的结算周期留空。

这一次,业务人员提交的模板里,结算周期这一列是空的,上传之后导入失败,这批二级商没有建出来。

本质

一句话:导入程序对「结算周期为空」是判断过的,但判断完没有结束这一行的处理,流程继续往下走,后面的代码拿着空值去解析,抛出空指针异常,整次导入跟着失败。

拆开看:

  1. 正常时这一列有没有值都能走。导入程序逐行把单元格读成资料字段;结算周期为空时,本应跳过这一项的解析,档案上的结算周期留空即可。
  2. 出错的地方在判空之后。代码里确实写了一处判断:结算周期为空时记一条日志。但它只记日志,既没有返回,也没有跳过这一行,流程继续执行到下一句——对结算周期做去空格、解析成业务值之类的处理。此时拿到的是空值,调用直接抛空指针异常。
  3. 异常怎么变成整次导入失败。这一行没有把异常兜住、转成「该项未填写」的结果,异常冒到了导入入口,于是这次导入以失败结束,模板里的二级商没有被建出来。
  4. 记录给出的处置在上层。组装导入请求的那一层先判断这个字段有没有值:有值才把值和字段名一起下发;没有值就只保留字段语义、不写具体值,请求里等于没有这一项,下游收不到空串,也就不会去解析它。
  5. 这属于在调用方绕开空值,没有改变下游那段「判了空还继续走」的写法。记录没有说明下游判空是否一并补成提前跳过;要让同类空值不再靠调用方兜,需要把这一分支补完整。

判空只写了一条日志、没有结束流程,等于把空值原样交给下一句解析,异常一抛,整次导入都会失败。

修复方向是让空值在进入解析前就被挡住:要么组装请求时不为空值下发这个字段,要么在判空分支里直接跳过该项解析。下面两段代码是同一行数据的调用两端,均为脱敏教学示例,用于解释错误与修复思路,不代表实际项目源码或已上线实现。修复示例里下游「字段缺失就不解析」这一半,是为了让上层的改动能接得住空值;记录只描述了上层处置,下游是否这样改没有材料确认。

错误代码

public class SubMerchantImportService {

    /** 导入模板的一行:组装要下发的导入请求 */
    public Map<String, Object> buildRequest(SubMerchantRow row) {
        Map<String, Object> req = new LinkedHashMap<>();
        req.put("name", row.getName());
        // 为什么错:结算周期是选填列,留空时这里照样把空值写进请求,
        // 下游收到的是「有一个空值」,而不是「没有这一项」
        req.put("settlementCycle", row.getSettlementCycle());
        return req;
    }

    /** 校验并建档:判了空却继续往下走 */
    public SubMerchant importRow(Map<String, Object> req) {
        if (req.get("settlementCycle") == null || req.get("settlementCycle").toString().isEmpty()) {
            // 为什么错:只记日志,没有返回也没有跳过这一项,空值继续往下
            log.info("结算周期未填写");
        }
        SubMerchant m = new SubMerchant();
        m.setName((String) req.get("name"));
        // 为什么错:空值到这里,toString().trim() 抛空指针,整次导入失败
        m.setCycleDays(SettlementCycleParser.toDays(req.get("settlementCycle").toString().trim()));
        return repository.save(m);
    }
}

修复代码示例

public class SubMerchantImportService {

    /** 导入模板的一行:选填项为空时按「未提供」组装请求 */
    public Map<String, Object> buildRequest(SubMerchantRow row) {
        Map<String, Object> req = new LinkedHashMap<>();
        req.put("name", row.getName());

        // 为什么这样改:空值时只保留字段语义、不写值,请求里不出现该字段,
        // 下游收到的是「没有这一项」,不会再去解析空串
        if (StringUtils.isNotBlank(row.getSettlementCycle())) {
            req.put("settlementCycle", row.getSettlementCycle().trim());
        }
        return req;
    }

    /** 校验并建档:有值才解析,字段缺失时按未填写处理 */
    public SubMerchant importRow(Map<String, Object> req) {
        SubMerchant m = new SubMerchant();
        m.setName((String) req.get("name"));
        if (req.containsKey("settlementCycle")) {
            m.setCycleDays(SettlementCycleParser.toDays((String) req.get("settlementCycle")));
        }
        return repository.save(m);
    }
}

下次遇到这些场景要警惕

  • 模板里每个标为选填的列,都单独留空跑一遍导入:看这一行能不能建出来,失败时能不能指出是哪一行哪一列,而不是只给一句导入失败。
  • 读导入代码时专门找「判空只打日志」的分支:确认空值往下传之前有没有返回或跳过,并且用空值和 null 各构造一次输入,两种都要走通。
  • 从旧方法复制一份解析逻辑来改时,逐段比对旧方法里的空值保护和默认值处理,确认新方法一处没漏。
  • 导入失败要把行号和列名带回给操作人;只报整次失败,业务没法自己改模板重试。