概述

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

接口列表

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

新增接口

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

基础信息

所属服务：接口所属服务，更多详情请查看服务管理功能介绍，必选；

接口名：接口名称，用于展示使用，长度不能超过200个字符，必填；

方法：接口请求方法类型，可选GET|POST，必选；

路径：接口请求路径后缀，长度不能超过2000个字符，必填；

开发人员：接口对应负责的开发人员，长度不能超过200个字符；

描述：接口功能描述，长度不能超过2000个字符；

举个例子，所属服务设置my-test-service，方法设置POST，路径设置test-aggregate-post，对应的聚合接口请求为 POST http://{FizzGate集成平台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参数。

举个例子：

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

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

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

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

请求体

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

举个例子：

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

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

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

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

Query参数

定义聚合接口的Query参数。

举个例子：

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

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

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

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

脚本校验

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

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

脚本类型：可选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编写参数校验，限制入参headerParam1、bodyParam1、queryParam1必须一致，不一致将提示错误信息（错误提示输出通过校验结果配置，详情请看后文介绍），如图所示。

语言配置

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

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

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

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

配置步骤

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

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

请求方法：调用底层服务接口的请求类型，可选GET|POST，必选；

服务名：无论是选择服务发现或者HTTP，都可以通过选择服务名字来选一组服务器。

超时时间(毫秒)：调用底层服务接口的超时时间，超时抛出异常，单位毫秒；

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

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

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

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

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

配置输出

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

校验结果

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

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

保存接口

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

导出接口

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

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

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

导入接口

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

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

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

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

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

调试模式

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

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

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

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

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

编辑接口

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

删除接口

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

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

发布|下线申请

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

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

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

标题：申请的标题，长度不能超过200个字符，必填；

类型：申请类型，可选发布|下线，必选；

申请原因：申请的原因，长度不能超过2000个字符；

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

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

接口测试

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

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

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

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

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

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

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

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

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

测试接口：调用测试接口，请求路径为/proxytest/{service}/{apiPath}；

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

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

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