发生了什么

换电地图是用户在客户端里查看附近换电柜的页面:地图上每个点位是一台电柜,点开一台电柜,会进入这台电柜的格口和电池列表。地图上方有筛选条件,其中一项是“业务线”;选中哪条业务线,地图和后面的列表就只显示这条业务线的电柜。

这次做了“换电地图展示优化”,要把地图筛选页从原生页面改成 H5,并要求用户进入地图后默认只看到某条业务线的电柜。为此,客户端请求电柜列表时要带上一份默认筛选条件。这份条件不是每次请求现拼,而是放在客户端本地缓存里,由两端共用:APP 初始化时写入一份默认条件,H5 筛选页在用户选中条件后覆盖写一份;APP 进入地图时读取这份缓存,点电柜进入列表时再把条件传给电柜列表。一条完整的筛选项,除了字段名、标题、是否选中,还要带一个“展示名称”,也就是这条业务线的名称。

上线后,灰度范围内的 Android 用户进入换电地图,点击地图上的电柜,页面还没打开就闪退。崩溃信息是一个声明为非空的参数 fieldName 被传入了空值。排查确认:APP 初始化写默认条件时漏了 fieldName,H5 筛选页选中条件后写缓存也没带这个字段,缓存里的筛选项因此缺少展示名称;电柜列表把它解析成 Java bean 时按“一定有值”处理,抛出空指针,页面直接退出。从筛选页选任意条件、再点电柜,也会走同一条崩溃路径。

本质

一句话:这份本地缓存实际上是一份跨端契约,两个写入方都漏了同一个必填字段,读取方却按“一定有值”来解析。

  1. 正常流程:筛选项按固定结构存成 JSON,字段名标识要过滤哪个字段,“展示名称”用于页面显示当前选中的条件。写入方把字段写全,读取方按结构解析,列表再按条件请求电柜。

  2. 这次改动新增了“默认条件”这条路径:APP 启动时组装一份业务线条件,异步写进本地缓存,界面不等它写完。异步本身不致命,问题是这份条件里没有 fieldName。

  3. H5 筛选页是第二个写入方。用户在这里选中条件后,它把条件写回同一份缓存,同样没有写 fieldName。两份数据来源不同,缺的是同一个字段。

  4. 用户点电柜时,APP 把缓存里的条件传给电柜列表,列表把它解析成 bean。这个 bean 把 fieldName 声明为非空,客户端框架在构造对象时做非空校验,拿到空值就抛异常。写缓存时少一个字段,读缓存时就成了空指针。

  5. 异常发生在页面初始化的过程中,没有在这里被捕获,所以用户看到的是闪退,而不是提示。缓存里是哪条路径写的、写入有没有完成,决定了传给列表的条件是什么,所以现象是概率性的。

  6. 影响范围是灰度范围内的 Android 用户,进入地图点电柜、或从筛选页选条件后点电柜都会遇到。修复方向是两条写入路径都补齐 fieldName:APP 初始化写默认条件时补上,H5 筛选页选中后也把它写进缓存;读取端对缺失字段做兜底属于加固,可以避免已经写坏的老缓存继续触发崩溃。修复上线与验证情况,记录没有说明。

代码为脱敏教学示例,用于解释错误与修复思路,不代表实际项目源码或已上线实现。

错误代码

// APP 启动时异步写入地图默认筛选条件(脱敏教学示例)
public void writeDefaultFilter(String businessLineName) {
    FilterItem item = new FilterItem();
    item.fieldValue = "5";
    item.select = true;
    // 为什么错:fieldName 是列表解析时要求必填的字段,这里没有赋值就落盘
    FilterCondition condition = new FilterCondition("bizLineList", "业务线", 2,
            Collections.singletonList(item));
    // 异步写:用户点电柜时,缓存里可能已经是这份缺字段的条件
    cache.writeAsync("map_filter", Json.encode(condition));
}

// 点电柜进列表:把缓存里的条件转成页面用的 bean(脱敏教学示例)
public final class FilterItemBean {
    private final String fieldName;

    public FilterItemBean(FilterItem item) {
        // 为什么错:这里按 fieldName 一定存在来构造,
        // 缓存里漏写该字段时直接抛空指针,异常冲出初始化就闪退
        this.fieldName = Objects.requireNonNull(item.fieldName, "fieldName");
    }
}

修复代码示例

// 修复:两条写入路径都经过同一个组装方法,fieldName 必填(脱敏教学示例)
public final class FilterItems {
    public static FilterItem of(String value, String name, boolean selected) {
        if (name == null || name.trim().isEmpty()) {
            throw new IllegalArgumentException("筛选项缺少 fieldName: " + value);
        }
        FilterItem item = new FilterItem();
        item.fieldValue = value;
        item.fieldName = name;
        item.select = selected;
        return item;
    }
}
// APP 初始化:默认条件补齐展示名称后写入
public void writeDefaultFilter(String businessLineName) {
    FilterItem item = FilterItems.of("5", businessLineName, true);
    cache.writeAsync("map_filter", Json.encode(new FilterCondition(
            "bizLineList", "业务线", 2, Collections.singletonList(item))));
}
// H5 筛选页选中后:同样先补齐字段再写入同一份缓存
public void onFilterSelected(FilterItem fromH5) {
    FilterItem checked = FilterItems.of(fromH5.fieldValue, fromH5.fieldName, fromH5.select);
    cache.write("map_filter", Json.encode(new FilterCondition(
            "bizLineList", "业务线", 2, Collections.singletonList(checked))));
}

下次遇到这些场景要警惕

  • 把筛选条件、定位信息这类数据放进本地缓存给多端共用时:先列出所有写入方(APP 初始化、H5 页面、分享或深链入口),逐个核对写出的字段集合是否一致;在全新安装、清缓存、先开 H5 再开 APP 等顺序下各进入一次,看读取端能否正常解析。
  • 页面从原生改成 H5、两端共用同一份缓存时:先约定字段结构,再检查“默认值”和“用户手选”两种来源的字段是否一样;只测其中一种来源,会漏掉另一条写入路径。
  • 读取端把字段声明为非空时:构造读取模型前先确认这个字段由谁保证一定写;如果历史缓存可能缺字段,要能降级(用编号回填名称或丢弃该条件),不要直接抛异常。
  • 点击列表项或进入下一页时闪退:先把崩溃日志里的字段名对到缓存结构,确认是写入缺失还是读取越界,再决定修写入端还是读取端;只修一端,老缓存仍会触发。