Complementos

Mercado de complementos

DBAPI ya ofrece algunos complementos comunes; puede descargarlos en el Mercado de complementos.

Función de los complementos

Los complementos de DBAPI se dividen en cinco categorías: complementos de conversión de datos, complementos de caché, complementos de alertas, complementos globales de conversión de datos y complementos de procesamiento de parámetros.
Todos los complementos son paquetes JAR; debe colocar estos archivos en el directorio extlib o lib de DBAPI y reiniciar el sistema para que estén disponibles.

Complemento de caché

Almacena en caché los resultados del ejecutor; por ejemplo, en el caso del ejecutor SQL, las consultas SQL generan resultados que se almacenan en caché, evitando así consultas frecuentes a la base de datos y reduciendo la carga sobre esta.
La lógica de almacenamiento en caché la define el usuario, quien puede guardar los datos en Redis, MongoDB, Elasticsearch u otras bases de datos.
Si no se encuentra ningún dato en la caché, el sistema ejecuta la consulta correspondiente y luego guarda el resultado en la caché.

Escenarios con múltiples consultas SQL

En el caso de un ejecutor SQL que incluya varias sentencias, el complemento de caché encapsula los resultados de todas ellas (si una consulta individual tiene configurado un complemento de conversión, primero se aplica dicha conversión) y almacena en caché el conjunto completo.

Complemento de alertas

Cuando se produce un error interno en la API, el complemento de alertas puede enviar notificaciones de advertencia, como correos electrónicos o mensajes SMS.
La lógica de generación de alertas la define el propio usuario.

Complemento de conversión de datos

A veces, las consultas SQL no devuelven directamente los datos en el formato deseado. En estos casos, resulta más práctico utilizar un complemento de conversión de datos para realizar transformaciones mediante código personalizado.
Por ejemplo, se pueden aplicar técnicas de ofuscación o despersonalización a números de teléfono o números de tarjeta bancaria obtenidos tras una consulta SQL.

Escenarios con múltiples consultas SQL

En el caso de un ejecutor SQL que contenga varias sentencias, cada consulta tendrá su propio complemento de conversión de datos asociado; este complemento actúa únicamente sobre los resultados de la consulta correspondiente.

Complemento global de conversión de datos

Por defecto, los datos devueltos por la API tienen el formato {success:true,msg:xxx,data:xxx}.
En ciertos casos, es necesario modificar el formato de la respuesta; por ejemplo, el framework de bajo código del frontend, AMIS, exige que las respuestas incluyan un campo status. En tales situaciones, se utiliza el complemento global de conversión de datos para ajustar el formato de toda la respuesta de la API.

[!NOTA] Diferencia entre complementos de conversión de datos y complementos globales de conversión de datos El complemento de conversión de datos modifica el formato de los resultados de un ejecutor específico (por ejemplo, los resultados de una consulta SQL), mientras que el complemento global de conversión de datos ajusta el formato de toda la respuesta de la API.

Complemento de procesamiento de parámetros

Permite realizar operaciones personalizadas sobre los parámetros de solicitud.
Por ejemplo, convertir todos los valores de los parámetros a mayúsculas.
O bien, si la API recibe parámetros cifrados, implementar una lógica personalizada para descifrarlos.
También puede añadir un parámetro offset en consultas paginadas, cuyo valor corresponda a (pageNo-1)*pageSize.

[!NOTA] Soporte por versiones El complemento de procesamiento de parámetros está disponible desde la versión 4.0.16 en la edición Personal y desde la versión 4.1.10 en la edición Empresarial.

Proceso de desarrollo de complementos

Preparativos

Los complementos se desarrollan utilizando el lenguaje Java. Asegúrese de contar con un entorno de desarrollo Java (versión 8 o superior), cree un proyecto Maven e incluya la dependencia dbapi-plugin en el archivo pom.xml.

xml

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

Desarrollo del complemento

Desarrollo del complemento de caché

