# 插件

# 插件市场

您可以去插件市场 (opens new window)下载插件

# 插件的作用

DBAPI的插件分4类，分别是数据转换插件、缓存插件、告警插件、全局数据转化插件

# 缓存插件

对执行器结果进行缓存，比如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执行结果进行格式转换

# 插件的开发流程

# 准备工作

插件使用java语言编写，准备java(8+)开发环境新建maven项目，pom里引入dbapi-plugin


<dependency>
    <groupId>com.gitee.freakchicken.dbapi</groupId>
    <artifactId>dbapi-plugin</artifactId>
    <version>4.0.0</version>
    <scope>provided</scope>
</dependency>

注意不同版本的DBAPI使用的插件必须依赖相应版本的dbapi-plugin.jar，版本对应关系如下

DBAPI版本	dbapi-plugin版本
4.0.0 - 4.0.3	4.0.0

# 插件开发

# 缓存插件开发

新建java类实现com.gitee.freakchicken.dbapi.plugin.CachePlugin

import com.gitee.freakchicken.dbapi.common.ApiConfig;
import com.gitee.freakchicken.dbapi.plugin.CachePlugin;

import java.util.Map;

public class Cdemo extends CachePlugin {

    /**
     * 插件名称，用于在页面上显示，提示用户
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * 插件功能描述，用于在页面上显示，提示用户
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * 插件参数描述，用于在页面上显示，提示用户
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * 插件初始化方法，实例化插件的时候执行，永远只会执行一次，
     * 一般是用来创建连接池
     */
    @Override
    public void init() {

    }

    /**
     * 缓存设置
     *
     * @param config           api配置
     * @param requestParams    request参数
     * @param data             要缓存的数据
     * @param localPluginParam 插件的局部参数
     */
    public void set(ApiConfig config, Map<String, Object> requestParams, Object data, String localPluginParam){

    }

    /**
     * 清除所有缓存，API修改、删除、下线的时候会触发清除缓存
     *
     * @param config           api配置
     * @param localPluginParam 插件的局部参数
     */
    public void clean(ApiConfig config, String localPluginParam){

    }

    /**
     * 查询缓存
     *
     * @param config           api配置
     * @param requestParams    request参数
     * @param localPluginParam 插件的局部参数
     * @return
     */
    public Object get(ApiConfig config, Map<String, Object> requestParams, String localPluginParam){
        return null;
    }
  
}

init方法是插件初始化方法，只会执行一次，一般用来初始化连接池，比如初始化redis连接池

get方法是获取缓存中的数据的方法，第一个参数是api配置，第二个参数是请求的参数

set方法是设置缓存的方法，当执行器执行后，会调用set方法。第一个参数是api配置，第二个参数是请求的参数，第三个参数是执行器执行结果，如果配置了数据转换插件的话，就是转换后的结果

clean是清空缓存的方法，当API的修改、下线、删除的时候，会执行这个clean方法

# 数据转换插件开发

新建java类，实现com.gitee.freakchicken.dbapi.plugin.TransformPlugin

import com.alibaba.fastjson.JSONObject;
import com.gitee.freakchicken.dbapi.common.ApiConfig;
import com.gitee.freakchicken.dbapi.plugin.TransformPlugin;

import java.util.List;

public class Tdemo extends TransformPlugin {

    /**
     * 插件名称，用于在页面上显示，提示用户
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * 插件功能描述，用于在页面上显示，提示用户
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * 插件参数描述，用于在页面上显示，提示用户
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * 插件初始化方法，实例化插件的时候执行，永远只会执行一次，
     */
    public void init() {
    }

    /**
     * 数据转换逻辑
     *
     * @param data             执行器执行后返回的结果数据
     * @param localPluginParam 插件的局部参数
     * @return
     */
    public Object transform(Object data, String localPluginParam) {
        return null;
    }
}

数据转换逻辑写在transform方法里第一个参数就是执行器执行的结果，如果是SQL执行器，那就是SQL执行结果，是List<JSONObject>数据类型，可以把data强转成List<JSONObject>数据类型

第二个参数是插件局部参数

# 全局数据转换插件开发

新建java类，实现com.gitee.freakchicken.dbapi.plugin.GlobalTransformPlugin

import com.alibaba.fastjson.JSONObject;
import com.gitee.freakchicken.dbapi.common.ResponseDto;
import com.gitee.freakchicken.dbapi.plugin.GlobalTransformPlugin;

public class AmisGlobalTransformPlugin extends GlobalTransformPlugin {

    /**
     * 插件名称，用于在页面上显示，提示用户
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * 插件功能描述，用于在页面上显示，提示用户
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * 插件参数描述，用于在页面上显示，提示用户
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * 插件初始化方法，实例化插件的时候执行，永远只会执行一次，
     */
    public void init() {
    }


