发生了什么
电柜是投放在点位上的换电设备,用户扫码后直接从柜子里取电池。柜子要持续向平台上报在线状态,一旦掉线,这个点位当场就没法换电,需要运维上门查看。为此系统里有一层“离线故障识别”:定期筛查长时间不在线的柜子,为它们生成电柜离线工单,运维按工单上门处置。没有工单,就不会有人被派到这个点位。
识别程序不写死柜子型号。它先从配置中心读出一份“当前生效的电柜型号码”清单,这份清单由运营维护,投放新型号时加进去;再逐条把型号码交给共享设备模型包里的枚举,翻译成型号类型。只有翻译成功的型号,才会被纳入离线判断和建单范围。正常链路是:型号投放,型号码加进配置,识别程序读到它,枚举翻译出类型,之后这些柜子掉线就能生成工单。
这次投放了两款新型号电柜,型号码分别是 26 和 27。后来有人反馈:这两款柜子掉线,就是生成不了离线工单。查下来,配置这一层是好的,26、27 都在清单里,问题出在翻译这一步。识别服务引用的共享设备模型包被固定在旧版本 2.9.5,这个版本里的枚举只收录了老型号,没有 26、27。配置给出这两个号,枚举里查不到对应的型号类型,翻译失败,这两款柜子也就进不了建单流程。
确认的影响是这两款型号的离线故障不会被转成工单;具体涉及多少台、持续多久,记录里没有写。处置是把识别服务引用的共享包从 2.9.5 升到 3.1.2,新版本枚举里已经带上 26、27,升级后问题修复。事后也定了一条:新电池、新电柜投放要提前通知相关系统,不通知调整,系统默认不支持生成离线工单。
本质
一句话:配置里加了新型号,但把型号码翻译成型号类型的那份枚举还是旧的,翻译不出来的型号在建单之前就被挡掉了。
- 型号码清单是可变的配置,在配置中心改完立即对所有实例生效。
- 型号类型来自共享模型包里的枚举,跟着服务打包,要发版才会变。
- 识别服务上次发版时,共享包停在 2.9.5,包里的枚举只到老型号。
- 26、27 加进配置后,清单能读到这两个号,但枚举里没有对应项,翻译这一步失败。
- 失败之后,这两款柜子没有被算作可识别型号,后面的离线判断和建单都不执行,始终没有工单生成。
问题不在型号清单,也不在判断规则,而在两条发布线错位:配置在配置中心改,依赖在代码仓库升级,两边没有绑定。只改配置,表面上新型号已经支持,可真正决定能不能建单的是那份跟着服务走的枚举。翻译失败也没有任何提示:配置里明明有这两个号,程序却没有把它们变成可处理的类型,既不记日志也不告警,故障因此一直没有被察觉,直到有人单独反馈。配置生效不等于链路打通:让新型号出现在清单里只是一步,能翻译它的枚举还在旧版本里,建单就永远不会开始。
修复方向是把共享包升到包含新枚举的版本;更稳妥的是让“配置里有、代码里不认识”显式失败,记下型号码并告警,而不是当成无需处理跳过。其他服务是否也引用着同一份旧包,记录里没有说明。
错误代码
// 离线识别任务:把配置里的生效型号码翻译成型号类型,再给对应柜子建单(脱敏教学示例)
public void runOfflineDetect() {
List<Integer> enabledCodes = configClient.getIntList("cabinetTypeCode");
Set<CabinetTypeEnum> types = new HashSet<>();
for (Integer code : enabledCodes) {
// 为什么错:型号类型来自共享模型包里的枚举,而服务依赖的包
// 还是旧版本,里面没有 26、27,这一步翻译不出任何结果
CabinetTypeEnum type = CabinetTypeEnum.fromCode(code);
if (type == null) {
// 为什么错:翻译失败被当成“这个型号不用管”直接跳过,
// 不记录也不告警,新型号从此不进识别范围
continue;
}
types.add(type);
}
// 型号类型集合里根本没有 26、27,这两款柜子不会走到建单
cabinetRepository.listOffline(types)
.forEach(cabinet -> offlineOrderService.create(cabinet));
}
修复代码示例
要修的是两处:把共享包升级到 3.1.2,让枚举里存在 26、27;以及让翻译失败变得可见。版本升级是改依赖声明,不在示例里;下面演示第二处的写法,属于建议改动,不代表已提交的实现。
// 修复:共享包升级后枚举已含 26、27;翻译失败不再静默跳过
public void runOfflineDetect() {
List<Integer> enabledCodes = configClient.getIntList("cabinetTypeCode");
Set<CabinetTypeEnum> types = new HashSet<>();
for (Integer code : enabledCodes) {
CabinetTypeEnum type = CabinetTypeEnum.fromCode(code);
if (type == null) {
// 修复:配置里有、代码里不认识,说明配置与依赖版本不一致,
// 留下型号码并告警,不能再当成“无需处理”
log.error("cabinet type code not supported, code={}", code);
alarmClient.raise("cabinet-type-unsupported", code);
continue;
}
types.add(type);
}
cabinetRepository.listOffline(types)
.forEach(cabinet -> offlineOrderService.create(cabinet));
}
下次遇到这些场景要警惕
- 投放新硬件型号前:写配置的同时列出所有引用型号枚举的服务,逐个核对它们依赖的共享包版本;再拿一台新柜子的真实型号码跑一遍完整链路,看工单是否真的生成,不要只看配置里出现了这个型号。
- 用共享枚举翻译外部输入时:显式处理取不到值的情况,记录原始值并告警或转人工;枚举缺失和“这个型号本来就不处理”是两件事,混成一个分支会让配置与代码的错位长期隐形。
- 配置与代码分成两条发布线时:新增枚举值要按“配置先到、代码后到”的时间差设计中间态,中间态要么被拦住告警,要么有兜底分支,不能靠上线顺序碰运气。
- 新设备、新批次上线流程:把“通知下游系统适配”写成流程里明确的一步,指定接收人和确认方式;默认不通知就代表不支持,不要等业务反馈才发现。