Cree una clase Java que implemente la interfaz 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 {

    /**
     * Nombre del complemento, mostrado en la interfaz para informar al usuario.
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * Descripción funcional del complemento, mostrada en la interfaz para orientar al usuario.
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * Descripción de los parámetros del complemento, mostrada en la interfaz para orientar al usuario.
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * Método de inicialización del complemento, ejecutado al instanciarlo y que se ejecuta solo una vez,
     * generalmente para crear un pool de conexiones.
     */
    @Override
    public void init() {

    }

    /**
     * Configuración de la caché:
     *
     * @param config           Configuración de la API
     * @param requestParams    Parámetros de la solicitud
     * @param data             Datos a almacenar en caché
     * @param localPluginParam Parámetros locales del complemento
     */
    public void set(ApiConfig config, Map<String, Object> requestParams, Object data, String localPluginParam){

    }

    /**
     * Limpieza de toda la caché; se activa cuando la API se modifica, elimina o deja de estar en línea.
     *
     * @param config           Configuración de la API
     * @param localPluginParam Parámetros locales del complemento
     */
    public void clean(ApiConfig config, String localPluginParam){

    }

    /**
     * Consulta de los datos almacenados en caché:
     *
     * @param config           Configuración de la API
     * @param requestParams    Parámetros de la solicitud
     * @param localPluginParam Parámetros locales del complemento
     * @return
     */
    public Object get(ApiConfig config, Map<String, Object> requestParams, String localPluginParam){
        return null;
    }
}

El método init se ejecuta una sola vez durante la inicialización del complemento y suele utilizarse para configurar pools de conexión, como el pool de conexiones Redis.
El método get permite recuperar los datos almacenados en caché; el primer parámetro es la configuración de la API y el segundo los parámetros de la solicitud.
El método set establece los datos en caché; después de que el ejecutor realice su tarea, se invoca este método. Los primeros dos parámetros son la configuración de la API y los parámetros de la solicitud, respectivamente, mientras que el tercer parámetro corresponde al resultado del ejecutor; si se ha configurado algún complemento de conversión de datos, será el resultado transformado.
El método clean borra toda la caché; se activa cuando la API se modifica, se desconecta o se elimina.

Desarrollo del complemento de conversión de datos

Cree una clase Java que implemente la interfaz 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 {

    /**
     * Nombre del complemento, mostrado en la interfaz para informar al usuario.
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * Descripción funcional del complemento, mostrada en la interfaz para orientar al usuario.
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * Descripción de los parámetros del complemento, mostrada en la interfaz para orientar al usuario.
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * Método de inicialización del complemento, ejecutado al instanciarlo y que se ejecuta solo una vez.
     */
    public void init() {
    }

    /**
     * Lógica de conversión de datos:
     *
     * @param data             Resultado devuelto tras la ejecución del ejecutor
     * @param localPluginParam Parámetros locales del complemento
     * @return
     */
    public Object transform(Object data, String localPluginParam) {
        return null;
    }
}

La lógica de conversión de datos se implementa en el método transform.
El primer parámetro corresponde al resultado de la ejecución del ejecutor; en el caso de un ejecutor SQL, este sería el resultado de la consulta, representado como un objeto List<JSONObject>; puede realizar una conversión explícita de tipo para obtener este formato.
El segundo parámetro son los parámetros locales del complemento.

Desarrollo del complemento global de conversión de datos

Cree una clase Java que implemente la interfaz 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 {

    /**
     * Nombre del complemento, mostrado en la interfaz para informar al usuario.
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * Descripción funcional del complemento, mostrada en la interfaz para orientar al usuario.
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * Descripción de los parámetros del complemento, mostrada en la interfaz para orientar al usuario.
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * Método de inicialización del complemento, ejecutado al instanciarlo y que se ejecuta solo una vez.
     */
    public void init() {
    }

    /**
     * Lógica de conversión de datos:
     *
     * @param data             Respuesta devuelta por la API
     * @param localPluginParam Parámetros locales del complemento global
     * @return
     */
    public Object transform(ResponseDto data, String localPluginParam) {
        return null;
    }
}

