# 使用指南

# 介绍

  • 狭义上说,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限流
  • 支持OpenAPI,方便集成到其他软件系统

# 基本概念

  • 执行器

执行器有多种,包括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": [12]},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种方式
  1. DBAPI默认会将API访问日志写入磁盘文件logs/dbapi-access.log,用户可以自行使用datax flume等工具采集日志到日志数据库。
  2. 如果在conf/application.properties文件配置了access.log.writer=db,那么DBAPI会将API访问日志直接写入日志数据库,这种方式适用于日志量不太大的场景下。
  3. 如果在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里的小于号不要写成<,要写成 &lt;

# 权限校验流程