接口列表功能用于维护聚合接口,聚合接口从外部调用方角度看是一个简单的接口,通过入参请求获取响应结果,内部实现会调用多个底层后端服务,将多个调用结果聚合转换成外部调用方想要的数据格式,更多详情请查看服务编排介绍,下面介绍接口列表功能的操作。
菜单位置:服务编排 接口列表。点击菜单后进入接口列表页面,如图所示。
聚合接口的入参大部分是通过JSON Schema来定义的,下面先简单地介绍下JSON Schema。
作为普通用户,我们并不需要去了解JSON Schema的规范内容,只要能够构建JSON Sche华体会股份有限公司ma即可。
要理解JSON Schema,首先要理解什么是JSON。JSON是JavaScript Object Notation的缩写,一种简单的数据交换格式。最初JSON是基于JavaScript,广泛的应用于万维网。由于其简洁和清晰的层次结构、易于人阅读等特性,使得越来越多的场景下被采用。
以上两个例子都是有效的JSON数据,包含一样的有效信息,但是当程序读取数据时,需要准确的知道数据是怎么组织的,比如哪些字段是必须,这些字段是什么类型。这时候JSON Schema就派上用场了,看以下JSON Schema例子:
用以上JSON Schema验证第一个例子时,验证失败;但是第二个例子验证通过。
JSON Schema本身也是通过JSON编写,其本身也是数据,不是一个计算机程序,只是一种“描述其它数据的结构”的声明格式。这既是长处,也是弱点,JSON Schema可以简洁地描述数据的结构并且自动验证数据,但是对于数据元素间的关系表达就力不能及了。

title字段用于验证失败时提示使用,例如请求接口时没传请求头时会提示“请求头参数1不能为空”(错误提示输出通过校验结果配置,详情请看后文介绍),如图所示。

当定义了语言配置(详情请查看后文的语言配置介绍)选项为英文时会使用titleEn字段用于验证失败时提示使用,例如请求接口时没传请求头时会提示“headerParam1 is missing but it is required”(错误提示输出通过校验结果配置,详情请看后文介绍),如图所示。


title字段用于验证失败时提示使用,例如请求接口时没传请求体参数时会提示“请求体参数1不能为空”(错误提示输出通过校验结果配置,详情请看后文介绍),如图所示。

当定义了语言配置(详情请查看后文的语言配置介绍)选项为英文时会使用titleEn字段用于验证失败时提示使用,例如请求接口时没传请求体参数时会提示“bodyParam1 is missing but it is required”(错误提示输出通过校验结果配置,详情请看后文介绍),如图所示。


title字段用于验证失败时提示使用,例如请求接口时没传Query参数时会提示“query参数1不能为空”(错误提示输出通过校验结果配置,详情请看后文介绍),如图所示。

当定义了语言配置(详情请查看后文的语言配置介绍)选项为英文时会使用titleEn字段用于验证失败时提示使用,例如请求接口时没传Query参数时会提示“queryParam1 is missing but it is required”(错误提示输出通过校验结果配置,详情请看后文介绍),如图所示。

对于JSON Schema规范无法覆盖的校验场景可以使用脚本对入参进行更加灵活的处理。


以上例子使用javascript编写参数校验,限制入参headerParam1、bodyParam1、queryParam1必须一致,不一致将提示错误信息(错误提示输出通过校验结果配置,详情请看后文介绍),如图所示。

聚合接口默认使用中文响应校验失败提示,通过配置可通过入参选择不同的提示语言,目前支持中文、英文提示(已满足我们的业务使用场景,有其他语言要求的小伙伴可以联系我们添加)。

字段:入参字段值,例如使用请求体参数languageCode的值来决定使用哪种语言;
中文:中文与入参字段值的映射关系,例如配置0,当请求入参字段值为0时使用中文提示校验结果;
英文:英文与入参字段值的映射关系,例如配置1,当请求入参字段值为1时使用英文提示校验结果。
聚合接口调用底层服务是通过多个step实现的,多个step串行执行,每个step包含多个request(对底层服务接口的调用),同个step里的多个request并行执行,后执行的step可以获取已执行step的执行结果,更多详情请查看服务编排文章的介绍,下面介绍配置步骤的使用。

