复盘:项目接入APIG网关
1. 背景(Situation)
2023年7月中旬,领导分配了1个任务,具体的内容是项目需要在10月30日前完成公司十统一中的网关统一(公司所有的云服务的前端都需要通过公司统一的网关来访问自身服务的后端),项目现状是所有接口没有使用公司统一网关来管控
2. 任务(Task)
基于上述背景,并结合公司的代码可信原则(用同一份设计文稿来实现生成接口代码、生成测试用例、生成api文档、API网关注册),对任务进行扩展如下:
API网关注册自动化:完成整个项目所有后端微服务注册公司网关
API自动化测试用例请求链路改造:api自动化测试需要通过公司API网关去请求到项目服务,保证与现网真实用户请求一致
代码自动生成(可选):完成项目的Controller、Dto、Vo的代码生成
测试用例自动生成(可选):完成项目API的Alph用例自动生成(只生成边界值用例)
API文档自动生成(可选):满足公司API文档规范,完成项目的API文档输出至公司统一平台
3. 行动(Action)
行动主干:
- 分析任务
- 任务打样:以单个微服务打样,并输出指南
- 按照微服务粒度划分责任田
- 举行开工会:指南讲解、任务划分、现场答疑
- 中期进度审视:识别风险、解决问题
- 期末项目验收:验收整改质量,做好交付准备
3.1. 任务分析
问:为什么要完成上诉任务?
答:因为要完成十统一
问:为什么要完成十统一?
答:
利于公司对API所属云服务的质量、风险管控
规范云服务开发流程,设计先行。先进行需求分析API设计再开发。
问:别的项目组的最佳实践是怎样的?
答:实现思路为,通过公司的API设计平台,输出api yaml文档;API设计平台已对接自动化测试平台,API文档平台,以及代码仓
3.2. 任务打样
3.2.1. API网关自动注册
具体思路:
摸清从前端到微服务之间的请求链路
了解API网关的具体特性
1. 是否支持参数校验?如何关闭
2. 是否支持流水线自动化注册?
1. 自动化注册的输入(设计文稿)是什么?
2. 自动化注册需要什么审批?
3. 自动化注册允许哪些操作(增删改查等)?
4. 设计文稿如何管理?
5. 是否可以实现对某个具体的云服务授权?
是否需要打通网络?(链路加入API网关后,需要看API网关与其上下游节点网络是否打通)
详细请求链路图
自动化流水线示意图
3.2.2. API自动化测试用例请求链路改造
具体思路:
梳理API测试用例当前请求链路
设计新的请求链路。需要考虑的点:
1. API网关的网络与自动化测试平台网络是否联通?如何打通?
2. 测试平台如何取得调用API网关的权限
自动化测试平台请求链路示意图
这台Nginx主要解决执行机和API网关网络不通的问题,措施是在Nginx配置API网关的DNS解析。
问:为什么不在执行机上面配置DNS解析?
答:每次执行自动化用例,都是在执行机上面生成容器来执行,则需要每次在容器里面配置DNS,十分麻烦,且容易遗留
问:为什么不在执行机的宿主机配置DNS解析?
答:因为宿主机不属于我方项目组的资源管理范畴,涉及跨部门协作,且对方部门大概率不会为我方项目组配置,因为属于定制化,会增加维护难度
3.2.3. 代码自动生成
根据项目组架构师的指引,指出swagger具有代码生成功能。swagger代码生成的原理:输入API yaml设计文稿(设计文稿截止2023.8月,有swagger 2.0和open api3.x的规范),通过jar包内部的模版,输出对应的代码。
所以整个生成代码的流程是:
各个微服务启动,获取swagger的yaml文档
利用yaml文档,使用maven插件去生成对应的controller、dto、vo代码
但是项目现状是使用的swagger3.0的规范,公司内部论坛并无适用于3.x规范的插件,只有许多基于Swagger-codegen官方插件改造后,适用于Swagger 2.0规范的生成java代码Maven插件;
问:为什么不采用Swagger-codegen的官方适用于3.0的插件呢?
答:因为官方插件截止2023.8月,并不支持一些特性,例如:
- 不支持类、方法、字段增加自定义注解
- 不支持类、方法、字段设置为自定义类型
- 不支持方法的返回类型为自定义类型
- 不支持@Length等部分参数校验注解
当前的具体思路:
方法1:项目的swagger版本降级为2.0规范(2.0版本有安全漏洞,不允许降级)
方法2:自己写插件。基于Swagger-codegen自行扩展特性,来满足项目需求。(人力投入太大,投入和产出不成正比)
方法3:寻找公司支持3.0规范的Maven插件(最终在架构师以及主管的帮助下,找到公司1个支持3.0的产品,但是特性上还不足以支撑项目,最后以需求方向他们提出需求。实现后再进行代码生成)
代码生成流水线示意图
3.2.4. 测试用例自动生成
api设计平台已对接自动化测试平台,只需按照指南配置相关参数即可实现
对接示意图
3.2.5. API文档自动生成
API设计平台已对接API文档平台,按需配置即可
对接示意图
4. 结果(Result)
- API网关注册自动化
- API自动化测试用例请求链路改造
- 代码自动生成(可选)
- 测试用例自动生成(可选)
- API文档自动生成(可选)