API低代码平台介绍2-最基本的数据查询功能

最基本的数据查询功能

本篇文章我们将介绍如何使用ADI平台定义一个基本的数据查询接口。由于是介绍平台具体功能的第一篇文章，里面会涉及比较多的概念介绍，了解了这些概念有助于您阅读后续的文章。
ADI平台的首页面如下：
ADI平台主页

1.菜单介绍

1.1 OAuth客户端

该API平台是一个独立的服务平台，任何与该API对接的系统都是一个OAuth客户端。

1.2 路由设置

一个路由就是一个接口，该接口是给各OAuth客户端调用的，路由下面包括分享设置，所谓分享设置就是接口的执行策略。一个路由可以包括多个分享设置（即多个执行策略），能够根据不同的条件执行不同的分享设置（例如不同的入参可以执行不同的分享设置），在今后的文章中会详细介绍。

1.3 标准字典类别

即定义接口报文中有哪些字段是需要使用字典值的，您需要在这里配置您的业务系统中的字典字段和字典值，例如房地产行业的业务系统中的业务类别、交易者类别、房屋状态、建筑结构等。该功能用于自动完成两个不同系统间的字典转换（例如A系统的"男性"与B系统的"male"互相转换），在今后的文章中会详细介绍。

1.4 分享日志ES查询

API平台会将每次的上报记录保存在ES中，您通过该模块可以方便的对全量分享日志做可视化查询（一个分享设置的执行会产生一条对应的分享日志）。

1.5 分享日志管理

通过该模块可以方便的对保存在关系数据库中的全量分享日志做可视化查询。

1.6 失败请求管理

通过该模块可以更加直观的看到接口调用失败的日志。

1.6 产品授权管理

在这里填写产品授权码，只有通过授权的API平台才能正常使用。

2.测试数据准备

我准备了一个mysql的测试库business_system来模拟某网签备案业务系统的数据库数据（什么是网签备案系统？简单来说就是住建局的房产交易平台，供买卖双方签订房屋买卖合同使用），其中包括三张表：

2.1 幢表（zhuang）

表结构如下:
幢表结构
幢表准备了两条数据：
幢表数据

2.2 户表（h）

户表通过"幢序号zxh"外键字段与zhuang表关联，表名这套房子属于哪个楼幢，表结构如下：
户表结构
户表准备了两条数据：
在这里插入图片描述

2.3 交易者表（jyz）

交易者表记录了谁购买了哪一套房子（通过户序号关联户表），以及买卖合同编号等信息，表结构如下：
交易者表结构
交易者表中保存了两个合同，其中的YS20231203000001合同有两个卖方（张三、李四）、两个买方（王五、赵六）；YS20231203000002合同有一个卖方（戚薇）和一个买方（周杰伦），数据如下：
交易者表数据

请注意： 后续的文章将很大程度在这个测试库上完成相关示例，请大家多多熟悉。

2.4 接口需求

通过买卖合同号使用GET请求查询该合同对应的楼栋基本信息、户基本信息、卖方基本信息、买方基本信息，该接口提供给住建局的预售资金监管系统使用（什么是预售资金监管系统？简单来说就是住建局的资金监管平台，买方把购房资金交给资金监管系统，等条件成熟后住建局再把资金给卖方，由此确保房产交易的安全性），要求接口响应如下json格式的报文：

{
	"ywbh": "业务编号",
	"htbh": "合同编号",
	"building": {
		"bdcdyh": "幢登记单元代码/不动产单元号",
		"zl": "幢坐落"
	},
	"houses": [{
		"bdcdyh": "户登记单元代码/不动产单元号",
		"fwbm": "房屋编码",
		"szqsc": "所在起始层",
		"szzzc": "所在终止层",
		"shbw": "室号部位",
		"fwzl": "房屋坐落",
		"jzjg": "建筑结构",
		"jzjgbm": "建筑结构编码",
		"fwyt": "房屋用途",
		"fwytbm": "房屋用途编码",
		"jzmj": "建筑面积"
	}],
	"sellers": [{
		"jyzqc": "交易者全称",
		"jyzzjmc": "交易者证件名称",
		"jyzzjhm": "交易者证件号码",
		"jyzxz": "交易者性质"
	}],
	"buyers": [{
		"jyzqc": "交易者全称",
		"jyzzjmc": "交易者证件名称",
		"jyzzjhm": "交易者证件号码",
		"jyzxz": "交易者性质"
	}]
}

其中building用来装载幢基本信息，houses用来装载户基本信息，sellers用来装载卖方信息，buyers用来装载买方信息。

