# 概述

服务编排是FizzGate集成平台提供的一个强大的功能，能够基于现有的业务微服务通过在线配置的方式快速的生成一个聚合接口，减少中间层胶水代码以及降低编码投入。在服务编排中支持使用函数，本进阶教程中我们分三篇文章（上篇：列表展开&合并、中篇：列表提取&关联、下篇：列表字段重命名&字段移除）来介绍数据列表类函数的使用。

本文为服务编排处理列表数据系列的上篇。

# 函数

函数是服务编排提供的一个强大又便捷的功能，通过将一些常用的逻辑封装成函数，在服务编排中使用函数对服务编排过程的数据进行处理，从而简化我们的配置又能实现复杂的功能。

# 函数分类

版本要求：v2.3或以上版本

函数以fn.开头，如fn.date.timestamp(), date为类别， 网关内置了以下几大类函数

  • 公共类 fn.common
  • 日期类 fn.date
  • 字符串类 fn.string
  • 编解码类 fn.codec
  • 数学类 fn.math
  • 数据列表类 fn.list

# 引用值

在函数里支持使用引用值，如：

fn.string.concat({step1.result.channelCode},{step1.result.nonce}）

{step1.result.channelCode} 表示引用值, 引用step1的结果

fn.string.concat({step1.result.channelCode},{g.account.name}）

{g.account.name} 表示引用值, 引用公共资源“account.name”, 以g开头表示引用公共资源

# 嵌套调用

支持多重嵌套调用，如：

fn.codec.md5(fn.date.add(fn.date.add("2021-07-09 22:44:55", "yyyy-MM-dd HH:mm:ss", 1, fn.math.addExact(999,1)), "yyyy-MM-dd HH:mm:ss", fn.math.addExact(0,1), 1000))

fn.string.toUpperCase(fn.codec.sha256(fn.string.concat({step1.result.channelCode},{step1.result.nonce},{step1.result.timestamp},{step1.result.appSecret})))

# 数据列表类函数

函数 返回值类型 用途 参数说明
fn.list.expand(
List<List<Object>> data)		 List<Object> 将二维数组(列表)展开为一维数组(列表)，
如：
data=[[{a:1}],[{a:2}],[{a:3}]]
fn.list.expand(data)
返回：[{a:1},{a:2},{a:3}]		 data: 二维数组（列表）
fn.list.merge(
List<Object>... data)		 List<Object> 将多个列表合并成一个，如：
data1=[{a:1}]
data2=[{a:2}]
data3=[{a:3}]
fn.list.merge(data1,data2,data3)
返回：[{a:1},{a:2},{a:3}]		 data: 列表，可多个
fn.list.extract(
List<Map<String, Object>> data,
String... fields)		 List<Map<String, Object>> 只提取列表里的部分字段，如：
data=[
{a:1,b:4,c:7},
{a:2,b:5,c:8},
{a:3,b:6,c:9}
]
fn.list.extract(data, "a", "c")
返回：[
{a:1,c:7},
{a:2,c:8},
{a:3,c:9}
]		 data: 列表
fields: 【可选】字段，可多个
fn.list.join(
List<Map<String, Object>> dest,
List<Map<String, Object>> src,
String joinField,
String... fields)		 List<Map<String, Object>> 合并2个列表字段，可只合并指定字段，如：
dest=[
{a:1,b:4,c:7},
{a:2,b:5,c:8},
{a:3,b:6,c:9}
]
src=[
{a:1,d:444,e:777},
{a:2,d:555,e:888}
]
fn.list.join(dest,src, "a", "d")
返回：[
{a:1,b:4,c:7,d:444},
{a:2,b:5,c:8,d:555},
{a:3,b:6,c:9}
]		 dest: 目标列表
src: 被合并的列表
joinField: 两个列表关联的字段
格式：
dest列表的关联字段:src列表的
关联字段，如：userName:uname,
如果两个列表的关联字段一样可
只填一个，如：userName
fields: 【可选】被合并列表里需合并的字段，可多个，不填则合并所有字段
fn.list.rename(
List<Map<String, Object>> data,
String... fieldPairs)		 List<Map<String, Object>> 重命名列表里的部分字段，如：
data=[
{a:1,b:4,c:7},
{a:2,b:5,c:8},
{a:3,b:6,c:9}
]
fn.list.rename(data, "a:apple", "c:cat")
返回：[
{apple:1,b:4,cat:7},
{apple:2,b:5,cat:8},
{apple:3,b:6,cat:9}
]		 data: 列表
fieldPairs: 【可选】需重命名
的字段对，可多个。格式：
原字段名:新字段名，如：c:cat
fn.list.removeFields(
List<Map<String, Object>> data,
String... fields)		 List<Map<String, Object>> 删除列表里的部分字段，如：
data=[
{a:1,b:4,c:7},
{a:2,b:5,c:8},
{a:3,b:6,c:9}
]
fn.list.removeFields(data, "b")
返回：[
{a:1,c:7},
{a:2,c:8},
{a:3,c:9}
]		 data: 列表
fields: 【可选】需删除的
字段，可多个

# 资料准备

# FizzGate集成平台安装

可参考： https://www.fizzgate.com/fizz/guide/installation (opens new window)

# 底层服务接口

本文服务编排调用的底层服务接口源码可从github(https://github.com/wehotel/fizz-examples)获取。从github克隆最新的fizz-examples源码，并启动fizz-examples-rest-api服务。

aggr_fn_list_demo_backend_1

aggr_fn_list_demo_backend_2

管理后台(菜单位置：RPC管理->服务声明)配置服务声明，如图所示。

aggr_fn_list_demo_backend_3

# 新增编排接口

管理后台，菜单位置：服务编辑->接口列表，点击新增。

# 列表展开 fn.list.expand

本例子在编排接口中调用底层fizz-examples-rest-api服务的/fn-list/user-basic-info-list-by-roles/{roleList}接口(接口源码：FnListController (opens new window))来获取用户基本信息列表，并对该接口的响应数据进行列表展开以满足我们想要的数据格式。

# 基础信息

aggr_fn_list_expand_1

# 配置输入

在配置输入中可以定义接口的入参和请求头等信息，如果不配置入参或请求头，网关会原样接收调用方传过来的所有入参或请求头，但不会对接收到的参数做任何校验。在本例子中我们不需要入参，全留空。

# 配置步骤

新增1个步骤step1，然后在步骤step1里新增1个请求request1，服务选择我们预先准备好的fizz-examples-rest-api服务，请求/fn-list/user-basic-info-list-by-roles/developer,manager接口。配置响应部分留空，网关会原样接收接口的返回结果。

aggr_fn_list_expand_2

# 配置输出

在配置输出中我们使用step1.request1.response.body.*来引用配置步骤中请求的响应结果(相关引用值的使用方式可参考文档：数据转换使用文档 (opens new window))。

配置要返回给前端的响应报文，这里配置了响应体有以下字段：

code：引用类型，值为步骤step1中请求request1的响应的code字段;

message：引用类型，值为步骤step1中请求request1的响应的message字段；

data：引用类型，值为步骤step1中请求request1的响应的data字段并用fn.list.expand函数对其进行展开。

aggr_fn_list_expand_3

# 测试

直接调用/fn-list/user-basic-info-list-by-roles/developer,manager接口得到的响应如图所示。

aggr_fn_list_expand_4

测试接口得到响应如图所示。

aggr_fn_list_expand_5

从测试接口的响应可以看出服务编排接口已完成了对/fn-list/user-basic-info-list-by-roles/developer,manager接口的请求并正确对响应的data字段的列表进行了展开。

# 列表合并 fn.list.merge

本例子在编排接口中两次调用底层fizz-examples-rest-api服务的/fn-list/user-basic-info-list-by-roles/{roleList}接口(接口源码：FnListController (opens new window))来获取用户基本信息列表，并对该接口的两次调用响应数据进行列表合并以满足我们想要的数据格式。

# 基础信息

aggr_fn_list_merge_1

# 配置输入

在本例子中我们不需要入参，全留空。

# 配置步骤

新增1个步骤step1，在步骤step1里新增1个请求request1，服务选择fizz-examples-rest-api，请求/fn-list/user-basic-info-list-by-role/admin接口。在步骤step1里新增1个请求request2，服务选择fizz-examples-rest-api，请求/fn-list/user-basic-info-list-by-role/manager接口。

aggr_fn_list_merge_2

aggr_fn_list_merge_3

# 配置输出

配置要返回给前端的响应报文，这里配置了响应体有以下字段：

code：引用类型，值为步骤step1中请求request1的响应的code字段;

message：引用类型，值为步骤step1中请求request1的响应的message字段；

data：引用类型，值为步骤step1中请求request1的响应的data字段与step1中请求request2的响应的data字段并用fn.list.merge函数对其进行合并。

aggr_fn_list_merge_4

# 测试

直接调用/fn-list/user-basic-info-list-by-role/admin接口得到的响应如图所示。

aggr_fn_list_merge_5

直接调用/fn-list/user-basic-info-list-by-role/manager接口得到的响应如图所示。

aggr_fn_list_merge_6

测试接口得到响应如图所示。

aggr_fn_list_merge_7

从测试接口的响应可以看出服务编排接口已完成了对/fn-list/user-basic-info-list-by-role/admin接口的请求和对/fn-list/user-basic-info-list-by-role/manager接口的请求并正确对两次调用的响应的data字段的列表进行了合并。

← 服务编排处理列表数据(中) →