Плагины

Рынок плагинов

Официальный разработчик DBAPI уже предоставил несколько популярных плагинов; вы можете скачать их на рынке плагинов.

Назначение плагинов

Плагины DBAPI делятся на 5 категорий: плагины преобразования данных, плагины кэширования, плагины оповещений, глобальные плагины преобразования данных и плагины обработки параметров.
Все плагины представляют собой JAR‑файлы; их необходимо поместить в директорию extlib или lib каталога DBAPI, после чего перезапустить сервер DBAPI для активации.

Плагин кэширования

Кэширует результаты исполнителей, например, SQL‑исполнителя: для запросов типа SELECT результаты кэшируются, что позволяет избежать частых обращений к базе данных и снижает нагрузку на неё.
Логика кэширования реализуется пользователем; данные могут сохраняться в Redis, MongoDB, Elasticsearch и других системах.
Если данные не найдены в кэше, выполняется запрос, а затем результат записывается в кэш.

Сценарии с несколькими SQL‑запросами

Если SQL‑исполнитель содержит несколько SQL‑запросов, плагин кэширования объединяет результаты всех запросов (если для отдельного запроса настроен плагин преобразования, он сначала обрабатывает результат) и кэширует полученный набор данных.

Плагин оповещений

При возникновении ошибок внутри API плагин оповещений может отправлять уведомления — например, по электронной почте или через SMS.
Логика оповещения также реализуется пользователем.

Плагин преобразования данных

Иногда SQL не позволяет сразу получить данные в нужном формате; в таких случаях удобно использовать плагин преобразования данных, который позволяет программно обработать и преобразовать данные.
Например, можно применять такие операции, как маскировка номеров телефонов или банковских карт в результатах SQL‑запроса.

Сценарии с несколькими SQL‑запросами

Если SQL‑исполнитель включает несколько запросов, для каждого запроса настраивается отдельный плагин преобразования данных; при этом каждый плагин работает только с результатами соответствующего запроса.

Глобальный плагин преобразования данных

По умолчанию формат ответа API имеет вид {success:true,msg:xxx,data:xxx}.
В некоторых случаях требуется изменить структуру ответа; например, фреймворк низкоуровневого кодирования для интерфейсов AMIS требует обязательного наличия поля status. В таких случаях используется глобальный плагин преобразования данных, который изменяет формат всего ответа API.

Разница между плагинами преобразования данных и глобальным плагином

Плагин преобразования данных применяется к результатам выполнения конкретного исполнителя (например, к результатам SQL‑запроса), тогда как глобальный плагин преобразования данных изменяет формат всего ответа API.

Плагин обработки параметров

Позволяет выполнять пользовательскую обработку входящих параметров.
Например, переводить все значения параметров в верхний регистр.
Или, если API принимает зашифрованные параметры, реализовать логику дешифровки.
Также можно добавить параметр offset, который рассчитывается по формуле (pageNo - 1) * pageSize при пагинации.

Поддержка версий

Плагин обработки параметров поддерживается начиная с версии Personal Edition 4.0.16 и Enterprise Edition 4.1.10.

Процесс разработки плагинов

Подготовительные работы

Плагины пишутся на языке Java; подготовьте среду разработки Java (версия 8 или выше), создайте новый проект Maven и добавьте в файл pom.xml зависимость dbapi-plugin.

xml

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

Разработка плагинов

Разработка плагина кэширования

Создайте класс Java, реализующий интерфейс com.gitee.freakchicken.dbapi.plugin.CachePlugin.

java

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    параметры запроса
     * @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    параметры запроса
     * @param localPluginParam локальные параметры плагина
     * @return
     */
    public Object get(ApiConfig config, Map<String, Object> requestParams, String localPluginParam){
        return null;
    }

}

Метод init выполняется один раз при инициализации плагина; обычно используется для создания пулов соединений, например, пула соединений Redis.
Метод get предназначен для получения данных из кэша; первый параметр — конфигурация API, второй — параметры запроса.
Метод set используется для записи данных в кэш; вызывается после выполнения исполнителя. Первый параметр — конфигурация API, второй — параметры запроса, третий — результат выполнения исполнителя (при наличии плагина преобразования данных — преобразованный результат).
Метод clean очищает весь кэш; вызывается при модификации, удалении или выводе API из эксплуатации.

Разработка плагина преобразования данных

Создайте класс Java, реализующий интерфейс com.gitee.freakchicken.dbapi.plugin.TransformPlugin.

java

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‑исполнитель, то это будет список объектов JSON (List<JSONObject>). Можно явно привести тип данных к List<JSONObject>.
Второй параметр — локальные параметры плагина.

Разработка глобального плагина преобразования данных

Создайте класс Java, реализующий интерфейс com.gitee.freakchicken.dbapi.plugin.GlobalTransformPlugin.

java

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.

java

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) {

    }
}

Логика оповещения реализуется в методе alarm.

Разработка плагина обработки параметров

Создайте новый класс Java, реализующий интерфейс com.gitee.freakchicken.dbapi.plugin.ParamProcessPlugin

java

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

import java.util.Map;

public class PaginationPlugin extends ParamProcessPlugin {
    /**
     * Название плагина, отображаемое на странице для подсказки пользователю
     *
     * @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 requestParam   Параметры запроса
     * @param apiConfig      Метаданные API
     * @param localPluginParam Локальные параметры плагина
     */
    @Override
    public void process(Map<String, Object> requestParam, ApiConfig apiConfig, String localPluginParam) {

    }
}