3.开始定义接口

3.1 新增OAuth客户端

点击主界面的[OAuth客户端]菜单->点击[新增]，填写如下字段：
新增OAuth客户端
核心字段说明：
系统名称： 是指要与我们API平台对接的第三方业务系统的名称；这里我们命名为"预售资金监管系统"。
单位名称： 是指要与我们API平台对接的第三方业务系统所属的单位；这里我们命名为"住建/房管"。
client_id： 是指该系统在API平台的唯一标识，今后我们做OAuth2.0客户端认证时会用到。
token的有效时间(秒)： 是指该系统从API平台获取到的access_token的有效期（默认值是2592000，即30天），今后我们做OAuth2.0客户端认证时会用到。
按同样的方式我们再新增一个OAuth客户端，命名为"网签备案系统"。
当两个客户端新增完成后，我们可以看到OAuth客户端列表：

其中的client_secret是自动生成的，今后我们做OAuth2.0客户端认证时会用到。
注意：一个OAuth客户端新增后可以重复使用，当遇到有新的系统要参与对接时，按同样的方式新增即可。

3.2 新增一个路由(接口)

点击主界面的[路由设置管理]->点击[新增]，填写以下字段：
新增路由
核心字段说明：
路由编码： 是指接口的英文名称，会体现到动态生成的接口地址中；这里我们命名为"queryMmhtJbxx"。
路由名称： 是指接口的中文名称；这里我们命名为"查询买卖合同基本信息"。
源系统： 是指该接口默认是给哪个OAuth客户端调用的；这里我们选择"预售资金监管系统"（当然也可以被其它OAuth客户端调用，这里只是赋一个默认值）。
调用方式： 是指该接口对应的http method；这里我们按上面的需求选择get。
其它字段我们暂时用不上，后续文章介绍对应的功能时再讲解，这里保持默认即可。保存后，您将看到以下界面：
路由列表界面

3.3 新增一个分享

点击路由的[分享设置]-[新增]，填写以下字段：
新增分享设置
核心字段说明：
分享类别： 是指该分享所属的类别，尽量实事求是即可；因为是跟住建局对接，因此这里我们从下拉列表选择"应用集成-001住建"。
分享编码： 是指分享设置的英文名称，默认和路由编码一致，如果您的路由下有多个分享设置，请修改分享编码，确保不会违反唯一性（后续文章会详细介绍一个路由下新增多个分享设置的应用场景）。
分享名称： 是指分享设置的中文名称，默认和路由编码一致，如果您的路由下有多个分享设置，根据分享设置的实际用途修改即可。
开发完成： 选择“是”才会完全执行该分享设置的逻辑；选择“否”会直接响应测试数据，且需要您在这个界面维护“测试响应数据”字段（一般什么情况下会选择"否"？当目标系统的接口还未开发完成时，为了不影响源系统的程序开发进度，这里就可以选择"否"，并且按照约定的报文格式组织测试数据进行响应；后续文章会详细介绍）。
目标系统名称： 是指这个分享设置的响应方是谁，这里我们选择"网签备案系统"。
是否启用： 选择“是”，如果选择“否”，将不会执行该分享设置（当一个路由下有多个分享设置，并且不再需要某个分享设置时，可以设置成"否"）。
是否前置分享： 是指执行该路由的其它分享设置之前，是否需要优先执行该分享设置，当且仅当前置分享设置执行成功后才会执行其他分享设置（后续文章会详细介绍前置分享的应用场景）。
实时响应： 是指是否需要同步执行该分享设置；选择“否”将异步执行，直接响应成功（后续文章会详细介绍异步执行的应用场景）。
数据库类型： 是指该分享设置要直接操作的数据库类型，支持Oracle、Mysql、SqlServer、PostgreSQL；这里我们选择Mysql。
数据库IP： 是指该分享设置要直接操作的数据库IP地址；由于测试库在本机，因此这里填写"127.0.0.1"。
数据库实例名： 是指该分享设置要直接操作的数据库实例名；这里我们填写"business_system?useUnicode=true&characterEncoding=UTF-8&serverTimezone=UTC"。
数据库端口： 是指该分享设置要直接操作的数据库连接端口；这里我们填写3306。
数据库用户名： 是指该分享设置要直接操作的数据库用户名。
数据库密码： 是指该分享设置要直接操作的数据库密码，保存后API平台会进行加密存储。
其它字段我们暂时用不上，后续文章介绍对应的功能时再讲解，这里保持默认即可。保存后，您将看到以下界面：
分享设置列表
可以点击"数据库连接测试"，看看我们填写的数据库信息是否正确，如图：

