# 概述

接口列表功能用于维护聚合接口,聚合接口从外部调用方角度看是一个简单的接口,通过入参请求获取响应结果,内部实现会调用多个底层后端服务,将多个调用结果聚合转换成外部调用方想要的数据格式,更多详情请查看服务编排介绍,下面介绍接口列表功能的操作。

# 接口列表

菜单位置:服务编排 > 接口列表。点击菜单后进入接口列表页面,如图所示。

manager_aggregate_list_query

# 新增接口

点击 新增 按钮弹出新增窗口,如图所示。

manager_aggregate_add_1

# 基础信息

manager_aggregate_add_2

所属服务:接口所属服务,更多详情请查看服务管理功能介绍,必选;

接口名:接口名称,用于展示使用,长度不能超过200个字符,必填;

方法:接口请求方法类型,可选GET|POST,必选;

路径:接口请求路径后缀,长度不能超过2000个字符,必填;

开发人员:接口对应负责的开发人员,长度不能超过200个字符;

描述:接口功能描述,长度不能超过2000个字符;

举个例子,所属服务设置my-test-service,方法设置POST,路径设置test-aggregate-post,对应的聚合接口请求为 POST http://{Fizz网关ip地址}:{port端口}/proxy/my-test-service/test-aggregate-post。

# 配置输入

聚合接口的入参大部分是通过JSON Schema来定义的,下面先简单地介绍下JSON Schema。

# JSON Schema介绍

JSON Schema实际上也是JSON数据,用于标注和验证JSON文档,可以类比于XML Schema,当前最新版本2019-09。

作为普通用户,我们并不需要去了解JSON Schema的规范内容,只要能够构建JSON Schema即可。

要理解JSON Schema,首先要理解什么是JSON。JSON是JavaScript Object Notation的缩写,一种简单的数据交换格式。最初JSON是基于JavaScript,广泛的应用于万维网。由于其简洁和清晰的层次结构、易于人阅读等特性,使得越来越多的场景下被采用。

JSON包含以下数据结构:

  • object:
    { "key1": "value1", "key2": "value2" }
    
  • array:
    [ "first", "second", "third" ]
    
  • number:
    42
    3.1415926
    
  • string:
    "This is a string"
    
  • boolean:
    true
    false
    
  • null:
    null
    

通过以上的简单数据类型,就能构造复杂的结构化数据了。下面举两个例子:

{
  "name": "George Washington",
  "birthday": "February 22, 1732",
  "address": "Mount Vernon, Virginia, United States"
}
{
  "first_name": "George",
  "last_name": "Washington",
  "birthday": "1732-02-22",
  "address": {
    "street_address": "3200 Mount Vernon Memorial Highway",
    "city": "Mount Vernon",
    "state": "Virginia",
    "country": "United States"
  }
}

以上两个例子都是有效的JSON数据,包含一样的有效信息,但是当程序读取数据时,需要准确的知道数据是怎么组织的,比如哪些字段是必须,这些字段是什么类型。这时候JSON Schema就派上用场了,看以下JSON Schema例子:

{
  "type": "object",
  "properties": {
    "first_name": { "type": "string" },
    "last_name": { "type": "string" },
    "birthday": { "type": "string", "format": "date" },
    "address": {
      "type": "object",
      "properties": {
        "street_address": { "type": "string" },
        "city": { "type": "string" },
        "state": { "type": "string" },
        "country": { "type" : "string" }
      }
    }
  }
}

用以上JSON Schema验证第一个例子时,验证失败;但是第二个例子验证通过。

JSON Schema本身也是通过JSON编写,其本身也是数据,不是一个计算机程序,只是一种“描述其它数据的结构”的声明格式。这既是长处,也是弱点,JSON Schema可以简洁地描述数据的结构并且自动验证数据,但是对于数据元素间的关系表达就力不能及了。

更多JSON Schema知识可以阅读Understanding JSON Schema (opens new window)

# 请求头部

定义聚合接口的请求Header参数。

manager_aggregate_add_3

举个例子:

{
  "type": "object",
  "properties": {
    "headerParam1": {
      "type": "string",
      "title": "请求头参数1",
      "titleEn": "headerParam1"
    }
  },
  "required": [
    "headerParam1"
  ]
}

以上例子定义了必传请求头参数headerParam1

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

manager_aggregate_add_input_header_1

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

manager_aggregate_add_input_header_2

# 请求体

定义聚合接口的请求体参数。

manager_aggregate_add_4

举个例子:

