发生了什么
一线人员会到候选位置做现场勘察,确认这里能不能布点,勘察结论要填进手机 App 里的「点位勘探」页面提交,后台拿到这份结果才能继续推进这个点位。这个 App 里的页面资源不是每次打开都从服务端取最新版,而是打成「离线包」预置在手机上或提前下载到本地,App 启动时决定用哪一版页面。也就是说,一台手机上跑的是哪版页面,取决于这台设备有没有下载并激活新包,和后台当天发布到哪一版没有直接关系。
后台这次给点位勘探的提交接口加了一个新的请求字段,并把它设成必填,先在一个城市灰度开放。灰度只做在后端,客户端页面仍按原来的节奏发离线包。问题出在还没拿到新包的设备上:页面还是旧资源,提交请求里根本不会带上这个新字段。
结果是一线点开点位勘探、提交走到接口时报错,页面弹出错误提示,勘察提交不下去。能不能复现取决于设备上生效的是哪版页面,不看城市,所以同城别的设备未必出现同样现象,排查时很容易先怀疑是页面故障或用户填错。现场的处理是让这名人员彻底退出 App 再重新进入,App 重新选择并激活了已下载的新包,页面换成新资源,提交恢复正常。
本质
正常情况下,接口新增字段需要所有调用方同步升级。但离线包把「页面版本」从服务端发布里拆了出去:后端发一版,各台手机还要各自下载、激活,中间必然有一段两者不同步的窗口。这次后端把新字段设成必填,等于假设这个窗口不存在。
出错的一步在参数校验的位置:服务端把缺失的新字段当成非法输入直接拒绝,请求里缺这个字段,不是用户填错,而是旧页面根本不知道有这个字段。校验本身没错,错在它被放在了一个旧页面还在使用的接口上,没有给旧版本留任何过渡。
接下来就是一条顺着走完的链:旧页面按旧契约组装请求,请求里没有新字段;服务端参数校验不通过,接口返回失败;页面把失败原因当普通错误提示弹出来,提示里通常只有字段名或「参数不能为空」这类技术描述,一线看不出该做什么,只能报「页面坏了」。灰度范围按城市开,但设备上的包版本和城市无关,这也是为什么同一功能有人正常、有人报错。
处置上,退出重进只是让个别设备命中新包,属于临时恢复,不是对所有设备的修复。后端要不要继续做兼容善后,取决于前端埋点里旧包还有多少占比;同时要把离线包版本规范定下来。代码修复是否已经上线、是否验证过,记录里没有说明,修复方向是按上面这条思路走。
错误代码
下面用一段后端校验代码说明,为什么版本不同步时旧页面一定会被拦下来。
// 示意:类名、字段名均为脱敏示意,不代表实际项目代码
public class PointSurveyRequest {
private String siteId;
// 这次新增的字段,直接标成必填
@NotBlank(message = "点位类型不能为空") // 为什么错:旧离线包里的页面根本不会传这个字段
private String siteType;
}
@RestController
public class PointSurveyController {
@PostMapping("/survey/submit")
public Result submit(@Valid @RequestBody PointSurveyRequest req) {
// 缺字段直接抛校验异常,旧客户端拿到 400,页面只能弹出通用提示
return surveyService.save(req);
}
}
修复代码示例
修复要同时做两件事:让旧包在过渡期能被识别出来,并给出能照着做的提示;对确实缺失的字段由服务端兜底,而不是一律拒绝。
// 沿用同一套对象,只改与缺陷有关的部分
public class PointSurveyRequest {
private String siteId;
private String siteType; // 改成非必填,过渡期内允许缺失
private String bundleVersion; // 客户端声明自己当前生效的离线包版本
}
@PostMapping("/survey/submit")
public Result submit(@RequestBody PointSurveyRequest req) {
if (bundleOutdated(req.getBundleVersion())) { // 没带版本号的旧包同样按过期处理
// 旧包补不上新字段,先给可执行的提示,而不是让用户去撞参数校验
return Result.fail("CLIENT_OUTDATED", "当前页面版本过旧,请退出应用后重新进入");
}
if (req.getSiteType() == null) {
// 版本达标却仍缺字段时兜底,并按版本计数,攒够数据再决定关闭兼容
req.setSiteType(SiteType.UNKNOWN);
metrics.count("survey.old_bundle", req.getBundleVersion());
}
return surveyService.save(req);
}
下次遇到这些场景要警惕
- 给接口加必填字段之前,先查前端埋点里客户端当前生效的页面版本分布。只要还有旧版本在用,就不要把字段设成硬必填:要么服务端给兜底值,要么设一个最低版本门槛,让旧版本收到能照做的提示。
- 灰度按城市或网点开放时,不要把灰度范围当成客户端版本范围。发布验证要专门留一台没更新过页面的设备,完整走一遍提交,只测自己刚装好的那台等于没测兼容性。
- 报错文案要能指向版本。参数校验的通用提示会让人以为是填错或页面坏了,遇到页面版本相关的问题,返回「请退出应用后重新进入」这类可执行动作,比只返回字段名有用得多。
- 收口时看数据。兼容窗口内持续观察旧包请求占比,降到位再关闭兼容;把「这个页面的发布方式是离线包、内置还是网页」写进接口变更检查清单,下次加字段时能第一时间想到版本这层。