发生了什么
平台有一个商户资料后台,签约合作的商家在系统里叫商户,商户资料里有一块是收款用的银行卡。新录一张卡时,业务人员不是在输入框里手打开户行,而是先在下拉框里选“银行”和“城市”,再填一个支行名关键词,系统列出这家银行在这个城市下的支行网点,选中后保存。
正常流程下,选完银行和城市、输入支行名,候选里就该出现目标网点。业务这次要录的是某某银行股份有限公司在当地的一家支行,他选了银行、填了支行名,候选列表里没有这家支行;换关键词、重新打开页面结果一样。目标支行始终不出现,这张银行卡就录不进去。业务只能先选一家能正常处理的银行把流程走完,目标支行一直没有登记上。
从这次请求的参数看,问题出在搜索这一步:银行名传的是法人全称“某某银行股份有限公司”,城市名是空的,只带了一个城市编码;接口一次最多返回1000条候选,目标支行不在这1000条里。这段逻辑是2021年8月一次改动留下的,直到2026年8月才被业务报上来。
本质
参与这次搜索的有三方:页面负责收集银行、城市和支行关键词;接口把参数拼成查询条件;下游支行数据提供候选。三方的动作各自都让范围变大了一点。
- 页面把选中的银行名当作搜索参数传下去,用的是法人全称“某某银行股份有限公司”,城市名没有值,只带了城市编码。
- 接口判断 cityName 为空,就不拼“银行+城市”这组条件;城市编码虽然被读进了方法,却没有进入查询语句,所以只补城市编码收不窄范围。
- 接口又把 bankName 这个参数当成支行名(subBankName)的关键词,直接拿它去模糊匹配支行名称,等于在全国的支行名里找“名称包含某某银行股份有限公司”的记录。
- 下游支行数据里,这家银行的标准名称是简称“某某银行”,比法人全称少“股份有限公司”几个字,名称这一层对不上,按名称定位银行也落空。
- 这样拼出来的是一次全国范围的模糊查询,而这类查询最多只返回1000条,超出的部分被直接丢掉,调用方也收不到“还有更多”的提示。
几件事叠在一起:本应“在某家银行的某个城市里找支行”,实际变成“在全国所有支行名里模糊匹配一串银行全称”,再被1000条上限截断。目标支行既没被前两个条件圈进来,也没挤进前1000条,下拉里自然没有它。更麻烦的是,返回的列表看起来就是完整结果,页面没有分页,业务没法翻下一页,只能以为库里没有这家支行。
修复方向是:把“银行”和“支行关键词”拆成两个参数,银行名先归一到标准名称,或者直接传银行编码,再定位银行;城市名与城市编码任一生效,两者都没有时明确提示“请选择城市”,不再静默做全国搜索;查询结果给出总数并支持翻页,命中过多时提示细化条件,而不是把一个截断后的列表当作完整结果返回。这个改动没有实施,产品侧的说法是新模型商户管理不再提供银行卡管理能力,此处暂不修复。
下面用一段脱敏教学示例说明这段查询与修复思路,代码不代表实际项目源码或已上线实现。
错误代码
// 教学示例:按银行、城市、支行关键词检索支行
List<Branch> searchBranch(String bankName, String cityName, String cityCode) {
BranchQuery q = new BranchQuery();
if (StringUtils.isNotBlank(cityName)) {
q.setCityName(cityName); // 城市名为空,这组条件被整段跳过
}
q.setSubBankName(bankName); // 为什么错:银行名被当成支行名关键词
q.setLimit(1000); // 为什么错:固定上限,超出部分静默丢弃
// cityCode 已经传进来,却没有拼进任何查询条件
return branchMapper.selectByQuery(q);
// 实际执行:select * from branch
// where sub_bank_name like '%某某银行股份有限公司%' limit 1000
}
修复代码示例
PageResult<Branch> searchBranch(BranchQueryReq req) {
// 1. 银行名先归一到标准名称,定位到唯一的银行
Bank bank = bankRepository.findByStandardName(
bankNameNormalizer.toStandard(req.getBankName()));
if (bank == null) throw new BizException("未知银行");
// 2. 城市名与城市编码任一生效,都没有就拒绝,不再全国查
String city = firstNonBlank(req.getCityName(), cityService.nameOf(req.getCityCode()));
if (city == null) throw new BizException("请选择城市");
// 3. 银行、城市、支行关键词各用各的参数
BranchQuery q = new BranchQuery();
q.setBankId(bank.getId());
q.setCityName(city);
q.setSubBankName(req.getKeyword());
return branchMapper.selectByPage(q, req.getPage()); // 显式分页,同时返回总数
}
下次遇到这些场景要警惕
- 下拉搜索依赖外部支行、机构、网点这类基础数据时,用标准简称和带“股份有限公司”的法人全称各搜一次,确认两种写法都能命中目标;再把接口收到的参数和真正拼进查询的字段逐个对一遍,避免字段名对得上、语义对不上。
- 查询方法新增城市、区域这类收窄参数时,把参数传空或删掉各跑一次,打印实际执行的语句对比,确认条件真的出现在查询里;只在方法签名里读到、没有拼进查询的参数,看起来支持,实际无效。
- 凡是结果有固定条数上限的查询,构造一条命中数超过上限的数据,确认接口会返回总数或“已截断”标记,页面能翻页或提示细化条件;不要接受“列表看起来完整”这种状态。
- 业务反馈“某个选项选不到”时,先让对方给出目标项的完整名称,再拿这个名字直接查基础数据表,确认数据存在、名称写法与入参一致,而不是反复在模糊搜索结果里找。