{
  "type": "object",
  "properties": {
    "bodyParam1": {
      "type": "string",
      "title": "请求体参数1",
      "titleEn": "bodyParam1"
    }
  },
  "required": [
    "bodyParam1"
  ]
}

以上例子定义了必传请求体参数bodyParam1

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

manager_aggregate_add_input_body_1

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

manager_aggregate_add_input_body_2

# Query参数

定义聚合接口的Query参数。

manager_aggregate_add_5

举个例子:

{
  "type": "object",
  "properties": {
    "queryParam1": {
      "type": "string",
      "title": "query参数1",
      "titleEn": "queryParam1"
    }
  },
  "required": [
    "queryParam1"
  ]
}

以上例子定义了必传Query参数queryParam1

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

manager_aggregate_add_input_query_1

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

manager_aggregate_add_input_query_2

# 脚本校验

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

manager_aggregate_add_6

点击 新增 按钮后弹出脚本配置窗口,如图所示。

manager_aggregate_add_7

脚本类型:可选javascript|groovy,必选;

脚本内容:所选的脚本类型语言编写的入参验证脚本,必填。

举个例子:

// javascript脚本函数名不能修改
function dyFunc(paramsJsonStr) {
  // 上下文, 数据结构请参考 context.js
  var context = JSON.parse(paramsJsonStr)['context'];
  // common为内置的上下文便捷操作工具类,详情请参考common.js;例如:
  // var data = common.getStepRespBody(context, 'step2', 'request1', 'data');

  // do something
  var headerParam1 = common.getInputReqHeader(context, 'headerParam1');
  var bodyParam1 = common.getInputReqBody(context, 'bodyParam1');
  var queryParam1 = common.getInputReqParam(context, 'queryParam1');
  var result = new Array();
  if (headerParam1 != bodyParam1) {
    result.push("headerParam1与bodyParam1不一致");
  }
  if (queryParam1 != bodyParam1) {
    result.push("queryParam1与bodyParam1不一致");
  }
  if (headerParam1 != queryParam1) {
    result.push("headerParam1与queryParam1不一致");
  }

  // 返回结果为Array或Object时要先转为json字符串
  return JSON.stringify(result);
}

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

manager_aggregate_add_input_script

# 语言配置

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

manager_aggregate_add_8

字段:入参字段值,例如input.request.body.languageCode使用请求体参数languageCode的值来决定使用哪种语言;

中文:中文与入参字段值的映射关系,例如配置0,当请求入参字段值为0时使用中文提示校验结果;

英文:英文与入参字段值的映射关系,例如配置1,当请求入参字段值为1时使用中文提示校验结果。

# 配置步骤

聚合接口调用底层服务是通过多个step实现的,多个step串行执行,每个step包含多个request(对底层服务接口的调用),同个step里的多个request并行执行,后执行的step可以获取已执行step的执行结果,更多详情请查看服务编排文章的介绍,下面介绍配置步骤的使用。

manager_aggregate_add_9

是否执行完此步骤后结束:勾选后实际请求只执行完该步骤后即响应结果,不执行后续步骤,用于调试使用;

请求方法:调用底层服务接口的请求类型,可选GET|POST,必选;

默认URL:调用底层服务接口的默认URL,当Fizz网关启动环境没有配置URL时使用该默认URL;

开发环境URL:开发环境调用底层服务接口的URL,当Fizz网关启动使用spring.profiles.active=dev时使用该URL;

测试环境URL:测试环境调用底层服务接口的URL,当Fizz网关启动使用spring.profiles.active=test时使用该URL;

预生产环境URL:预生产环境调用底层服务接口的URL,当Fizz网关启动使用spring.profiles.active=pre时使用该URL;

生产环境URL:生产环境调用底层服务接口的URL,当Fizz网关启动使用spring.profiles.active=prod时使用该URL;

超时时间(毫秒):调用底层服务接口的超时时间,超时抛出异常,单位毫秒;

Fallback:可选stop|continue,控制当调用底层服务接口失败后是否继续执行后续操作;

请求预处理:勾选后可配置预处理脚本,预处理脚本返回true时才执行调用底层服务接口。

manager_aggregate_add_10

配置入参:配置调用底层服务接口的请求参数;

配置响应:配置调用底层服务接口的响应内容。

manager_aggregate_add_11

配置步骤结果:配置step执行完成后的响应内容。

# 配置输出

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

manager_aggregate_add_12

manager_aggregate_add_13

# 校验结果

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

manager_aggregate_add_14

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

# 保存接口

所有配置完成后点击 保存 按钮,完成聚合接口的配置。

manager_aggregate_add_15

# 导出接口