Логика обработки параметров пишется в методе process.
requestParam — это параметры запроса, apiConfig — метаданные API, а localPluginParam — локальные параметры плагина.

Регистрация плагинов

Плагины DBAPI регистрируются с использованием механизма SPI в Java. Для этого необходимо выполнить следующие шаги:

В каталоге resources создайте папку META-INF, затем внутри неё — папку services.
В каталоге META-INF/services создайте файл com.gitee.freakchicken.dbapi.plugin.CachePlugin и укажите в нём имя только что написанного класса кэширующего плагина.
В каталоге META-INF/services создайте файл com.gitee.freakchicken.dbapi.plugin.TransformPlugin и укажите в нём имя только что написанного плагина преобразования данных.
В каталоге META-INF/services создайте файл com.gitee.freakchicken.dbapi.plugin.GlobalTransformPlugin и укажите в нём имя только что написанного глобального плагина преобразования данных.
В каталоге META-INF/services создайте файл com.gitee.freakchicken.dbapi.plugin.AlarmPlugin и укажите в нём имя только что написанного плагина оповещения.
В каталоге META-INF/services создайте файл com.gitee.freakchicken.dbapi.plugin.ParamProcessPlugin и укажите в нём имя только что написанного плагина обработки параметров.

Описание плагинов

Глобальные параметры

Цель создания глобальных параметров плагина — обеспечить удобство использования одного и того же плагина в разных средах.
Глобальные параметры являются собственными настройками каждого плагина и не зависят от API; например, кэширующий плагин может требовать IP‑адрес и порт Redis‑сервера. Эти параметры задаются в файле conf/plugin.properties.
Глобальные параметры особенно удобны при переключении между различными окружениями: если тестовая и производственная среды используют разные адреса Redis, то указание этих данных в конфигурационном файле значительно упрощает работу.
Если пользователь хочет добавить новые глобальные настройки для плагина, он может просто добавить соответствующие строки в файл conf/plugin.properties, например:

properties

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

Способ получения значений глобальных параметров плагина:

java

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

Локальные параметры

Цель создания локальных параметров — обеспечить гибкое повторное использование одного и того же плагина для различных API.
Локальные параметры задаются отдельно для каждого API и настраиваются через интерфейс (при создании или редактировании API).
Например, для плагина кэширования Redis различные API могут требовать разное время хранения данных в кэше; таким образом, при вызове одного и того же плагина каждый API может передавать свои уникальные параметры времени.
Аналогично, для плагина шифрования полей каждое API может использовать свои собственные поля для шифрования; таким образом, один и тот же плагин можно гибко применять к разным API.
Способ получения значений локальных параметров плагина:

java

// Локальные параметры уже переданы в соответствующий метод плагина; их имя указано в параметре localPluginParam.
// Например, в методе alarm плагина оповещения последним параметром являются локальные параметры:
public void alarm(Exception e, ApiConfig config, HttpServletRequest request, String localPluginParam) {

}

Вывод логов из плагина

Если вы хотите выводить логи внутри плагина, рекомендуется напрямую использовать метод logger родительского класса:

java

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

Описание плагинов

Все плагины должны реализовывать три метода: getName, getDescription и getParamDescription. Их задача — предоставить пользователю информацию о назначении плагина и формате его локальных параметров.

Использование плагинов

После завершения разработки плагина соберите его в виде JAR‑файла, скопируйте полученный JAR вместе с зависимыми библиотеками в директорию extlib или lib DBAPI (мы рекомендуем размещать их в директории extlib для удобства централизованного управления), затем перезапустите сервис DBAPI (в случае кластерной работы необходимо скопировать JAR‑файл и перезапустить каждый узел кластера). После этого плагин будет готов к использованию.
Если в плагине используются глобальные параметры, дополнительно укажите соответствующие настройки в файле conf/plugin.properties и перезапустите сервис для применения изменений (в случае кластерной работы аналогичная процедура должна быть проведена на каждом узле).

Полный пример разработки плагина

Пример демонстрации

Плагины ​

Рынок плагинов ​

Назначение плагинов ​

Плагин кэширования ​

Плагин оповещений ​

Плагин преобразования данных ​

Глобальный плагин преобразования данных ​

Плагин обработки параметров ​

Процесс разработки плагинов ​

Подготовительные работы ​

Разработка плагинов ​

Разработка плагина кэширования ​

Разработка плагина преобразования данных ​

Разработка глобального плагина преобразования данных ​

Разработка плагина оповещений ​

Разработка плагина обработки параметров ​

Регистрация плагинов ​

Описание плагинов ​

Глобальные параметры ​

Локальные параметры ​

Вывод логов из плагина ​

Описание плагинов ​

Использование плагинов ​

Полный пример разработки плагина ​

Плагины

Рынок плагинов

Назначение плагинов

Плагин кэширования

Плагин оповещений

Плагин преобразования данных

Глобальный плагин преобразования данных

Плагин обработки параметров

Процесс разработки плагинов

Подготовительные работы

Разработка плагинов

Разработка плагина кэширования

Разработка плагина преобразования данных

Разработка глобального плагина преобразования данных

Разработка плагина оповещений

Разработка плагина обработки параметров

Регистрация плагинов

Описание плагинов

Глобальные параметры

Локальные параметры

Вывод логов из плагина

Описание плагинов

Использование плагинов

Полный пример разработки плагина