DBAPI

# 使用指南

# 介绍

  • 狭义上说，DBAPI是一个面向数仓开发人员的低代码工具，只需在页面上编写sql，并配置好参数，就可以自动生成http接口。它可以帮助程序员快速的开发后端数据接口，尤其适用于BI报表、数据可视化大屏的后端接口开发。

  • 广义上说，DBAPI是整个企业数据接口的管理中心，是企业对外提供数据服务的管理平台。它提供了数据接口的动态创建发布功能，对接口的统一管理，并提供了对客户端的管理能力，可以监控客户端对接口的调用、控制客户端对接口的权限。

  • 体验地址：

最新发行版：https://support.51dbapi.com/#/demo (opens new window)

# 特点

  • 开箱即用，不需要编程，单机模式不需要依赖其他软件（只需要java运行环境）
  • 支持单机模式、集群模式，支持windows Linux mac
  • 支持动态创建、修改API；动态创建、修改数据源。热部署全程无感。
  • 支持API级别的访问权限控制，支持IP白名单、黑名单控制
  • 支持所有类型数据库（JDBC协议），包括mysql/sqlserver/postgreSql/hive/oracle等等
  • 支持动态sql，类似mybatis的动态sql，支持sql编辑、运行、调试
  • 丰富的插件扩展，支持缓存、数据转换、失败告警
  • 支持API配置导入导出，方便测试环境到生产环境的API迁移
  • 支持一个接口内多条SQL执行（例如分页功能），支持事务开启关闭
  • 支持复杂嵌套JSON传参
  • 支持接口调用记录查询，接口访问信息统计

# 基本概念

  • 执行器

执行器有多种，包括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/hive/kylin/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种方式
  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;

# 权限校验流程