La lógica de conversión de datos se implementa en el método transform; el primer parámetro corresponde a la respuesta de la API, mientras que el segundo son los parámetros locales del complemento.

Desarrollo del complemento de alertas

Cree una clase Java que implemente la interfaz 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 {

    /**
     * Nombre del complemento, mostrado en la interfaz para informar al usuario.
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * Descripción funcional del complemento, mostrada en la interfaz para orientar al usuario.
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * Descripción de los parámetros del complemento, mostrada en la interfaz para orientar al usuario.
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * Método de inicialización del complemento, ejecutado al instanciarlo y que se ejecuta solo una vez.
     */
    @Override
    public void init() {

    }

    /**
     * Lógica de generación de alertas:
     *
     * @param e                Error ocurrido
     * @param config           Metadatos de la API
     * @param request          Solicitud recibida
     * @param localPluginParam Parámetros locales del complemento de alertas
     */
    public void alarm(Exception e, ApiConfig config, HttpServletRequest request, String localPluginParam) {

    }
}

La lógica de generación de alertas se implementa en el método alarm.

Desarrollo del complemento de procesamiento de parámetros

Cree una nueva clase Java que implemente 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 {
    /**
     * Nombre del plugin, utilizado para mostrarlo en la interfaz y orientar al usuario.
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * Descripción de la funcionalidad del plugin, mostrada en la interfaz para informar al usuario.
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * Descripción de los parámetros del plugin, mostrada en la interfaz para orientar al usuario.
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * Método de inicialización del plugin, ejecutado únicamente una vez durante la instanciación.
     */
    @Override
    public void init() {

    }

    /**
     * Procesamiento de parámetros.
     *
     * @param requestParam   Parámetros de la solicitud.
     * @param apiConfig      Metadatos de la API.
     * @param localPluginParam Parámetros locales del plugin.
     */
    @Override
    public void process(Map<String, Object> requestParam, ApiConfig apiConfig, String localPluginParam) {

    }
}

La lógica de procesamiento de parámetros se encuentra dentro del método process.
requestParam contiene los parámetros de la solicitud, apiConfig incluye los metadatos de la API y localPluginParam corresponde a los parámetros locales del plugin.

Registro del plugin

Los plugins de DBAPI se registran mediante el mecanismo SPI de Java. Para ello, es necesario realizar los siguientes pasos:

En el directorio resources, cree una carpeta llamada META-INF, y dentro de ella, cree otra carpeta llamada services.
En el archivo META-INF/services/com.gitee.freakchicken.dbapi.plugin.CachePlugin, escriba el nombre de la clase Java del plugin de caché que acaba de desarrollar.
En el archivo META-INF/services/com.gitee.freakchicken.dbapi.plugin.TransformPlugin, indique el nombre de la clase Java del plugin de transformación de datos que ha creado.
En el archivo META-INF/services/com.gitee.freakchicken.dbapi.plugin.GlobalTransformPlugin, escriba el nombre de la clase Java del plugin global de transformación de datos que ha desarrollado.
En el archivo META-INF/services/com.gitee.freakchicken.dbapi.plugin.AlarmPlugin, indique el nombre de la clase Java del plugin de alertas que ha creado.
En el archivo META-INF/services/com.gitee.freakchicken.dbapi.plugin.ParamProcessPlugin, escriba el nombre de la clase Java del plugin de procesamiento de parámetros que ha implementado.

Descripción de los plugins

Parámetros globales

El propósito de diseñar parámetros globales es facilitar el uso de un mismo plugin en diferentes entornos.
Los parámetros globales son específicos de cada plugin y no están relacionados con la API; por ejemplo, el plugin de caché requiere información como la dirección IP y el puerto de Redis. Estos valores se configuran en el archivo conf/plugin.properties.
Los parámetros globales permiten cambiar fácilmente entre distintos entornos; por ejemplo, si el entorno de pruebas y el de producción deben conectarse a direcciones diferentes de Redis, resulta muy conveniente configurar dichas direcciones en el archivo de propiedades.
Si desea añadir nuevas configuraciones globales para su plugin, simplemente agregue las entradas correspondientes en el archivo conf/plugin.properties, como por ejemplo:

