发生了什么

发票上传是发票进入系统的入口:用户选好发票文件、填写票面信息后提交,系统先调用发票验真接口核对这张票,再拿验真返回的票面信息和用户填写的内容逐项比对。发票抬头就是票面上写的购买方名称,它和金额、发票号码一样都在比对范围内,任何一项对不上,这次上传都会被拒绝,系统不会为这张票留下记录。正常情况是两边一致、上传通过,发票才算登记进系统。

验真接口这一侧有一个前提:它按设计只返回自己识别到的字段,发票抬头就常常不在返回结果里。改造这段校验的人把原来的判空写法理解成“防止空指针的兜底”,顺手把它改成了“字段为空就等于不一致,直接返回错误”。于是 12 月 22 日晚上开始,发票上传报出的都是同一句提示:发票抬头不一致,不能上传发票。

一开始现场按正常校验拦截处理,认为是用户上传的发票有问题。查日志才看清:这几条请求的验真结果里根本没有抬头字段,拿来比较的是一个不存在的值。后续多条请求报的都是同一个错,说明问题不在某一张票据上。

本质

比较两个值,只有两边都有值时才可能得出“一致”或“不一致”。验真接口没有返回抬头,表示这次没有拿到这个字段、没有比对依据,并不表示用户填错了。

  1. 改造前的代码正是按这个前提写的:先判断验真返回的字段是不是空,空就跳过这一项,接着比下一项。这个判空的作用是“没有依据就不下结论”。
  2. 改造时它被理解成防止空指针的兜底写法,改成显式的失败分支:验真返回为空,或者和填写值不相等,都返回“抬头不一致”。
  3. 于是“无法比较”变成了“比较失败”。上游不返回抬头的每一张发票,都会在这一行被判不一致,上传被拦在入口。
  4. 提示语只说抬头不一致,把排查方向引向了票据本身,现场因此先怀疑用户上传的发票有问题,而不是先怀疑校验逻辑。
  5. 恢复靠回退而不是改数据:先通过灰度开关把校验切回更新前的版本,上传恢复;再把这行判断改回“只有验真返回了该字段才参与比对”,重新上线后关闭回退开关。

空值在这里表示“没有比对依据”,把它当成“不一致”,等于用缺失的证据判了票据不合格。

下面两段是脱敏教学示例,用于说明错误与修复思路,不代表实际项目源码或已上线实现。

错误代码

public class InvoiceFieldComparator {

    public CheckResult compare(InvoiceUploadForm form, VerifyResult verify) {
        // 为什么错:验真接口按设计只返回部分字段,抬头常常不返回,
        // 这里把“没返回”和“抬头填错了”合并成同一个失败分支
        if (!same(verify.getTitle(), form.getTitle())) {
            return CheckResult.fail("发票抬头不一致,不能上传发票");
        }
        if (!same(verify.getAmount(), form.getAmount())) {
            return CheckResult.fail("发票金额不一致,不能上传发票");
        }
        return CheckResult.ok();
    }

    private boolean same(String verified, String filled) {
        // 为什么错:一边为空就直接判不相等,上游没返回字段时必然走到这里
        return verified != null && verified.equals(filled);
    }
}

修复代码示例

public class InvoiceFieldComparator {

    public CheckResult compare(InvoiceUploadForm form, VerifyResult verify) {
        // 修复:只有验真返回了该字段,才把它作为比对依据
        if (hasText(verify.getTitle()) && !verify.getTitle().equals(form.getTitle())) {
            return CheckResult.fail("发票抬头不一致,不能上传发票");
        }
        if (hasText(verify.getAmount()) && !verify.getAmount().equals(form.getAmount())) {
            return CheckResult.fail("发票金额不一致,不能上传发票");
        }
        // 缺失的字段不参与比对,但要留痕,便于回查这次校验到底依据了哪些字段
        recordSkippedFields(form, verify);
        return CheckResult.ok();
    }

    private boolean hasText(String value) {
        // 缺失(空值或空白)不等于不一致:没有依据时不下结论
        return value != null && !value.trim().isEmpty();
    }
}

下次遇到这些场景要警惕

  • 改造一段带判空的比对逻辑之前:先逐个写出判空分支的原有作用,是跳过比较、给默认值,还是拦下请求;不要因为“看起来像防空指针”就把它改成失败分支。
  • 接入或升级第三方验真、识别接口时:按“正常值、字段缺失、空串、空值”四类响应各构造一条用例,确认系统是跳过该项比对、转人工核验,还是判为不一致,并把这三种处理写进用例断言。
  • 上线前用一条正常发票走完整流程:选一张上游不返回某个字段的票据上传,如果提示“不一致”,先去日志核对该字段到底有没有返回,不要先让用户重传或改票面。
  • 靠开关回退止血之后:回退只能证明旧版本可用,还要确认被拦下的发票是否需要补传,并在修复版本上线后重跑同一批票据。