Plugins

Marché des plugins

DBAPI fournit officiellement plusieurs plugins couramment utilisés ; vous pouvez télécharger ces plugins sur le marché des plugins.

Rôle des plugins

Les plugins de DBAPI se répartissent en cinq catégories : plugins de conversion de données, plugins de cache, plugins d’alerte, plugins globaux de conversion de données et plugins de traitement des paramètres.
Tous les plugins sont des fichiers JAR ; il suffit de placer ces fichiers dans le répertoire extlib ou lib de DBAPI, puis de redémarrer l’application pour les utiliser.

Plugin de cache

Ce plugin permet de mettre en cache les résultats des exécuteurs. Par exemple, pour un exécuteur SQL, les résultats des requêtes SELECT peuvent être stockés en cache afin d’éviter des interrogations fréquentes de la base de données et ainsi réduire la charge sur celle-ci.
La logique de mise en cache est définie par l’utilisateur, qui peut choisir de stocker les données dans Redis, MongoDB, Elasticsearch, etc.
Si aucune donnée n’est trouvée dans le cache, l’exécution se poursuit normalement, puis le résultat est mis en cache.

Scénario multi‑requêtes avec l’exécuteur SQL

Lorsque l’exécuteur SQL contient plusieurs instructions SQL, le plugin de cache encapsule les résultats de toutes ces requêtes (si une seule instruction dispose d’un plugin de conversion, ce dernier sera appliqué avant le stockage) et met ensuite l’ensemble en cache.

Plugin d’alerte

Lorsqu’une erreur interne survient au sein d’une API, le plugin d’alerte peut envoyer des notifications d’alerte, par e‑mail, SMS, etc.
La logique d’alerte est définie par l’utilisateur.

Plugin de conversion de données

Parfois, une requête SQL ne permet pas d’obtenir directement les données au format souhaité ; dans ce cas, il est plus pratique d’utiliser un plugin de conversion de données pour traiter et transformer les données via du code personnalisé.
Par exemple, on peut anonymiser ou masquer certaines informations comme les numéros de téléphone ou les numéros de carte bancaire dans les résultats d’une requête SQL.

Scénario multi‑requêtes avec l’exécuteur SQL

Dans le cas d’un exécuteur SQL contenant plusieurs instructions, chaque instruction possède son propre plugin de conversion de données ; ce plugin s’applique toujours aux résultats d’une seule requête SQL.

Plugin global de conversion de données

Par défaut, les données renvoyées par une API ont le format suivant : {success:true,msg:xxx,data:xxx}.
Dans certains cas, il est nécessaire de modifier le format des données de réponse ; par exemple, le framework low‑code frontal AMIS exige que les interfaces retournent des données incluant un champ status. Dans ce cas, le plugin global de conversion de données permet de reformater l’ensemble des données renvoyées par l’API.

Différence entre le plugin de conversion de données et le plugin global de conversion de données

Le plugin de conversion de données transforme uniquement les résultats d’un exécuteur spécifique (par exemple, les résultats d’une requête SQL), tandis que le plugin global de conversion de données modifie le format de l’ensemble des données renvoyées par l’API.

Plugin de traitement des paramètres

Ce plugin permet d’effectuer des traitements personnalisés sur les paramètres de requête.
Par exemple, convertir toutes les valeurs des paramètres en majuscules.
Ou encore, si l’API reçoit des paramètres chiffrés, déchiffrer leurs valeurs selon une logique définie par l’utilisateur.
Enfin, lors d’une requête paginée, ajouter un paramètre offset dont la valeur est calculée comme suit : (pageNo - 1) * pageSize.

Notes sur la prise en charge des versions

Le plugin de traitement des paramètres est pris en charge à partir de la version personnelle 4.0.16 et de la version entreprise 4.1.10.

Processus de développement des plugins

Préparation

Les plugins sont développés en Java ; assurez-vous d’avoir installé un environnement de développement Java (version 8 ou supérieure), puis créez un projet Maven et ajoutez la dépendance dbapi-plugin dans votre fichier pom.xml :

xml

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