properties

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

Para obtener el valor de un parámetro global del plugin:

java

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

Parámetros locales

El objetivo de los parámetros locales es permitir que un mismo plugin sea reutilizado de manera flexible por múltiples APIs.
Los parámetros locales se definen individualmente para cada API; estos valores se configuran desde la interfaz (al crear o editar una API).
Por ejemplo, para el plugin de caché de Redis, cada API puede requerir un tiempo de almacenamiento en caché diferente; así, al invocar el mismo plugin, cada API puede pasar un parámetro distinto para establecer dicho tiempo.
Del mismo modo, para el plugin de cifrado de campos, cada API puede necesitar cifrar campos distintos; por lo tanto, al utilizar este plugin, cada API puede especificar un nombre de campo diferente. De esta forma, un mismo plugin puede ser reutilizado de manera flexible por varias APIs.
Para obtener el valor de un parámetro local del plugin:

java

// Los parámetros locales ya han sido pasados al método correspondiente del plugin; el nombre del parámetro es localPluginParam.
// Por ejemplo, en el método alarm del plugin de alertas, el último parámetro corresponde al parámetro local.
public void alarm(Exception e, ApiConfig config, HttpServletRequest request, String localPluginParam) {

}

Registro de logs del plugin

Si desea registrar mensajes de log dentro del plugin, se recomienda utilizar directamente el logger de la clase padre.

java

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

Descripción del plugin

Todos los plugins deben implementar los tres métodos: getName, getDescription y getParamDescription. Su función es proporcionar información clara sobre la funcionalidad del plugin y el formato de sus parámetros locales en la interfaz.

Uso del plugin

Una vez finalizado el desarrollo del plugin, empaquete el código y copie el archivo JAR generado junto con los archivos JAR de las dependencias del plugin en el directorio extlib o lib de DBAPI (recomendamos colocarlos en el directorio extlib para facilitar su gestión centralizada). Luego reinicie el servicio de DBAPI (en modo cluster, cada nodo debe copiar los archivos JAR y reiniciar el clúster), tras lo cual podrá comenzar a utilizar el plugin.
Si el plugin utiliza parámetros globales, también deberá agregar las correspondientes configuraciones en el archivo conf/plugin.properties y reiniciar el servicio para que surtan efecto (en modo cluster, cada nodo debe realizar esta operación).

Caso completo de desarrollo de un plugin

Demo del caso

Complementos ​

Mercado de complementos ​

Función de los complementos ​

Complemento de caché ​

Complemento de alertas ​

Complemento de conversión de datos ​

Complemento global de conversión de datos ​

Complemento de procesamiento de parámetros ​

Proceso de desarrollo de complementos ​

Preparativos ​

Desarrollo del complemento ​

Desarrollo del complemento de caché ​

Desarrollo del complemento de conversión de datos ​

Desarrollo del complemento global de conversión de datos ​

Desarrollo del complemento de alertas ​

Desarrollo del complemento de procesamiento de parámetros ​

Registro del plugin ​

Descripción de los plugins ​

Parámetros globales ​

Parámetros locales ​

Registro de logs del plugin ​

Descripción del plugin ​

Uso del plugin ​

Caso completo de desarrollo de un plugin ​

Complementos

Mercado de complementos

Función de los complementos

Complemento de caché

Complemento de alertas

Complemento de conversión de datos

Complemento global de conversión de datos

Complemento de procesamiento de parámetros

Proceso de desarrollo de complementos

Preparativos

Desarrollo del complemento

Desarrollo del complemento de caché

Desarrollo del complemento de conversión de datos

Desarrollo del complemento global de conversión de datos

Desarrollo del complemento de alertas

Desarrollo del complemento de procesamiento de parámetros

Registro del plugin

Descripción de los plugins

Parámetros globales

Parámetros locales

Registro de logs del plugin

Descripción del plugin

Uso del plugin

Caso completo de desarrollo de un plugin