Plugins

Mercado de Plugins

• A DBAPI oficial já disponibilizou alguns plugins comuns; você pode baixá-los no Mercado de Plugins.

Função dos Plugins

• Os plugins da DBAPI são divididos em 5 categorias: plugins de conversão de dados, plugins de cache, plugins de alerta, plugins globais de conversão de dados e plugins de processamento de parâmetros.
• Todos os plugins são pacotes JAR; basta colocar o arquivo JAR no diretório extlib ou lib da DBAPI e reiniciar o sistema para que estejam disponíveis.

Plugin de Cache

• O plugin de cache armazena os resultados dos executores. Por exemplo, no executor SQL, ele armazena os resultados das consultas, evitando assim consultas frequentes ao banco de dados e reduzindo a carga sobre este.
• A lógica de cache é definida pelo usuário, que pode armazenar os dados em Redis, MongoDB, Elasticsearch, entre outros.
• Quando não é possível obter os dados do cache, o executor é executado e o resultado é então armazenado no cache.

Cenário de múltiplas instruções SQL

No caso do executor SQL, se um único executor contiver várias instruções SQL, o plugin de cache encapsulará os resultados dessas instruções ( se uma única instrução tiver configurado um plugin de conversão, esse será aplicado primeiro ) em um único conjunto antes de armazená-lo no cache.

Plugin de Alerta

• Quando ocorre um erro interno na API, o plugin de alerta pode enviar notificações de alerta, como e-mails ou mensagens SMS.
• A lógica de geração de alertas é definida pelo próprio usuário.

Plugin de Conversão de Dados

• Às vezes, o SQL não consegue retornar os dados no formato desejado de imediato. Nesses casos, é útil utilizar um plugin de conversão de dados para processar e transformar os dados por meio de código personalizado.
• Por exemplo, é possível realizar a desanonymização de números de telefone ou de cartões bancários obtidos nas consultas SQL.

Cenário de múltiplas instruções SQL

No caso do executor SQL, se um único executor contiver várias instruções SQL, cada instrução terá seu próprio plugin de conversão de dados configurado. Cada plugin atua exclusivamente sobre os resultados da consulta correspondente.

Plugin Global de Conversão de Dados

• Por padrão, os dados retornados pela API têm o formato {success:true,msg:xxx,data:xxx}.
• Em algumas situações, é necessário alterar o formato dos dados de resposta; por exemplo, o framework de low-code frontal AMIS exige que as respostas das APIs incluam um campo status. Nesse caso, o plugin global de conversão de dados pode ser utilizado para ajustar o formato de todos os dados retornados pela API.

Diferença entre o plugin de conversão de dados e o plugin global de conversão de dados

O plugin de conversão de dados realiza a transformação do formato dos resultados gerados pelos executores (por exemplo, após a execução de uma consulta SQL), enquanto o plugin global de conversão de dados modifica o formato de toda a resposta da API.

Plugin de Processamento de Parâmetros

• Permite ao usuário realizar operações personalizadas sobre os parâmetros de solicitação.
• Por exemplo, converter todos os valores dos parâmetros para maiúsculas.
• Ou, em casos de APIs que recebem parâmetros criptografados, implementar uma lógica personalizada para descriptografar esses valores.
• Em consultas paginadas, o usuário pode adicionar um parâmetro offset, cujo valor corresponde a (pageNo-1)*pageSize.

Suporte por versão

O plugin de processamento de parâmetros passou a ser suportado a partir da versão 4.0.16 na edição pessoal e da versão 4.1.10 na edição empresarial.

Processo de Desenvolvimento de Plugins

Preparativos

• Os plugins são desenvolvidos em Java. Prepare um ambiente de desenvolvimento Java (versão 8 ou superior), crie um projeto Maven e adicione a dependência dbapi-plugin ao arquivo pom.xml:

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

Desenvolvimento do Plugin

Desenvolvimento do Plugin de Cache

• Crie uma classe Java que implemente a interface 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 {

    /**
     * Nome do plugin, exibido na interface para informar o usuário.
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * Descrição funcional do plugin, exibida na interface para orientar o usuário.
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * Descrição dos parâmetros do plugin, exibida na interface para orientar o usuário.
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * Método de inicialização do plugin, executado apenas uma vez durante a instalação,
     * geralmente usado para criar pools de conexão.
     */
    @Override
    public void init() {

    }

    /**
     * Configuração do cache:
     *
     * @param config           Configuração da API
     * @param requestParams    Parâmetros da requisição
     * @param data             Dados a serem armazenados no cache
     * @param localPluginParam Parâmetros locais do plugin
     */
    public void set(ApiConfig config, Map<String, Object> requestParams, Object data, String localPluginParam) {

    }

    /**
     * Limpeza de todo o cache:
     *
     * @param config           Configuração da API
     * @param localPluginParam Parâmetros locais do plugin
     */
    public void clean(ApiConfig config, String localPluginParam) {

    }

    /**
     * Consulta do cache:
     *
     * @param config           Configuração da API
     * @param requestParams    Parâmetros da requisição
     * @param localPluginParam Parâmetros locais do plugin
     * @return
     */
    public Object get(ApiConfig config, Map<String, Object> requestParams, String localPluginParam) {
        return null;
    }
}