    /**
     * 数据转换逻辑
     *
     * @param data             API返回数据
     * @param localPluginParam 全局转换插件的局部参数
     * @return
     */
    public Object transform(ResponseDto data, String localPluginParam) {
        return null;
    }


}

数据转换逻辑写在transform方法里，第一个参数就是API执行返回的结果，第二个参数是插件局部参数

# 告警插件开发

新建java类，实现com.gitee.freakchicken.dbapi.plugin.AlarmPlugin

import com.gitee.freakchicken.dbapi.common.ApiConfig;
import com.gitee.freakchicken.dbapi.plugin.AlarmPlugin;

import javax.servlet.http.HttpServletRequest;

public class EmailAlarmPlugin extends AlarmPlugin {


    /**
     * 插件名称，用于在页面上显示，提示用户
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * 插件功能描述，用于在页面上显示，提示用户
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * 插件参数描述，用于在页面上显示，提示用户
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * 插件初始化方法，实例化插件的时候执行，永远只会执行一次
     */
    @Override
    public void init() {

    }

     /**
     * 告警逻辑
     * 
     * @param e                异常
     * @param config           API元数据
     * @param request          请求
     * @param localPluginParam 告警插件的局部参数
     */
    public void alarm(Exception e, ApiConfig config, HttpServletRequest request, String localPluginParam) {

    }
}

# 插件注册

dbapi插件使用java的spi机制注册，需要执行以下操作：

在resources目录下新建文件夹META-INF,再在META-INF文件夹下新建services文件夹

在META-INF/services目录下新建文件com.gitee.freakchicken.dbapi.plugin.CachePlugin，并在此文件中填写刚才编写的缓存插件的java类名

在META-INF/services目录下新建文件com.gitee.freakchicken.dbapi.plugin.TransformPlugin，并在此文件中填写刚才编写的数据转换插件的java类名

在META-INF/services目录下新建文件com.gitee.freakchicken.dbapi.plugin.GlobalTransformPlugin，并在此文件中填写刚才编写的全局数据转换插件的java类名

在META-INF/services目录下新建文件com.gitee.freakchicken.dbapi.plugin.AlarmPlugin，并在此文件中填写刚才编写的告警插件的java类名

# 插件说明

# 全局参数

设计插件全局参数的目的，是为了方便一个插件在不同的环境中使用
插件全局参数是每个插件自身的参数，与API无关，比如缓存插件需要连接的redis的ip、端口信息。配置在文件conf/plugin.properties中。
全局参数主要是为了方便不同环境的切换，比如测试环境和生产环境需要连接不同的redis地址，那么把redis地址信息配在配置文件就很方便。
如果用户想添加插件的全局配置，可以直接在conf/plugin.properties文件中添加配置，比如：

RedisCachePlugin.ip=127.0.0.1
RedisCachePlugin.port=6379
RedisCachePlugin.db=0
RedisCachePlugin.password=

获取插件全局参数值的方法：

import com.gitee.freakchicken.dbapi.plugin.PluginConf;
String ip = PluginConf.getKey("RedisCachePlugin.ip")

# 局部参数

设计插件局部参数的目的，是为了让一个插件能够被多个API灵活的复用
插件局部参数是为每个API单独指定的参数，参数值从页面上配置进去（创建、编辑API的时候）。
比如针对redis缓存插件，不同的API需要设置不同的缓存时间，那么每个API调用同一个缓存插件的时候，就可以传递不同的时间参数进去。又比如针对字段加密插件，每个API需要加密的字段都不一样，那么每个API调用同一个字段加密插件的时候，就可以传递不同的字段名参数进去。这样可以让一个插件灵活的被多个API复用。
获取插件局部参数值的方法：

// 插件局部参数已经传入了对应插件的方法，参数名是localPluginParam
// 例如告警插件的alarm方法，最后一个参数就是局部插件参数
    public void alarm(Exception e, ApiConfig config, HttpServletRequest request, String localPluginParam) {

    }

# 插件日志打印

如果想在插件内打印日志，推荐直接调用父类的logger

super.logger.debug("set data to cache");

# 插件描述说明

所有的插件都要实现getName getDescription getParamDescription3个方法，其作用是为了在页面上提示用户插件的作用和插件局部参数的格式

# 插件使用

用户开发完插件后，请打包，将最后生成的jar包和插件依赖的jar包拷贝进DBAPI的lib目录下，再重启DBAPI服务（如果是集群模式，每个节点都需要拷贝jar包并重启集群），就可以使用插件了
如果插件中使用了全局参数，还需要在conf/plugin.properties文件添加相应配置并重启生效（如果是集群模式，每个节点都需要添加相应配置并重启生效）

# 插件开发完整案例

案例demo (opens new window)