Développement du plugin

Développement du plugin de cache

Créez une classe Java implémentant l’interface 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 {

    /**
     * Nom du plugin, affiché sur l’interface utilisateur.
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * Description fonctionnelle du plugin, affichée sur l’interface utilisateur.
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * Description des paramètres du plugin, affichée sur l’interface utilisateur.
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * Méthode d’initialisation du plugin, exécutée une seule fois lors de l’instanciation.
     * Elle sert généralement à créer un pool de connexions.
     */
    @Override
    public void init() {

    }

    /**
     * Méthode de configuration du cache :
     *
     * @param config           Configuration de l’API
     * @param requestParams    Paramètres de la requête
     * @param data             Données à mettre en cache
     * @param localPluginParam Paramètres locaux du plugin
     */
    public void set(ApiConfig config, Map<String, Object> requestParams, Object data, String localPluginParam) {

    }

    /**
     * Méthode de suppression de tous les éléments en cache :
     *
     * @param config           Configuration de l’API
     * @param localPluginParam Paramètres locaux du plugin
     */
    public void clean(ApiConfig config, String localPluginParam) {

    }

    /**
     * Méthode de récupération des données en cache :
     *
     * @param config           Configuration de l’API
     * @param requestParams    Paramètres de la requête
     * @param localPluginParam Paramètres locaux du plugin
     * @return
     */
    public Object get(ApiConfig config, Map<String, Object> requestParams, String localPluginParam) {
        return null;
    }
}

La méthode init est exécutée une seule fois lors de l’initialisation du plugin ; elle sert généralement à initialiser un pool de connexions, par exemple un pool Redis.
La méthode get permet de récupérer les données mises en cache ; le premier argument correspond à la configuration de l’API, le second aux paramètres de la requête.
La méthode set configure le cache après l’exécution de l’exécuteur ; le premier argument est la configuration de l’API, le second les paramètres de la requête, et le troisième le résultat de l’exécution. Si un plugin de conversion de données est configuré, ce résultat sera déjà transformé.
La méthode clean vide le cache ; elle est appelée lorsque l’API est modifiée, déployée ou retirée.

Développement du plugin de conversion de données

Créez une classe Java implémentant l’interface 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 {

    /**
     * Nom du plugin, affiché sur l’interface utilisateur.
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * Description fonctionnelle du plugin, affichée sur l’interface utilisateur.
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * Description des paramètres du plugin, affichée sur l’interface utilisateur.
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * Méthode d’initialisation du plugin, exécutée une seule fois lors de l’instanciation.
     */
    public void init() {
    }

    /**
     * Logique de conversion des données :
     *
     * @param data             Données résultant de l’exécution de l’exécuteur
     * @param localPluginParam Paramètres locaux du plugin
     * @return
     */
    public Object transform(Object data, String localPluginParam) {
        return null;
    }
}

La logique de conversion des données est écrite dans la méthode transform.
Le premier argument correspond au résultat de l’exécution de l’exécuteur ; s’il s’agit d’un exécuteur SQL, il s’agira des résultats sous forme de liste de JSON (List<JSONObject>). Il est possible de casters cette donnée en type List<JSONObject>.
Le second argument représente les paramètres locaux du plugin.

Développement du plugin global de conversion de données

Créez une classe Java implémentant l’interface 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 {

    /**
     * Nom du plugin, affiché sur l’interface utilisateur.
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * Description fonctionnelle du plugin, affichée sur l’interface utilisateur.
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * Description des paramètres du plugin, affichée sur l’interface utilisateur.
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * Méthode d’initialisation du plugin, exécutée une seule fois lors de l’instanciation.
     */
    public void init() {
    }

    /**
     * Logique de conversion des données :
     *
     * @param data             Données renvoyées par l’API
     * @param localPluginParam Paramètres locaux du plugin global
     * @return
     */
    public Object transform(ResponseDto data, String localPluginParam) {
        return null;
    }
}

La logique de conversion des données est écrite dans la méthode transform, où le premier argument correspond aux résultats renvoyés par l’API, et le second aux paramètres locaux du plugin.