是否执行完此步骤后结束:勾选后实际请求只执行完该步骤后即响应结果,不执行后续步骤,用于调试使用;
服务名:无论是选择服务发现或者HTTP,都可以通过选择服务名字来选一组服务器。
Fallback:可选stopcontinue,控制当调用底层服务接口失败后是否继续执行后续操作;
请求预处理:勾选后可配置预处理脚本,预处理脚本返回true时才执行调用底层服务接口。


配置聚合接口调用完成的响应内容。在响应体、响应头配置中可以配置简单的响应固定值、响应引用值,对于需要逻辑处理得到结果的响应可以通过脚本配置灵活处理,如图所示。


配置聚合接口入参校验失败后的响应内容,在响应体、响应头配置中可以配置简单的响应固定值、响应引用值,对于需要逻辑处理得到结果的响应可以通过脚本配置灵活处理,如图所示。

校验结果有一个专用的引用值validateMsg,该引用值用于存放入参验证错误提示信息。

导出功能将聚合接口以配置文件的形式导出,导出的文件可通过导入功能重新导入系统,当我们的系统分多个环境时,可使用导出导入功能实现聚合接口的快速同步,下面介绍导出功能。
导入功能将配置文件中的聚合接口转化成后台的持久化存储,导入的文件可以通过导出功能获取或者通过编写好的聚合配置JSON文件转化得到(转换工具可以联系我们获取)。当我们的系统分多个环境时,可使用导出导入功能实现聚合接口的快速同步,下面介绍导出功能。


强制覆盖:通过请求类型(GETPOST)、请求路径(/proxy/{service}/{apiPath})可以唯一确定一个聚合接口,当聚合接口已存在时,未勾选该选项时忽略该聚合接口导入,勾选该选项时覆盖已存在的聚合接口配置;
调试模式用于对接口开发过程中的调试使用,当打开调试模式后,FizzGate集成平台会将聚合接口调用底层服务接口的请求响应信息以及耗时、聚合结果、步骤上下文打印到日志中,通过日志可以清楚的了解聚合接口的实际执行情况。调试模式会对网关性能造成影响,因此不建议在生产环境打开调试模式,当调试完成后及时关闭调试模式,避免打印过多日志造成资源浪费,下面介绍调试模式的使用。
勾选想要打开调试模式的接口,点击 打开调试模式 按钮弹出确认窗口,如图所示。


勾选想要关闭调试模式的接口,点击 关闭调试模式 按钮弹出确认窗口,如图所示。
点击 确定 按钮后删除接口,处于已发布状态的接口无法删除,需要下线后才能操作删除。
发布下线申请用于聚合接口的发布或者下线申请,只有通过审核人审核后申请人才能执行发布下线操作,避免误操作‘,保证接口的安全。


点击 添加 按钮后,弹出接口列表,勾选需要操作的接口,点击 确定 添加进申请中。

选择审核人:选择有审核权限的人对申请进行审核,列表根据需要操作的接口动态变化(未添加接口时列表为空,拥有服务权限并且有待审核菜单权限的人、操作管理员角色的人为可选审核人),必选;
点击 确定 按钮后提交申请,选择的审核人会收到申请审核邮件(审核人邮箱地址通过用户管理设置,更多详情请查看用户管理功能介绍),如图所示。

后台提供了可视化的接口调用界面,聚合接口创建完成后可通过该界面对接口进行调用测试。通过点击接口详情页面的 测试 按钮打开接口测试页面,如图所示。

跳转页面的同时后台会将接口当前的最新配置推送给FizzGate集成平台生成一个测试接口,请求路径为/proxytest/{service}/{apiPath}。

点击 发送 按钮向指定接口发送一次请求,Response响应结果区域显示调用接口结果,如图所示。
返回Context:FizzGate集成平台中一次聚合接口的请求过程中内部会持有一个Context对象,该对象保存了本次请求过程的入参信息、底层服务接口调用信息、响应信息,通过勾选该选项,接口会将Context随接口响应一起返回,通过查看Context可以清楚地了解接口的实际调用过程。
未勾选 返回Context 选项时,接口按配置输出的设置响应结果,如图所示。

勾选 返回Context 选项后,接口会将Context随接口响应一起返回,如图所示。


点击 保存 按钮会将本次测试请求数据保存下来,通过选取已保存的测试记录可以快速恢复请求数据,如图所示。

标题:本次测试数据保存时使用的标题,长度不能超过2000个字符,保存后在历史测试记录列表显示,如图所示。