3.4 编写sql组装业务数据

点击分享设置的[数据定义]，如图：
数据定义入口
点击数据定义页面的[新增]，假设接口的入参是htbh(合同编号)，那么我们要做的，就是根据入参编写sql语句，实现报文的组装。
首先，我们把json报文的根节点字段查询出来，sql如下：

select distinct ywbh,htbh from jyz j where j.HTBH = request~htbh~

提示： request~ ~ 是sql中获取动态参数（从接口的请求报文中获取）的写法，参数名和入参保持一致（大小写不敏感）；API平台生成在线接口文档的时候，会自动解析request~~中的参数，以便您进行测试。
把sql填写到表单中，如图：
新增数据定义
核心字段说明：
数据集： 是指您的sql语句。
数据类型： 是指该sql语句的执行结果要组装成什么json格式，支持jsonObject和jsonArray；根数据集只能使用jsonObject。
数据集名称： 是指组装成json的时候，该数据集对应的json字段名；默认root，表示根数据集，会将sql查出来的字段放到json对象的根节点。
数据集父类名称： 是指该数据集的上层数据集名称，用来实现json嵌套格式（当某条sql的执行依赖于上级sql的执行结果时，那么需要在这里指定上层数据集，并且通过 parent~ ~ 可以把上层sql的执行结果作为本sql的查询条件）。
是否大写： 是指组装json的时候，json字段是否需要大写；根据最前面给的json实例，我们这里选择"否"，即小写。
执行前置条件_JS： 是指满足指定条件时才执行该数据集（后续文章会详细介绍使用场景）。

填写完成后点击保存即可，如果保存成功，代表您的sql语法无误，API平台会自动解析该sql返回的字段，保存到”数据详情”中。
提示：只有第一次保存sql才会自动解析字段，如果您后续修改sql增加或减少了字段，那么”数据详情”中是不会自动增加或减少字段的，需要您手工在”数据详情”中对字段进行增删改。
数据定义列表
点击[数据详情]可以看到自动生成的字段信息，如图：
数据详情列表
接下来我们组装json中building(幢)节点的数据。点击点击分享设置的[数据定义]->[新增]
填写如下sql语句：

SELECT DISTINCT
	z.ZHDJDYDM AS bdcdyh,
	z.zl 
FROM
	zhuang z
	JOIN h ON h.ZXH = z.ZXH
	JOIN jyz ON h.HXH = jyz.HXH 
	AND jyz.ywbh = parent~ywbh~

提示： parent~~是sql中获取动态参数（从父级数据集的查询结果中获取）的写法，参数名和父级数据集返回的字段名保持一致（大小写不敏感）。
新增数据集

根据报文结构，这个数据集对应的数据类型是jsonObject，数据集名称是building，父级数据集选择root，json字段小写，填写后点击保存即可。

接下来我们组装json中houses(户)节点的数据。点击点击分享设置的[数据定义]->[新增]
填写如下sql语句：

SELECT DISTINCT
	h.HDJDYDM AS bdcdyh,
	h.FBM AS fwbm,
	h.QSC AS szqsc,
	h.ZHZHC AS szzzc,
	h.FH AS shbw,
	h.ZL AS fwzl,
	h.JZJG AS jzjg,
	h.GHYT AS fwyt,
	h.JZMJ 
FROM
	h
	JOIN jyz ON h.HXH = jyz.HXH 
	AND jyz.ywbh = parent~ywbh~

如图：
在这里插入图片描述

根据报文结构，这个数据集对应的数据类型是jsonArray，数据集名称是houses，父级数据集选择root，json字段小写，填写后点击保存即可。

接下来我们组装json中sellers(卖方)节点的数据。点击点击分享设置的[数据定义]->[新增]
填写如下sql语句：

SELECT
	j.QC AS jyzqc,
	j.ZJMC AS jyzzjmc,
	j.ZJHM AS jyzzjhm,
	j.JYZXZ 
FROM
	jyz j 
WHERE
	j.ywbh = parent~ywbh~ 
	AND j.JYZLB = '卖方'

如图：
新增数据集
根据报文结构，这个数据集对应的数据类型是jsonArray，数据集名称是sellers，父级数据集选择root，json字段小写，填写后点击保存即可。

接下来我们组装json中buyers(买方)节点的数据。点击点击分享设置的[数据定义]->[新增]
填写如下sql语句：