导出功能将聚合接口以配置文件的形式导出,导出的文件可通过导入功能重新导入系统,当我们的系统分多个环境时,可使用导出导入功能实现聚合接口的快速同步,下面介绍导出功能。

manager_aggregate_export_1

勾选想到导出的接口,点击 导出 按钮弹出确认窗口,如图所示。

manager_aggregate_export_2

点击 确定 按钮,浏览器保存配置文件,如图所示。

manager_aggregate_export_3

# 导入接口

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

manager_aggregate_import_1

点击 导入 按钮弹出导入配置窗口,如图所示。

manager_aggregate_import_2

点击 选取文件 按钮后选取要导入的配置文件;

强制覆盖:通过请求类型(GET|POST)、请求路径(/proxy/{service}/{apiPath})可以唯一确定一个聚合接口,当聚合接口已存在时,未勾选该选项时忽略该聚合接口导入,勾选该选项时覆盖已存在的聚合接口配置;

点击 确定 按钮后导入聚合接口配置。

# 调试模式

调试模式用于对接口开发过程中的调试使用,当打开调试模式后,Fizz网关会将聚合接口调用底层服务接口的请求响应信息以及耗时、聚合结果、步骤上下文打印到日志中,通过日志可以清楚的了解聚合接口的实际执行情况。调试模式会对网关性能造成影响,因此不建议在生产环境打开调试模式,当调试完成后及时关闭调试模式,避免打印过多日志造成资源浪费,下面介绍调试模式的使用。

勾选想要打开调试模式的接口,点击 打开调试模式 按钮弹出确认窗口,如图所示。

manager_aggregate_debug_mode_1

点击 确定 按钮确认打开调试模式。

manager_aggregate_debug_mode_2

勾选想要关闭调试模式的接口,点击 关闭调试模式 按钮弹出确认窗口,如图所示。

manager_aggregate_debug_mode_3

点击 确定 按钮确认关闭调试模式。

manager_aggregate_debug_mode_4

# 编辑接口

点击 编辑 按钮弹出编辑窗口,如图所示。

manager_aggregate_edit_1

manager_aggregate_edit_2

# 删除接口

点击 删除 按钮弹出删除确认窗口,如图所示。

manager_aggregate_delete_1

manager_aggregate_delete_2

点击 确定 按钮后删除接口,处于已发布状态的接口无法删除,需要下线后才能操作删除。

# 发布|下线申请

发布|下线申请用于聚合接口的发布或者下线申请,只有通过审核人审核后申请人才能执行发布|下线操作,避免误操作‘,保证接口的安全。

点击 发布|下线申请 按钮,弹出发布|下线申请窗口,如图所示。

manager_aggregate_apply_1

manager_aggregate_apply_2

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

manager_aggregate_apply_3

标题:申请的标题,长度不能超过200个字符,必填;

类型:申请类型,可选发布|下线,必选;

申请原因:申请的原因,长度不能超过2000个字符;

选择审核人:选择有审核权限的人对申请进行审核,列表根据需要操作的接口动态变化(未添加接口时列表为空,拥有服务权限并且有待审核菜单权限的人、操作管理员角色的人为可选审核人),必选;

点击 确定 按钮后提交申请,选择的审核人会收到申请审核邮件(审核人邮箱地址通过用户管理设置,更多详情请查看用户管理功能介绍),如图所示。

manager_aggregate_apply_4

# 接口测试

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

manager_aggregate_test_1

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

manager_aggregate_test_2

点击 发送 按钮向指定接口发送一次请求,Response响应结果区域显示调用接口结果,如图所示。

manager_aggregate_test_3

manager_aggregate_test_4

请求体tab用于配置请求的请求体参数。

manager_aggregate_test_5

请求头tab用于配置请求的请求头参数。

manager_aggregate_test_6

Query参数用于配置请求的Query参数。

manager_aggregate_test_7

返回Context:Fizz网关中一次聚合接口的请求过程中内部会持有一个Context对象,该对象保存了本次请求过程的入参信息、底层服务接口调用信息、响应信息,通过勾选该选项,接口会将Context随接口响应一起返回,通过查看Context可以清楚地了解接口的实际调用过程。

未勾选 返回Context 选项时,接口按配置输出的设置响应结果,如图所示。

manager_aggregate_test_8

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

manager_aggregate_test_9

测试接口:调用测试接口,请求路径为/proxytest/{service}/{apiPath};

正式接口:调用正式接口,请求路径为/proxy/{service}/{apiPath};

manager_aggregate_test_10

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

manager_aggregate_test_11

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

manager_aggregate_test_12

上次更新: 2020-11-9 11:50