一种基于编译期类型契约的接口一致性校验方法及装置与流程
本技术涉及接口一致性校验,尤其涉及一种基于编译期类型契约的接口一致性校验方法及装置。
背景技术:
1、在前后端分离的web项目开发模式中,前端与后端开发人员通过接口文档约定数据交互的格式与类型。接口文档通常采用openapi规范进行描述,并以yaml或json格式存储在本地文件或远程服务器上供团队成员查阅,对接口一致性进行有效校验是项目正常开发的前提。
2、现有接口一致性校验方法缺少可被编译期校验引用的结构化类型基准数据,前端无法精确感知后端接口是否发生变更;未将接口契约转化为编译器可执行的静态类型约束,导致问题发现严重滞后;接口文档发生变更时,断言文件无法自动同步更新;缺少项目构建终止的强制约束机制,无法在编译阶段阻断问题;类型不一致时产生的错误信息晦涩难懂,排查和修复成本高昂,导致前后端接口一致性校验的效率和可靠性不高,影响项目的正常开发。
技术实现思路
1、为了解决上述问题,第一方面,本发明提供了一种基于编译期类型契约的接口一致性校验方法,包括:
2、在项目构建准备阶段获取项目的初始接口文档源,根据初始接口文档源进行表达转换、哈希值计算和指纹映射构建,获得初始标准化类型表达式、初始类型指纹哈希值和初始指纹映射表;
3、根据初始标准化类型表达式和初始类型指纹哈希值,进行编译期类型断言结构的构造,生成初始断言文件;
4、在项目构建进行阶段获取项目的更新接口文档源,根据更新接口文档源获得对应的更新标准化类型表达式、更新类型指纹哈希值和更新指纹映射表;
5、将更新指纹映射表与初始指纹映射表进行指纹比对,获得指纹比对结果;当指纹比对结果为不一致时,根据更新标准化类型表达式和更新类型指纹哈希值,采用与初始断言文件相同的过程生成更新断言文件;
6、调用typescript编译器对更新断言文件进行编译检查,获得编译结果;当编译结果为不通过时,根据初始标准化类型表达式和更新标准化类型表达式进行语义比对,生成可读错误报告并终止项目构建。
7、在一实施例中,根据初始接口文档源进行表达转换、哈希值计算和指纹映射构建,包括:
8、识别初始接口文档源的文档格式类型,从预置的适配器注册表中选取与文档格式类型对应的解析适配器,调用解析适配器将初始接口文档源反序列化为接口描述对象列表,接口描述对象列表包括每个接口的接口路径、请求方法、请求参数列表和响应体结构定义;
9、根据请求参数列表和响应体结构定义构建类型定义对象,提取类型定义对象中的ref引用位置,将ref引用位置替换为初始接口文档源中的实际类型定义,获得内联定义;
10、提取内联定义的后端类型描述,根据预置的类型映射规则库将后端类型描述转换为每个接口的初始标准化类型表达式;
11、将初始标准化类型表达式、接口路径和请求方法序列化为json字符串,通过哈希算法将json字符串转化为初始类型指纹哈希值;
12、获取每个接口的接口标识,以接口标识为键构建键集合,以键对应的初始类型指纹哈希值为值构建值集合,根据键集合和值集合构建初始指纹映射表。
13、在一实施例中,根据初始标准化类型表达式和初始类型指纹哈希值,进行编译期类型断言结构的构造,生成初始断言文件,包括:
14、根据初始标准化类型表达式生成每个接口的响应数据类型,根据初始标准化类型表达式构造每个接口的预期类型形状;
15、构建类型兼容性校验逻辑,用于检验响应数据类型与预期类型形状是否满足双向类型兼容性条件;
16、构造初步类型级断言结果,将初始类型指纹哈希值作为编译期基准常量嵌入初步类型级断言结果中,获得目标类型级断言结果;
17、当类型兼容性校验逻辑为满足时,目标类型级断言结果为通过态;当类型兼容性校验逻辑为不满足时,目标类型级断言结果为携带错误描述信息的失败态;
18、由类型兼容性校验逻辑和目标类型级断言结果构成初始断言文件。
19、在一实施例中,将更新指纹映射表与初始指纹映射表进行指纹比对,获得指纹比对结果,包括:
20、获取更新指纹映射表的更新键集合,以及更新键集合中每个键对应的更新类型指纹哈希值;
21、获取初始指纹映射表的初始键集合,以及初始键集合中每个键对应的初始类型指纹哈希值;
22、若更新键集合与初始键集合的大小相同,并且所有键对应的更新类型指纹哈希值与初始类型指纹哈希值均相同,则指纹比对结果判定为一致,否则指纹比对结果判定为不一致。
23、在一实施例中,调用typescript编译器对更新断言文件进行编译检查,获得编译结果,包括:
24、获取项目业务代码文件,将更新断言文件和项目业务代码文件输入typescript编译器进行编译,生成诊断信息集合;
25、当诊断信息集合为空时,判定编译结果为通过;当诊断信息集合不为空时,判定编译结果为不通过。
26、在一实施例中,根据初始标准化类型表达式和更新标准化类型表达式进行语义比对,生成可读错误报告,包括:
27、将初始标准化类型表达式与更新标准化类型表达式不相同的接口标识作为变更接口;
28、对变更接口的初始标准化类型表达式和更新标准化类型表达式分别进行结构化解析,获得初始结构化类型描述和更新结构化类型描述;
29、对初始结构化类型描述和更新结构化类型描述,进行基于字段路径的差异识别,获得类型差异;
30、根据类型差异生成可读错误报告,可读错误报告包括差异类型标识、接口定位信息、字段路径和对比内容。
31、在一实施例中,对初始结构化类型描述和更新结构化类型描述,进行基于字段路径的差异识别,获得类型差异,包括:
32、以字段路径为单位,对初始结构化类型描述和更新结构化类型描述进行递归遍历,逐一判定每个字段路径的类型差异;
33、若字段路径仅存在于更新结构化类型描述中,则类型差异判定为新增类型;
34、若字段路径仅存在于初始结构化类型描述中,则类型差异判定为删除类型;
35、若字段路径同时存在于初始结构化类型描述和更新结构化类型描述中,但类型定义不相同,则类型差异判定为类型变更;
36、若字段路径同时存在于初始结构化类型描述和更新结构化类型描述中,类型定义相同但属性约束不相同,则类型差异判定为约束变更。
37、第二方面,本发明提供了一种基于编译期类型契约的接口一致性校验装置,用于实现所述的基于编译期类型契约的接口一致性校验方法,所述装置包括:
38、初始接口文档源转化模块,用于在项目构建准备阶段获取项目的初始接口文档源,根据初始接口文档源进行表达转换、哈希值计算和指纹映射构建,获得初始标准化类型表达式、初始类型指纹哈希值和初始指纹映射表;
39、初始断言文件获取模块,用于根据初始标准化类型表达式和初始类型指纹哈希值,进行编译期类型断言结构的构造,生成初始断言文件;
40、更新接口文档源转化模块,用于在项目构建进行阶段获取项目的更新接口文档源,根据更新接口文档源获得对应的更新标准化类型表达式、更新类型指纹哈希值和更新指纹映射表;
41、更新断言文件获取模块,用于将更新指纹映射表与初始指纹映射表进行指纹比对,获得指纹比对结果;当指纹比对结果为不一致时,根据更新标准化类型表达式和更新类型指纹哈希值,采用与初始断言文件相同的过程生成更新断言文件;
42、可读错误报告获取模块,用于调用typescript编译器对更新断言文件进行编译检查,获得编译结果;当编译结果为不通过时,根据初始标准化类型表达式和更新标准化类型表达式进行语义比对,生成可读错误报告并终止项目构建。
43、第三方面,本发明提供了一种电子设备,包括存储器、处理器及存储在所述存储器上并可在所述处理器上运行的计算机程序,所述处理器执行所述程序时实现所述的基于编译期类型契约的接口一致性校验方法。
44、第四方面,本发明提供了一种非暂态计算机可读存储介质,其上存储有计算机程序,所述计算机程序被处理器执行时实现所述的基于编译期类型契约的接口一致性校验方法。
45、本发明具有以下有益效果:
46、1、通过在项目构建准备阶段构建初始接口文档源的标准化类型表达式、类型指纹哈希值和初始指纹映射表,为项目构建进行阶段的自动化接口校验奠定了数据基础,并实现了接口变更的精确感知;通过初始标准化类型表达式和初始类型指纹哈希值构造断言文件,将接口契约转化为编译器可执行的静态类型约束,使问题发现从运行时提前至编译时;通过在项目构建进行阶段自动拉取更新接口文档源并执行指纹比对,在文档实际发生变更时触发断言文件更新,实现了文档与代码的实时同步;将编译不通过作为项目构建终止的强制约束机制,在编译阶段即可阻断问题;通过初始标准化类型表达式和更新标准化类型表达式的语义比对生成可读错误报告,直接定位变更的具体接口、字段路径及变更前后的类型差异,显著提升了前后端接口一致性校验的效率和可靠性。
47、2、通过构建检验响应数据类型与预期类型形状是否满足双向类型兼容性条件的类型兼容性校验逻辑,并基于该校验逻辑构造目标类型级断言结果,将接口文档的契约约束转化为由编译器强制执行的类型规则,从而将接口类型一致性问题从依赖人工感知的运行时阶段提前至由编译器强制保障的编译阶段,彻底杜绝了因类型不一致而引发的线上故障;通过将初始类型指纹哈希值作为编译期基准常量嵌入断言结果中,使断言结果与后端接口文档的特定版本形成强绑定关系,每次构建时均可基于该基准进行精准校验,避免了因类型定义缓存过期而导致的前后端类型偏离;断言文件独立于业务代码且仅包含类型断言逻辑而无运行时代码,实现了零运行时开销的类型安全保障;错误描述信息包含接口的请求方法和路径,使开发者无需额外分析即可在编译阶段精准定位发生契约冲突的具体接口,大幅降低了问题排查和修复成本。
48、3、通过结构化解析初始标准化类型表达式与更新标准化类型表达式获得新旧结构化类型描述,并以字段路径为单位进行递归遍历,从新增类型、删除类型、类型变更和约束变更四个维度系统性地识别类型差异,在此基础上生成包含差异类型标识、接口定位信息、字段路径和对比内容的可读错误报告,将typescript编译器产生的晦涩错误信息转换为开发者可直接阅读和理解的业务语言,使开发者无需额外分析即可立即明确问题根源并执行针对性修复,显著提升了问题的定位效率。
版权声明:本站专利文献数据主要来源于国家知识产权局等公开渠道,由 技术新讯 进行整理汇编。页面设计及数据汇编的著作权归本站所有。全部内容仅供个人学习、科研评估与技术交流参考,严禁用于任何商业用途(包括但不限于直接生产制造、技术转让、倒卖数据等)。
免责条款:专利技术具有时效性,本站不对资料的绝对准确性、完整性和可实施性提供任何明示或暗示的担保。因参考本站内容造成的直接或间接损失,本站不承担相关法律责任。若您认为本站内容有侵权问题,请及时提供权属证明与我们联系,本站将在核实后依法处理。反馈意见:yyfuon@163.com