Développement du plugin d’alerte

Créez une classe Java implémentant l’interface 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 {

    /**
     * Nom du plugin, affiché sur l’interface utilisateur.
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * Description fonctionnelle du plugin, affichée sur l’interface utilisateur.
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * Description des paramètres du plugin, affichée sur l’interface utilisateur.
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * Méthode d’initialisation du plugin, exécutée une seule fois lors de l’instanciation.
     */
    @Override
    public void init() {

    }

    /**
     * Logique d’alerte :
     *
     * @param e                Exception rencontrée
     * @param config           Métadonnées de l’API
     * @param request          Requête associée
     * @param localPluginParam Paramètres locaux du plugin d’alerte
     */
    public void alarm(Exception e, ApiConfig config, HttpServletRequest request, String localPluginParam) {

    }
}

La logique d’alerte est écrite dans la méthode alarm.

Développement du plugin de traitement des paramètres

Créez une nouvelle classe Java qui implémente 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 {
    /**
     * Nom du plugin, affiché sur la page pour guider l'utilisateur
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * Description de la fonctionnalité du plugin, affichée sur la page pour guider l'utilisateur
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * Description des paramètres du plugin, affichée sur la page pour guider l'utilisateur
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * Méthode d'initialisation du plugin, exécutée lors de l'instanciation et ne s'exécute qu'une seule fois
     */
    @Override
    public void init() {

    }

    /**
     * Traitement des paramètres
     *
     * @param requestParam     Paramètres de la requête
     * @param apiConfig        Métadonnées de l'API
     * @param localPluginParam Paramètres locaux du plugin
     */
    @Override
    public void process(Map<String, Object> requestParam, ApiConfig apiConfig, String localPluginParam) {

    }
}

La logique de traitement des paramètres est écrite dans la méthode process ;
requestParam correspond aux paramètres de la requête, apiConfig aux métadonnées de l'API, et localPluginParam aux paramètres locaux du plugin.

Enregistrement des plugins

Les plugins DBAPI utilisent le mécanisme SPI de Java pour leur enregistrement ; voici les étapes à suivre :

Créez un dossier META-INF dans le répertoire resources, puis créez un sous-dossier services à l'intérieur de META-INF.
Dans le fichier META-INF/services, créez un fichier nommé com.gitee.freakchicken.dbapi.plugin.CachePlugin et indiquez-y le nom de la classe Java du plugin de cache que vous venez d'écrire.
Dans le fichier META-INF/services, créez un fichier nommé com.gitee.freakchicken.dbapi.plugin.TransformPlugin et indiquez-y le nom de la classe Java du plugin de transformation de données que vous venez d'écrire.
Dans le fichier META-INF/services, créez un fichier nommé com.gitee.freakchicken.dbapi.plugin.GlobalTransformPlugin et indiquez-y le nom de la classe Java du plugin de transformation globale que vous venez d'écrire.
Dans le fichier META-INF/services, créez un fichier nommé com.gitee.freakchicken.dbapi.plugin.AlarmPlugin et indiquez-y le nom de la classe Java du plugin d'alerte que vous venez d'écrire.
Dans le fichier META-INF/services, créez un fichier nommé com.gitee.freakchicken.dbapi.plugin.ParamProcessPlugin et indiquez-y le nom de la classe Java du plugin de traitement des paramètres que vous venez d'écrire.

Description des plugins

Paramètres globaux

L'objectif de concevoir des paramètres globaux est de faciliter l'utilisation d'un même plugin dans différents environnements.
Les paramètres globaux sont propres à chaque plugin et indépendants de l'API ; par exemple, un plugin de cache nécessite les informations d'adresse IP et de port du serveur Redis. Ces paramètres sont configurés dans le fichier conf/plugin.properties.
Les paramètres globaux permettent notamment de passer facilement d'un environnement à un autre : si l'environnement de test et celui de production doivent se connecter à des adresses Redis différentes, il suffit d'indiquer ces informations dans le fichier de configuration.
Si l'utilisateur souhaite ajouter une configuration globale pour un plugin, il peut directement y insérer les paramètres dans le fichier conf/plugin.properties, par exemple :

