DBApi用户使用手册

数据源

• 理论上支持所有支持JDBC协议的数据库
• 创建数据源的时候如果选择其他类型，需要用户手动填写JDBC驱动class类和查询所有表的sql，同时将相应的JDBC驱动jar包放入DBApi的lib目录下并重启生效（如果是集群模式，每个节点都需要拷贝jar包并重启集群）
• DBApi已经自带mysql/sqlserver/postgreSql/hive/kylin/clickhouse/的驱动包，如果版本不匹配请手动替换lib目录下的相应驱动jar包
• 查询所有表sql的作用：创建、编辑API的时候，点击选择数据源，会自动展示该数据源下的所有表名称，方便辅助用户编写业务逻辑sql。 由于不同数据库查询所有表名称的方式都不一样，所以需要用户手动去填写这个sql

插件

• DBApi的插件分3类，分别是数据转换插件、缓存插件、告警插件
• 插件需要用户自己编写java代码开发。开发完成后打成jar包，并放入DBApi的lib目录下即可以使用
• 插件开发指南

1. 数据转换插件

• 有时候sql无法一次性获得自己想要的数据格式，如果用代码对数据进行一些处理转换能更加方便，这时候就要用到数据转换插件。用户自己编写数据转换逻辑的代码。
• 典型场景，比如针对sql查询结果中的用户手机号、银行卡号进行加密脱敏。

2. 缓存插件

• 主要是对查询类API，sql查询结果进行缓存，这样避免频繁的查询数据库，对数据库造成压力。
• 缓存逻辑由用户自己编写，用户可以缓存到redis/mongodb/elasticsearch等等。
• 如果开启了缓存，当从缓存中查询不到数据时，才去数据库查询，同时将结果缓存下来。

3 告警插件

• 当API内部报错的时候，告警插件可以将报错信息发送告警提醒，比如发邮件、发短信
• 告警逻辑由用户自己编写

基本操作

创建/修改数据源

创建/修改API

基础配置

• API分组，选择API所属的分组，这个分组可以将来授权使用
• 请求路径，这就是将来http请求的路径
• 选择数据源，就是接口执行sql逻辑的数据库地址
• 填入sql ,类似mybatis的动态sql语法，不需要写最外层的<select> <update> 标签，参数名用 #{} ${} 表示，可以参考mybatis文档
• 一个sql编写窗口内只能写一条sql
• 点击添加可以新增sql，一个API内可以执行多条sql，最后的多个结果封装后一起返回，比如分页查询，一个接口内既要查询详情也要查询总条数
• 选择Content-Type，如果是application/x-www-form-urlencoded类型的API, 需要配置参数，如果是application/json类型的API，需要填写json参数实例

对于application/x-www-form-urlencoded类型的API，用户在请求该API的时候既可以使用application/x-www-form-urlencoded，也可以使用application/json

对于application/json类型的API，用户在请求该API的时候只能使用application/json方式

• 添加参数，参数名称就是sql中的参数名，sql中涉及到的每个参数都要填写
• 访问权限，开放接口可以直接访问，私有接口需要申请token才能访问

高级配置

• 事务

默认关闭事务，如果是insert/update/delete语句，建议开启事务，开启事务后如果sql执行失败事务会回滚。如果API内有多条sql，开启事务后多条sql是放在一个事务内执行的

如果是HIVE等不支持事务的数据库，请不要开启事务，否则会报错

• 数据转换，如果需要数据转换，就填写数据转换插件的java类名，不填写表示不转换。插件如果需要传参数就填写参数。

如果一个API内包含多条sql，那么每条sql会对应一个数据转换插件配置，数据转换插件永远是针对单条sql查询结果进行转换

• 缓存，如果需要数据缓存，就填写缓存插件的java类名，不填写表示不开启缓存。插件如果需要传参数就填写参数。
• 告警，如果API执行失败需要告警的话，就填写告警插件的java类名，不填写表示不开启失败告警。插件如果需要传参数就填写参数。

API分组管理

• 可以添加、删除分组

API请求测试

• 在页面快速访问API，查看结果，注意如果是内网部署，您需要手动修改访问的IP、端口为外网IP、端口

sql调试

• 点击sql填写框右上角的最大化按钮，可以开启sql调试功能
• 如果sql中有参数，在调试的时候，请输入参数

权限管理

创建token

授权token可以访问哪些API

ip防火墙设置

其他功能

导出接口文档

• 可以导出接口文档（markdown格式）

Token使用说明

• 请求私有接口时，需要把token值放入header的Authorization字段中携带，才可以访问成功。（如果是开放接口，不需要设置header）
• 以python为例，访问API的代码示例如下：

import requests
headers = {"Authorization": "5ad0dcb4eb03d3b0b7e4b82ae0ba433f"}
re = requests.post("http://127.0.0.1:8520/API/userById", {"idList": [1, 2]}, headers=headers)
print(re.text)

注意事项

数据源支持

• 如果您要使用Oracle或者其他类型的数据源，请将相应的jdbc驱动包手动放入DBApi部署后的lib目录下（如果是集群部署每个节点都需要手动放入jar包）

sql编写规范

• 和mybatis动态sql语法一样，同样支持参数#{}、 ${}，可以参考mybatis文档 ，不需要写最外层的<select> <update> 标签，直接写sql内容
• 注意和mybatis一样，sql里的小于号不要写成<，要写成 <

权限校验流程