SELECT
	j.QC AS jyzqc,
	j.ZJMC AS jyzzjmc,
	j.ZJHM AS jyzzjhm,
	j.JYZXZ 
FROM
	jyz j 
WHERE
	j.ywbh = parent~ywbh~ 
	AND j.JYZLB = '买方'

如图：
新增数据集

根据报文结构，这个数据集对应的数据类型是jsonArray，数据集名称是buyers，父级数据集选择root，json字段小写，填写后点击保存即可。

到此为止，我们所有的sql都添加好了，数据定义列表截图如下：

4.在线测试接口

回到路由设置的列表页，找到我们刚才新增的路由，点击[打开文档]，如图所示：
在这里插入图片描述
点击后可以看到API平台为我们自动生成的在线文档，如图：
自动生成在线接口文档
我们填写入参值：YS20231203000001，点击[试一下]，接口调用该接口，如图：
在线测试接口
可以看到API平台为这个接口自动生成的接口地址是"http://127.0.0.1:8080/adi/bitapi/queryMmhtJbxx"，其中的adi和bitapi是固定路径，queryMmhtJbxx则是我们自定义的路由编码；响应报文如下：

{
  "type": "success",
  "data": {
    "ywbh": "20231203000001",
    "htbh": "YS20231203000001",
    "building": {
      "bdcdyh": "110108001001GB00001F0001",
      "zl": "北京市海淀区曙光中路曙光花园智业园1幢"
    },
    "houses": [
      {
        "bdcdyh": "110108001001GB00001F00010003",
        "fwbm": "fbm0003",
        "szqsc": 1,
        "szzzc": 1,
        "shbw": "103",
        "fwzl": "北京市海淀区曙光中路曙光花园智业园1幢B座1-103",
        "jzjg": "钢结构",
        "fwyt": "住宅",
        "jzmj": 183
      }
    ],
    "sellers": [
      {
        "jyzqc": "张三",
        "jyzzjmc": "居民身份证",
        "jyzzjhm": "510121100909137101",
        "jyzxz": "外省市个人"
      },
      {
        "jyzqc": "李四",
        "jyzzjmc": "军官证",
        "jyzzjhm": "wj0001",
        "jyzxz": "军人"
      }
    ],
    "buyers": [
      {
        "jyzqc": "王五",
        "jyzzjmc": "户口簿",
        "jyzzjhm": "522121100909137102",
        "jyzxz": "本市城镇居民"
      },
      {
        "jyzqc": "赵六",
        "jyzzjmc": "港澳台身份证",
        "jyzzjhm": "gat0001",
        "jyzxz": "台湾同胞"
      }
    ]
  },
  "uuid": "ece8cac65dc744b993ac86dadaeae6af"
}

其中的type、data、uuid是API平台响应的固定参数，解释如下：
type：表示本次接口调用是否成功，其中type=success表示请求处理成功，否则(type=fail)表示处理失败，当处理成功时，data一般是装载业务数据的json对象或者是字符串类型的提示信息，当处理失败时，data则是字符串类型的失败原因。
data：业务数据或提示信息。
uuid：本次请求的唯一标识，通过uuid值可以在API平台中迅速定位日志详情。

注意： API平台要求请求报文必须是utf-8编码的；API平台的响应报文也是utf-8编码的。

有了在线接口文档，我们就不需要安装类似postman这种软件了，当时，如果你确实想在postman中调用也是可以的，在浏览器地址栏调用get请求也是可以的，如图所示：
浏览器调用API平台

4.查询接口调用日志

点击主界面的[分享日子和ES查询]或[分享日志管理]，如图所示：
分享日志列表

每个分享设置在执行时都会生成一条分享日志。从"说明"列我们可以看到最开始那条日志对应的调用耗时最长，是因为数据源第一次被使用时API平台会创建数据库连接池。最常用的两列：
日志编码： 每次调用时的唯一编码，可以从API平台的响应报文中中获取；
日志跟踪： 从接口入参中获取，一般是业务系统的某个字段，例如业务编号或买卖合同号等，可以自定义使用哪个入参作为日志跟踪值。
如果使用ES查询，那么我们可以在第一个查询条件输入框中输入某个关键字，即可查询到相关的日志，例如我们输入"周杰伦"进行查询，效果如下：
ES关键词查询
ES查询提高了我们查询日志的灵活程度。
点击[详情]，可以看到该条分享日志更加详细的信息，例如请求报文、请求时间、响应报文、响应时间等，如图所示：
日志详情1
日志详情2
里面有些字段值是空的，这是因为我们本次定义的接口没有涉及到请求转发、没有涉及到加解密。