更换文档组件时,可以保留一份旧版公文系统,用它接收新组件的响应。这里最值得分开试的,是两种看起来都像“只多了一点内容”的改动。服务端可以多返回一个可选的说明字段,也可以在原有的保存状态字段里返回一种新状态。前者考验旧程序怎样读取字段,后者可能改变一次公文流转的结果。
假设旧系统在收到保存回执后,根据状态决定保留待办、通知经办人,还是把公文送往下一环节。验收人员关心的就不只是接口能否连通。他们还需要知道,同一份旧程序收到它从未见过的结果时,是否会显示“已保存”,又是否真的推进了流程。下面的字段、状态与公文均为合成样例,可据此设计项目测试。
先固定原来会做决定的那一端
取出实际部署过的旧调用方版本,连同它使用的客户端库、字段映射和流程规则一起登记。若测试时重新生成了一套认识新字段和新状态的客户端,得到的就是另一组软件组合,回答不了旧系统在切换当天会怎样处理。先让旧调用方处理一份已知回执,留下它实际读取的值、界面提示和后续动作,作为比较起点。
Google 的 AIP-180 将兼容性区分为源代码、传输和业务语义三个方面。这个区分有助于定位问题。升级客户端库可能影响编译,服务端响应可能影响旧模型的解析,而解析之后的状态判断又可能改变流程。该指南有其协议和调用方假设,项目的通过条件仍应写进本次接口约定。参阅 AIP-180 兼容性指南。
第一次只增加一项说明
设旧回执中有一个 saveState 字段,值为 stored 时,旧流程会在满足原有审批和权限条件后进入下一步。第一份新样本保留这个值,只增加可选字段 displayNote。开发人员应先问清接口是否允许扩展响应,再观察旧调用方在哪个环节处理了说明字段。
如果旧模型按约定忽略附加信息,验收记录就写“忽略了说明,原状态和动作保持一致”。如果严格解析器在遇到未识别字段时直接拒绝整份响应,就记录具体失败位置。这时流程还没走到状态判断,排查方向应是接口约定、旧模型及其真实配置。微软 Azure 的 API 设计指南同时要求服务端考虑旧客户端在请求里省略新增字段的情形,收发两个方向应分别验证。参阅 Azure 微服务 API 设计指南。
第二次只改变已知字段的值
恢复到原来那份响应,这次保持字段集合不变,让 saveState 返回假设的新值 awaitingCheck。它表示服务端还有一步内部核对。旧程序认识字段名,却没有处理这个值的业务分支。此时应沿着值在程序里的实际走向取证。
一种可能是旧客户端把状态限定为几个固定选项,读取新值时就产生错误。另一种可能是它接收了字符串,但流程规则只有“失败”和“其他”两条路径,于是把新状态送进了原来的成功分支。两种情形对应不同的修改责任。第一种要查客户端如何解码,第二种要查业务规则如何做决定。给解析器增加一个可接受值,只解决了前一步。
可扩展枚举需要服务提供方和使用方共同定义读法。Microsoft Graph 的设计模式预留了 unknownFutureValue,并约定客户端如何声明愿意接收新增成员。该模式还分别规定读取与写入时的处理。核验其他组件时,应查它自己对未知值和版本演进的说明,再决定需要适配哪个旧客户端。参阅 Microsoft Graph 可扩展枚举设计模式。
旧客户端库也值得核对。微软的 .NET 枚举设计资料曾提醒,已经发布的程序可能无法正确处理接口新增的返回值。该页摘录自 2008 年的框架指南,这里仅用它说明旧程序的已有分支可能成为迁移约束。实际项目仍须逐一确定所用语言、库版本与业务约定。参阅 .NET 枚举设计指南的历史说明。
把“未识别”留在可以处理的位置
在这个公文样例里,若旧调用方无法确认保存是否完成,可让经办人看到“状态待核对”,保留待办并留下可查询的回执编号。是否需要等待后续通知、按正式接口查询,或由实施人员处理,应由该项目明确。尤其要查看后台任务和消息通知,因为页面保留在原处时,后台仍有可能已经推进了流程。
未知值本身没有赋予批准、写入或继续流转的权限。若正式接口明确约定返回值是封闭集合,收到集合外的值就应按契约异常处理。如果约定允许增加成员,则应验证旧程序的保留、提示与降级路径。响应读取可以按扩展规则忽略可选信息,但向服务端提交修改时,字段、权限和允许的状态转换仍须按写入契约校验。
给每份测试回执留下一条可复查的结果
| 样本变化 | 记录什么 | 核对哪项动作 |
|---|---|---|
| 保留原回执 | 解析结果和原状态 | 原流程按既有条件执行 |
| 只多一个可选说明 | 是否接受响应,原状态是否保留 | 说明字段是否意外改变流转 |
| 原字段返回新状态 | 解析错误或未知值进入的分支 | 是否误报保存、误发通知或推进审批 |
在获准的隔离环境中,分别用相同的旧调用方和初始公文状态执行三次。测试人员可在每次前恢复合成样本,并为回执、业务记录和操作日志保留关联编号。最后读回公文版本与流程节点。若旧程序还会把读取的对象写回服务端,应另查它是否会删去无法识别的字段或覆盖新状态。
结果应精确到某个旧客户端版本、某类响应以及实际观察到的动作。历史公文的版式、原有二次开发和其他接口仍各有验收样本。准备评估石墨办公文档中台私有部署时,可以带上旧接口说明、调用方版本及一份去除业务数据的回执,围绕原有流程的关键分支预约架构演示。也可以先看私有化部署方案,了解部署形态与交付范围。