# 使用指南
# 介绍
狭义上说,DBAPI是一个面向数仓开发人员的低代码工具,只需在页面上编写sql,并配置好参数,就可以自动生成http接口。它可以帮助程序员快速的开发后端数据接口,尤其适用于BI报表、数据可视化大屏的后端接口开发。
广义上说,DBAPI是整个企业数据接口的管理中心,是企业对外提供数据服务的管理平台。它提供了数据接口的动态创建发布功能,对接口的统一管理,并提供了对客户端的管理能力,可以监控客户端对接口的调用、控制客户端对接口的权限。
体验地址:
最新发行版:https://support.51dbapi.com/#/demo (opens new window)
# 特点
- 开箱即用,不需要编程,单机模式不需要依赖其他软件(只需要java运行环境)
- 支持单机模式、集群模式,支持
windows
Linux
mac
- 支持动态创建、修改API;动态创建、修改数据源。热部署全程无感。
- 支持API级别的访问权限控制,支持IP白名单、黑名单控制
- 支持所有关系型数据库(JDBC协议),包括mysql、sqlserver、postgreSql、oracle、hive、达梦、人大金仓、doris、Oceanbase、GaussDB等等
- 支持动态sql,类似mybatis的动态sql,支持sql编辑、运行、调试
- 丰富的插件扩展,支持缓存、数据转换、失败告警
- 支持API配置导入导出,方便测试环境到生产环境的API迁移
- 支持Select/Insert/Update/Delete语句,支持存储过程调用
- 支持一个接口内多条SQL执行(例如分页功能),支持事务开启关闭
- 支持复杂嵌套JSON传参
- 支持接口调用记录查询,接口访问信息统计
- 支持API限流
# 基本概念
- 执行器
执行器有多种,包括SQL执行器、elasticsearch执行器、HTTP执行器。API内的业务执行都抽象成执行器来执行
SQL执行器就是用来在数据库执行sql,将结果返回
elasticsearch执行器是用来在elasticsearch执行DSL语言,将执行结果返回
HTTP执行器相当于网关接口代理,可以使用http客户端转发访问http协议接口,将执行结果返回
个人版目前只支持SQL执行器
- API分组
分组可以对API进行归类,比如业务相同的API可以归入同一个分组,便于管理
- 客户端
DBAPI是一个接口平台,客户端就是调用此平台上API的调用方,比如python程序、java程序都可以调用API,python程序、java程序都是客户端。
客户端的唯一标识是clientId,客户端拥有clientId 和 密钥(secret),管理员可以给客户端分配私有API的访问权限
客户端由管理员创建
# 使用操作入门
# 登录
- 使用默认的账号密码
admin/admin
登录
# 创建数据源
- 点击数据源菜单,点击创建数据源,进入创建数据源页面
- 填写数据库账号地址并保存
- 保存后回到了数据源页面,可以看到多了一条数据源,可以对其编辑删除
理论上支持所有支持JDBC协议的数据库
创建数据源的时候如果选择其他类型,需要用户手动填写JDBC驱动class类,同时将相应的JDBC驱动jar包放入DBApi的
lib
目录下并重启生效(如果是集群模式,每个节点都需要拷贝jar包并重启集群)
DBApi已经自带mysql/sqlserver/postgreSql/clickhouse的驱动包,如果版本不匹配请手动替换
lib
目录下的相应驱动jar包
# 创建API
# 创建API分组
点击API菜单,点击左侧创建API分组按钮
在弹窗中填写分组名称并保存
保存后发现左侧多了新的分组,点击分组上的更多按钮,可以编辑、删除分组
# 创建API
在分组上点击创建API按钮,进入创建API页面
点击基本信息,填写API基础信息
访问权限,开放接口可以直接访问,私有接口需要客户端申请token才能访问
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,类似mybatis的动态sql语法,不需要写最外层的
<select>
<update>
标签,参数名用#{}
${}
表示,可以参考mybatis文档 (opens new window)
事务,默认关闭事务,如果是insert/update/delete语句,建议开启事务,开启事务后如果sql执行失败事务会回滚。如果API内有多条sql,开启事务后多条sql是放在一个事务内执行的
如果是HIVE等不支持事务的数据库,请不要开启事务,否则会报错
数据转换,如果需要数据转换,就填写数据转换插件的java类名,不填写表示不转换。插件如果需要传参数就填写参数。
点击添加按钮可以新增sql,一个API内可以执行多条sql,最后的多个结果封装后一起返回,比如分页查询,一个接口内既要查询详情也要查询总条数。一个sql编写窗口内只能写一条sql
如果一个执行器内包含多条sql,那么每条sql会对应一个数据转换插件配置,数据转换插件永远是针对单条sql查询结果进行转换
- 点击窗口最大化按钮,进入sql调试界面
- 点击运行sql,可以执行sql,如果sql中有参数需要设置参数
- 点击全局插件,填写全局插件信息
缓存,如果需要数据缓存,就填写缓存插件的java类名,不填写表示不开启缓存。插件如果需要传参数就填写参数。
告警,如果API执行失败需要告警的话,就填写告警插件的java类名,不填写表示不开启失败告警。插件如果需要传参数就填写参数。
全局数据转换,如果需要数据转换,就填写数据转换插件的java类名,不填写表示不转换。插件如果需要传参数就填写参数。
- 点击保存即可创建API
# API发布
点击API上的更多按钮,展开了上线按钮,点击上线按钮发布API
点击API上的更多按钮,展开了请求测试按钮,点击请求测试按钮进入请求测试页面
点击发送请求按钮,可以发起请求,如果有参数需要填写参数
# 客户端管理
点击客户端菜单,点击创建客户端按钮
填写客户端信息,保存
创建客户端会生成clientId和secret,系统管理员需要将clientId和secret告知客户端(API调用方)。
客户端使用自己的clientId和secret访问 http://192.168.xx.xx:8520/token/generate?clientId=xxx&secret=xxx
接口可以动态的获取token,客户端使用这个token才能访问私有API(前提是系统管理员已经对该客户端授权了访问此私有API)
创建客户端必须设置token过期时间,以后客户端每次申请的token就会有相应的过期时间,在这个有效期内, 使用上一次申请的token去访问API都是有效的。否则过了这个过期时间,就要重新申请token。
如果token过期时间设置单次有效,那么每次访问私有API都需要重新申请一次token
点击授权按钮,对客户端进行授权API
选择需要授权的分组,保存
# Token使用说明
token申请接口:
http://192.168.xx.xx:8520/token/generate?clientId=xxx&secret=xxx
请求私有接口时,需要把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)
- 修改之前的API为私有接口并重新上线,然后再点击请求测试按钮
此时点击发送请求按钮,发现API不可访问
填入clientId和secret,点击按钮访问接口获取token
将token填入 header的Authorization字段,点击发送请求按钮,发现API访问成功
# ip防火墙设置
开启防火墙可以对IP进行拦截
# 监控
DBAPI只依赖元数据库(mysql/sqlite)就可以使用,但是如果您还需要使用页面上的监控功能(监控API调用记录、访问量、成功率等等), 就必须依赖于另一个日志数据库(需用户自行搭建),来存储API访问日志,推荐使用clickhouse,当然您也可以使用其它的关系型数据库。
目前提供了clickhouse/mysql的日志数据库初始化脚本,在
sql
目录下
- API访问日志采集进入日志数据库有3种方式
- DBAPI默认会将API访问日志写入磁盘文件
logs/dbapi-access.log
,用户可以自行使用datax
flume
等工具采集日志到日志数据库。 - 如果在
conf/application.properties
文件配置了access.log.writer=db
,那么DBAPI会将API访问日志直接写入日志数据库,这种方式适用于日志量不太大的场景下。 - 如果在
conf/application.properties
文件配置了access.log.writer=kafka
,那么DBAPI会将API访问日志写入kafka, 用户需要自行从kafka采集日志到日志数据库,这种方式适用于日志量大的场景,可以由kafka去做数据缓冲。
注意此种方式下需要在
conf/application.properties
文件填写kafka地址。同时DBAPI也自带了消费kafka日志并写入日志数据库的工具,请使用
bin/dbapi-log-kafka2db.sh
脚本。
- 如果您不需要使用监控功能,可以不用搭建日志数据库,并配置
access.log.writer=null
即可。
# Dashboard
- 点击监控菜单可以查看API调用记录的监控
# 查看接口调用记录
- 点击详情标签,可以搜索API调用记录
# 其他功能
# 导出接口文档
- 在API菜单点击工具按钮,再点击导出接口文档按钮
# 插件说明
- DBAPI的插件分4类,分别是数据转换插件、缓存插件、告警插件、全局数据转化插件
- 您可以去插件市场 (opens new window)下载插件
# 缓存插件
- 对执行器结果进行缓存,比如SQL执行器,对查询类SQL,sql查询结果进行缓存,这样避免频繁的查询数据库,对数据库造成压力。
- 缓存逻辑由用户自己编写,用户可以缓存到redis/mongodb/elasticsearch等等。
- 当从缓存中查询不到数据时,才去执行执行器,同时将结果缓存下来。
- 如果是SQL执行器,如果一个执行器内包含多条sql,那么缓存插件是对多条sql执行的结果(如果单条sql配置了转换插件,会先转换结果)封装成一个整体后,对整体进行缓存
# 告警插件
- 当API内部报错的时候,告警插件可以将报错信息发送告警提醒,比如发邮件、发短信
- 告警逻辑由用户自己编写
注意系统已经自带邮件告警插件,如果要使用注意修改
conf/plugin.properties
中发件人参数信息
# 邮件告警插件全局参数
EMAIL_USERNAME=dbapi_test@163.com
EMAIL_PASSWORD=WGJQBFRIPUENHMUP
EMAIL_HOST=smtp.163.com
# 数据转换插件
- 有时候sql无法一次性获得自己想要的数据格式,如果用代码对数据进行一些处理转换能更加方便,这时候就要用到数据转换插件。用户自己编写数据转换逻辑的代码。
- 比如针对sql查询结果中的用户手机号、银行卡号进行转换脱敏。
- 如果是SQL执行器,如果一个执行器内包含多条sql,那么每条sql会对应一个数据转换插件配置,数据转换插件永远是针对单条sql查询结果进行转换
# 全局数据转换插件
- API返回的数据格式默认是
{success:true,msg:xxx,data:xxx}
- 有些情况下需要对response数据格式进行一些转换,比如前端低代码框架
AMIS
就要求接口返回数据必须携带status
字段,这个时候就可以用全局数据转换插件
对整个API的返回数据进行格式转换
注意数据转换插件和全局数据转换插件的区别,数据转换插件是对执行器执行结果进行格式转换(比如对SQL执行器执行查询sql得到的结果进行转换),而全局数据转换插件是对整个API执行结果进行格式转换
# 注意事项
# 数据源支持
- 如果您要使用Oracle或者其他类型的数据源,请将相应的jdbc驱动包手动放入DBApi部署后的
lib
目录下(如果是集群部署每个节点都需要手动放入jar包)
# sql编写规范
- 和mybatis动态sql语法一样,同样支持参数
#{}
、${}
,可以参考mybatis文档 (opens new window) ,不需要写最外层的<select>
<update>
标签,直接写sql内容 - 注意和mybatis一样,sql里的小于号不要写成
<
,要写成<