properties

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

Méthode pour récupérer la valeur d'un paramètre global :

java

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

Paramètres locaux

L'objectif de concevoir des paramètres locaux est de permettre à un même plugin d'être réutilisé de manière flexible par plusieurs API.
Les paramètres locaux sont spécifiés individuellement pour chaque API ; leurs valeurs sont définies via l'interface utilisateur (lors de la création ou de la modification d'une API).
Par exemple, pour un plugin de cache Redis, chaque API peut avoir besoin d'une durée de cache différente ; ainsi, lorsqu'une API utilise ce même plugin, elle peut transmettre un paramètre de temps spécifique.
De même, pour un plugin de chiffrement de champs, chaque API peut nécessiter de chiffrer des champs distincts ; chaque API peut donc fournir un nom de champ différent lors de l'appel au même plugin. Cela permet à un même plugin d'être réutilisé de façon flexible par plusieurs API.
Méthode pour récupérer la valeur d'un paramètre local :

java

// Les paramètres locaux ont déjà été passés à la méthode correspondante du plugin ; le nom du paramètre est localPluginParam.
// Par exemple, dans la méthode alarm du plugin d'alerte, le dernier paramètre correspond aux paramètres locaux.
public void alarm(Exception e, ApiConfig config, HttpServletRequest request, String localPluginParam) {

}

Journalisation dans les plugins

Si vous souhaitez afficher des messages de journalisation au sein d'un plugin, il est recommandé d'utiliser directement la méthode logger héritée de la classe parente.

java

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

Description des plugins

Tous les plugins doivent implémenter trois méthodes : getName, getDescription et getParamDescription. Leur rôle est d'informer l'utilisateur, sur l'interface, de la fonctionnalité du plugin ainsi que du format des paramètres locaux.

Utilisation des plugins

Une fois le plugin développé, procédez à son empaquetage, puis copiez le fichier JAR généré ainsi que les fichiers JAR dépendants dans le répertoire extlib ou lib de DBAPI (nous recommandons vivement d'utiliser le répertoire extlib pour une gestion centralisée). Redémarrez ensuite le service DBAPI ( en mode cluster, chaque nœud doit copier le fichier JAR et redémarrer le cluster), après quoi le plugin sera opérationnel.
Si le plugin utilise des paramètres globaux, veuillez également ajouter les configurations correspondantes dans le fichier conf/plugin.properties et redémarrer pour que les modifications prennent effet ( en mode cluster, chaque nœud doit effectuer cette étape).

Cas pratique complet de développement de plugin

Exemple de démonstration

Plugins ​

Marché des plugins ​

Rôle des plugins ​

Plugin de cache ​

Plugin d’alerte ​

Plugin de conversion de données ​

Plugin global de conversion de données ​

Plugin de traitement des paramètres ​

Processus de développement des plugins ​

Préparation ​

Développement du plugin ​

Développement du plugin de cache ​

Développement du plugin de conversion de données ​

Développement du plugin global de conversion de données ​

Développement du plugin d’alerte ​

Développement du plugin de traitement des paramètres ​

Enregistrement des plugins ​

Description des plugins ​

Paramètres globaux ​

Paramètres locaux ​

Journalisation dans les plugins ​

Description des plugins ​

Utilisation des plugins ​

Cas pratique complet de développement de plugin ​

Plugins

Marché des plugins

Rôle des plugins

Plugin de cache

Plugin d’alerte

Plugin de conversion de données

Plugin global de conversion de données

Plugin de traitement des paramètres

Processus de développement des plugins

Préparation

Développement du plugin

Développement du plugin de cache

Développement du plugin de conversion de données

Développement du plugin global de conversion de données

Développement du plugin d’alerte

Développement du plugin de traitement des paramètres

Enregistrement des plugins

Description des plugins

Paramètres globaux

Paramètres locaux

Journalisation dans les plugins

Description des plugins

Utilisation des plugins

Cas pratique complet de développement de plugin