发生了什么
账务服务保存结算相关的账务数据。商户账单是其中一类记录:它按账期汇总某个商户的账单金额,系统提供导出,把账单拉成表格文件。账单不是账务服务自己算出来的,而是清结算程序算出后通过消息推过来,账务服务接收并保存,再对外提供查询和导出。
账单上有一个“结算商户”字段,记录清结算为这笔账单确定的结算商户。这个字段不是账单消息一到就有:清结算要先有账单,之后才生成对应的结算单,结算单生成后再发一条消息,把结算商户补到账单上。所以账单刚保存时结算商户为空,是流程里正常的中间状态,不是错误数据。
正常导出时,每一行账单都已经带上结算商户,导出结果是一张完整表格。这一次,导出的这批账单里混着还没生成结算单的记录。导出时程序先取出账单,把这些账单的结算商户编号收成一个列表,再批量换成商户信息用于展示。列表里混着空值,批量转换在这一步失败,抛出 NumberFormatException,异常的说明文字就是 null;界面上最终给出的提示也只有 null,导出的人看不出是哪张账单、缺了什么。这个字段过一段时间会由清结算的消息补上,同一批账单晚些再导出可能就正常了,因此它看起来更像偶发问题,实际取决于导出时这批账单处在哪个阶段。
本质
问题不在结算商户为空,空是清结算流程决定的正常状态。问题在批量转换编号时把“暂时为空、稍后补全”的值当成“一定可以转成数字”,没有先过滤。
按实际顺序看:
- 清结算算出账单,先发账单消息。此时结算单还没生成,消息里的结算商户是空的。
- 账务服务收到消息,把账单保存下来,结算商户为空。这一步本身不算错,字段确实允许为空。
- 清结算随后生成结算单,再发一条更新消息。账务服务据此把结算商户补上,到这一步数据才完整。
- 导出发生在这批账单补全之前。导出程序先按筛选条件取出账单,把这些账单的结算商户编号收集成一个列表,再调用商户查询,批量换成商户信息用于导出。
- 商户查询把列表里的每个编号都交给 Long.parseLong。列表里只要有一条为空,转换就抛 NumberFormatException,异常的说明文字正是 null。异常在这里被捕获并记录,方法返回空列表。
- 导出因此拿不到这批商户信息;这次导出最终给出的提示只有一个 null,既没有账单号也没有缺失字段;排查时记录可能已经被补全,看上去又正常了,复现和定位都更难。
把“暂时为空、稍后补全”的字段当成“一定可以转换”,并且把一批编号直接交给 parseLong,一条空值就能让整批商户信息查不出来:提示只有 null,账单本身却可能已经补全。
处理方式是在转换前过滤掉为空的结算商户编号,再批量查询;该修复已上线。过滤后其他账单的商户信息照常查出来,这条账单只是没有商户信息,不会因为一条空值让整批查询失败。更彻底的方向是在导出结果里明确给出未生成结算商户的账单数量,并让异常兜底带上上下文,而不是只返回一个空列表。
下面用最小示意复现这一步:错误版把整批编号直接交给 parseLong,修复版先过滤空值再转换。
错误代码
/** 导出时把账单上的结算商户编号批量换成商户信息 */
public List<MerchantAccount> queryMerchantAccount(List<String> merchantIdList) {
try {
MerchantQueryRequest request = new MerchantQueryRequest();
// 为什么错:账单先到、结算单后生成,编号在补全前为空是正常状态;
// 这里把整批编号直接交给 parseLong,一条 null 就抛 NumberFormatException
List<Long> merchantIds = merchantIdList.stream()
.map(Long::parseLong)
.collect(Collectors.toList());
request.setMerchantIds(merchantIds);
ServiceResult<List<MerchantAccount>> result = merchantService.queryMerchantList(request);
if (result == null || result.getData() == null) {
return Collections.emptyList();
}
return result.getData();
} catch (Exception e) {
// 异常被记录后转成空列表,调用方看不出是数据没就绪还是查询失败
log.error("queryMerchantAccount error", e);
return Collections.emptyList();
}
}
修复代码示例
/** 导出时把账单上的结算商户编号批量换成商户信息 */
public List<MerchantAccount> queryMerchantAccount(List<String> merchantIdList) {
try {
MerchantQueryRequest request = new MerchantQueryRequest();
// 修复:结算商户为空表示结算单还没生成,先过滤再解析
List<Long> merchantIds = merchantIdList.stream()
.filter(StringUtils::isNotBlank)
.map(Long::parseLong)
.collect(Collectors.toList());
if (merchantIds.size() < merchantIdList.size()) {
// 过滤掉多少条要能看见,避免导出结果少了商户信息却没人发现
log.info("skip blank settlement merchant, count={}",
merchantIdList.size() - merchantIds.size());
}
request.setMerchantIds(merchantIds);
ServiceResult<List<MerchantAccount>> result = merchantService.queryMerchantList(request);
if (result == null || result.getData() == null) {
return Collections.emptyList();
}
return result.getData();
} catch (Exception e) {
log.error("queryMerchantAccount error", e);
return Collections.emptyList();
}
}
两段代码是脱敏教学示例,用于解释错误与修复思路,不代表实际项目源码或已上线实现。类名、方法名和字段名为示意,保留了“批量编号解析失败后异常转空列表”的结构。
下次遇到这些场景要警惕
- 上游按“先建主记录、后补字段”分两条消息推送时:构造一条“主记录已到、补充字段未到”的数据走完整导出,观察提示是否可读、其他账单是否照常导出,而不是只测补全之后的数据。
- 批量把编号转成数字或枚举时:先过滤空值再转换;一条空值会让整批转换失败,影响范围不是一条记录,而是同一批查询。
- 导出或对外接口用异常兜底时:不要只返回空列表;至少记录被过滤的条数,并在结果里标出缺少商户信息的账单,否则调用方只会拿到一个空结果,使用者只看到一个 null。
- 排查“偶发”的导出失败时:同一批数据在补全消息前后各导一次,比较两次结果;只在补全后验证,会漏掉这类只在中间状态出现的问题。