发生了什么

“车型使能信息”是一条配置记录,说明某个车型支持哪些功能模块:后台按模块勾选,存下来是一组枚举值,每个值代表一种模块能力。这组值不只后台在用,商户端也在用——商户端把每个枚举值映射成车辆管理页面上的一个功能入口,比如“车辆控制”按钮。所以一个枚举值同时承担两件事:后台的勾选项,以及客户端的一个页面功能。

正常流程是这样走完的:运营在后台给某个车型勾选模块,商户端打开车辆管理页时读到这组枚举值,按事先约定好的“枚举值到功能入口”的映射,逐个把按钮渲染到页面上,商户点进去使用对应功能。约定里原来只有 1 到 6 这六个值。

这一次的起因是一个紧急需求:7 月 10 日提出,要在车型使能信息里新增“电量模块”,原计划 7 月 17 日发布,枚举值因此从 1 到 6 扩到 7。需求范围只到后台和服务端,没有包含商户端。7 月 16 日 21 点服务就发完了,随后把 7 加进了枚举——加值只是后台的一次配置操作,商户端不会因此更新,它的映射只跟 App 版本走。

服务发完、枚举加上 7 之后,商户端读到的列表里多了一个 7。商户端本地这份映射仍停在旧版本,只有 1 到 6,查 7 时取不到任何处理逻辑,代码没有判空就直接拿这个空值去用,抛了空指针。页面渲染在这里中断,整个车辆管理页停在当前状态,再点“车辆控制”按钮也没有反应。配置里没有 7 的车型走不到这段逻辑,页面照常。7 月 17 日产品同学发现问题后同步过来,处理方式是商户端兼容未约定的枚举值,紧急修复发版。记录中的影响描述是“未影响正常商户”,具体涉及多少商户、多少车辆没有写。

本质

一句话:一个多端共用的枚举值被后台单方面加了新成员,商户端还按旧约定只认识 1 到 6,遇到 7 取不到处理逻辑却直接把空值当结果用掉,一处空指针把整个页面带停。

  1. 后台保存使能信息时,写进去的是枚举值本身,而不是功能名称;商户端拿到这组值后,靠本地约定查出每个值对应哪个页面、哪个处理逻辑。
  2. 商户端不认识“电量模块”这个概念,它只认识数字。哪个数字对应哪个页面、哪个处理类,写死在客户端的一份映射里,这份映射只能跟着 App 版本发布才会变。
  3. 这次改的是后台和服务端,后台一保存,新数据立刻带上 7;客户端没有发版,映射仍然只到 6。两端对同一组值的认识从此不一致。
  4. 商户端遍历返回值时,用 7 去映射里取值,取到空;紧接着取这个空值的标题、挂它的点击事件,抛空指针。异常发生在渲染按钮的那一层,后面的按钮没有渲染出来,已经在页面上的按钮也失去响应。
  5. 于是商户看到的是:页面停住,点“车辆控制”没有任何反应。这不是接口报错,也不是数据没下发,而是客户端自己在一个空值上崩了一次。

容易漏掉的地方有两处。一是影响面判断:加枚举值时,判断依据是“本期需求有没有涉及商户端”,而“使能信息商户端也在读”这条依赖不在影响面清单里,于是只改了后台,也没人按“新增枚举要通知所有读取方”的约定去提客户端需求。二是客户端兜底:不认识的枚举值应当被跳过或显示为不可用,而不是让整个页面抛异常;一条新增值不应该有能力让页面整体失效。后台能配出来的值,不等于每个使用方都认识;共享枚举每加一个成员,都是一次跨端契约变更,而不是后台多点一个勾。

错误代码

// 车型使能信息:一组枚举值,每个值代表车型支持的一个功能模块(脱敏教学示例)
public class ModelEnablement {
    private List<Integer> moduleCodes;   // 后台配置,本期从 [1..6] 变成 [1..7]
}

// 商户端:本地维护“枚举值到功能入口”的映射,只能随 App 版本发布才会变
public class VehiclePage {
    private final Map<Integer, ModuleEntry> entries = new HashMap<>();

    VehiclePage() {
        entries.put(1, new ModuleEntry("车辆控制", this::openControl));
        entries.put(2, new ModuleEntry("车辆定位", this::openLocation));
        // ……只登记到 6,后台本期新增的 7 在这里没有对应实现
    }

    void render(List<Integer> moduleCodes) {
        for (Integer code : moduleCodes) {
            // 为什么错:7 不在映射里,get 返回 null,代码却没有判空
            ModuleEntry entry = entries.get(code);
            // 为什么错:直接拿空值取标题、挂点击事件,抛空指针;
            // 渲染在这一步中断,整页停住,车辆控制按钮再点也无响应
            views.add(buildButton(entry.title(), entry.onClick()));
        }
    }
}

修复代码示例

// 沿用同一个页面与同一组枚举值,只改“取不到实现”之后怎么处理
public class VehiclePage {

    void render(List<Integer> moduleCodes) {
        for (Integer code : moduleCodes) {
            ModuleEntry entry = entries.get(code);
            if (entry == null) {
                // 只改与缺陷有关的部分:不认识的值跳过并留痕,其余模块照常渲染
                log.warn("unknown module code skipped, code={}", code);
                continue;
            }
            try {
                views.add(buildButton(entry.title(), entry.onClick()));
            } catch (RuntimeException e) {
                // 单个入口出错也不能让整页失去响应
                log.error("module entry render failed, code={}", code, e);
            }
        }
    }

    // 若该模块必须出现在页面上,登记占位入口,点进去提示升级,属于兜底展示
    { entries.put(7, ModuleEntry.placeholder("电量", "请升级到最新版本后使用")); }
}

两段代码改的是同一处:把“取到空值就直接使用”改成“取不到就跳过、单个入口出错不影响整页”。代码为脱敏教学示例,用于解释错误与修复思路,不代表实际项目源码或已上线实现;类名、方法名与枚举值均为示意。

下次遇到这些场景要警惕

  • 要给一个多端共用的枚举加值时:先把读取这个字段的端全部列出来(后台、服务端、App、小程序、对外接口各算一个),逐个确认是否需要同步发版、谁先谁后;只改其中一端,就要给中间态留兜底。
  • 客户端用枚举值决定页面功能时:构造一条带未知值(比如 7 或 999)的数据,在旧版本客户端上跑一遍,观察是“只少一个入口”还是“整页停住”;只要整页受影响,就说明兜底缺失。
  • 需求范围写着“不涉及某端”时:核对该端是否读取本次改动的字段或枚举,尤其是配置类数据;被改的字段被谁读,比需求写着涉及谁更可靠。
  • 页面点按钮没反应、日志里有空指针时:先定位取空的那一行,在取用之前加判断和降级展示止血,再回头理清这个值的约定、通知机制和发布顺序,避免下次又靠客户端紧急发版收场。