• O método init é responsável pela inicialização do plugin e é executado apenas uma vez, geralmente para configurar pools de conexão, como o pool de conexões Redis.

• O método get recupera os dados armazenados no cache; o primeiro parâmetro é a configuração da API, e o segundo são os parâmetros da requisição.

• O método set define os dados a serem armazenados no cache; após a execução do executor, esse método é chamado. O primeiro parâmetro é a configuração da API, o segundo são os parâmetros da requisição e o terceiro é o resultado da execução do executor — caso haja um plugin de conversão de dados configurado, será o resultado convertido.

• O método clean limpa todo o cache; essa operação é acionada sempre que a API é modificada, desativada ou removida.

Desenvolvimento do Plugin de Conversão de Dados

• Crie uma classe Java que implemente a interface 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 {

    /**
     * Nome do plugin, exibido na interface para informar o usuário.
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * Descrição funcional do plugin, exibida na interface para orientar o usuário.
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * Descrição dos parâmetros do plugin, exibida na interface para orientar o usuário.
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * Método de inicialização do plugin, executado apenas uma vez durante a instalação.
     */
    public void init() {
    }

    /**
     * Lógica de conversão de dados:
     *
     * @param data             Resultado da execução do executor
     * @param localPluginParam Parâmetros locais do plugin
     * @return
     */
    public Object transform(Object data, String localPluginParam) {
        return null;
    }
}

• A lógica de conversão de dados é escrita no método transform.

• O primeiro parâmetro é o resultado da execução do executor; no caso de um executor SQL, trata-se do resultado da consulta, representado pelo tipo de dado List<JSONObject>. É possível fazer um cast explícito para List<JSONObject>.

• O segundo parâmetro são os parâmetros locais do plugin.

Desenvolvimento do Plugin Global de Conversão de Dados

• Crie uma classe Java que implemente a interface 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 {

    /**
     * Nome do plugin, exibido na interface para informar o usuário.
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * Descrição funcional do plugin, exibida na interface para orientar o usuário.
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * Descrição dos parâmetros do plugin, exibida na interface para orientar o usuário.
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * Método de inicialização do plugin, executado apenas uma vez durante a instalação.
     */
    public void init() {
    }

    /**
     * Lógica de conversão de dados:
     *
     * @param data             Dados retornados pela API
     * @param localPluginParam Parâmetros locais do plugin global
     * @return
     */
    public Object transform(ResponseDto data, String localPluginParam) {
        return null;
    }
}

• A lógica de conversão de dados é escrita no método transform; o primeiro parâmetro é o resultado da execução da API, e o segundo são os parâmetros locais do plugin.

Desenvolvimento do Plugin de Alerta

• Crie uma classe Java que implemente a interface 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 {

    /**
     * Nome do plugin, exibido na interface para informar o usuário.
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * Descrição funcional do plugin, exibida na interface para orientar o usuário.
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * Descrição dos parâmetros do plugin, exibida na interface para orientar o usuário.
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * Método de inicialização do plugin, executado apenas uma vez durante a instalação.
     */
    @Override
    public void init() {

    }

    /**
     * Lógica de geração de alertas:
     *
     * @param e                Exceção
     * @param config           Metadados da API
     * @param request          Requisição
     * @param localPluginParam Parâmetros locais do plugin de alerta
     */
    public void alarm(Exception e, ApiConfig config, HttpServletRequest request, String localPluginParam) {

    }
}

• A lógica de geração de alertas é escrita no método alarm.

Desenvolvimento do Plugin de Processamento de Parâmetros

• Crie uma nova classe Java que implemente com.gitee.freakchicken.dbapi.plugin.ParamProcessPlugin

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 {
    /**
     * Nome do plugin, utilizado para exibição na página e orientação ao usuário
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * Descrição da funcionalidade do plugin, utilizada para exibição na página e orientação ao usuário
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * Descrição dos parâmetros do plugin, utilizada para exibição na página e orientação ao usuário
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * Método de inicialização do plugin, executado ao instanciar o plugin e sempre será executado apenas uma vez
     */
    @Override
    public void init() {

    }

    /**
     * Processamento dos parâmetros
     *
     * @param requestParam     Parâmetros da requisição
     * @param apiConfig        Metadados da API
     * @param localPluginParam Parâmetros locais do plugin
     */
    @Override
    public void process(Map<String, Object> requestParam, ApiConfig apiConfig, String localPluginParam) {

    }
}

• A lógica de processamento dos parâmetros é escrita no método process.
• requestParam corresponde aos parâmetros da requisição, apiConfig aos metadados da API e localPluginParam aos parâmetros locais do plugin.

Registro do plugin

• Os plugins do DBAPI são registrados utilizando a mecânica SPI do Java. Para isso, siga os passos abaixo:

1. No diretório resources, crie uma pasta chamada META-INF e, dentro dela, crie outra pasta chamada services.

2. Na pasta META-INF/services, crie um arquivo chamado com.gitee.freakchicken.dbapi.plugin.CachePlugin e insira nele o nome da classe Java do plugin de cache que acabou de ser desenvolvido.

3. Na pasta META-INF/services, crie outro arquivo chamado com.gitee.freakchicken.dbapi.plugin.TransformPlugin e insira nele o nome da classe Java do plugin de transformação de dados que acabou de ser desenvolvido.

4. Na pasta META-INF/services, crie mais um arquivo chamado com.gitee.freakchicken.dbapi.plugin.GlobalTransformPlugin e insira nele o nome da classe Java do plugin de transformação global de dados que acabou de ser desenvolvido.

5. Na pasta META-INF/services, crie ainda um arquivo chamado com.gitee.freakchicken.dbapi.plugin.AlarmPlugin e insira nele o nome da classe Java do plugin de alarmes que acabou de ser desenvolvido.

6. Na pasta META-INF/services, crie finalmente um arquivo chamado com.gitee.freakchicken.dbapi.plugin.ParamProcessPlugin e insira nele o nome da classe Java do plugin de processamento de parâmetros que acabou de ser desenvolvido.

Explicação dos plugins

Parâmetros globais

• O objetivo de projetar parâmetros globais para os plugins é facilitar seu uso em diferentes ambientes.
• Os parâmetros globais são específicos de cada plugin e não estão relacionados à API; por exemplo, o plugin de cache precisa das informações de IP e porta do Redis. Essas configurações são definidas no arquivo conf/plugin.properties.
• Os parâmetros globais servem principalmente para facilitar a troca entre ambientes distintos: por exemplo, se o ambiente de teste e o de produção precisam conectar-se a endereços diferentes do Redis, é conveniente configurar essas informações no arquivo de configuração.
• Caso o usuário deseje adicionar novas configurações globais ao plugin, basta acrescentar as informações no arquivo conf/plugin.properties, como:

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

• Para obter o valor de um parâmetro global do plugin, utilize o seguinte código:

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

Parâmetros locais

• O objetivo de projetar parâmetros locais para os plugins é permitir que um mesmo plugin seja reutilizado de forma flexível por várias APIs.

• Os parâmetros locais são especificados individualmente para cada API, sendo configurados diretamente na interface (ao criar ou editar uma API).

• Por exemplo, para o plugin de cache do Redis, diferentes APIs podem necessitar de tempos de expiração distintos; assim, ao chamar o mesmo plugin de cache, cada API pode passar um parâmetro de tempo diferente.

• Outro exemplo: para o plugin de criptografia de campos, cada API pode precisar criptografar campos diferentes; dessa forma, ao utilizar o mesmo plugin de criptografia, cada API pode informar um nome de campo específico. Assim, um único plugin pode ser reutilizado de maneira flexível por múltiplas APIs.

• Para obter o valor de um parâmetro local do plugin, utilize o seguinte código:

// Os parâmetros locais já foram passados para o método correspondente do plugin,
// sendo o nome do parâmetro indicado pelo argumento localPluginParam.
// Por exemplo, no método alarm do plugin de alarmes, o último parâmetro é justamente o parâmetro local.
public void alarm(Exception e, ApiConfig config, HttpServletRequest request, String localPluginParam) {

}

Impressão de logs no plugin

• Se desejar imprimir logs dentro do plugin, recomenda-se utilizar diretamente o logger da classe pai:

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

Descrição do plugin

• Todos os plugins devem implementar os três métodos: getName, getDescription e getParamDescription, cuja função é fornecer ao usuário, na interface, informações claras sobre a finalidade do plugin e o formato dos parâmetros locais.

Uso do plugin

• Após concluir o desenvolvimento do plugin, faça o empacotamento e copie o arquivo JAR gerado, juntamente com os arquivos JAR das dependências do plugin, para o diretório extlib ou lib do DBAPI (recomendamos colocá‑los no diretório extlib para facilitar a gestão unificada). Em seguida, reinicie o serviço DBAPI (em modo cluster, todos os nós devem copiar os arquivos JAR e reiniciar o cluster). Após isso, o plugin estará pronto para uso.
• Caso o plugin utilize parâmetros globais, também será necessário adicionar as respectivas configurações no arquivo conf/plugin.properties e reiniciar o sistema para que as alterações entrem em vigor (em modo cluster, cada nó deve realizar essa configuração e reiniciar).

Caso completo de desenvolvimento de plugin

Demo do caso