Plugins

Plugin-Markt

• Die offizielle DBAPI‑Version stellt bereits einige häufig genutzte Plugins bereit. Sie können diese über den Plugin‑Markt herunterladen.

Funktionen der Plugins

• Die DBAPI‑Plugins lassen sich in fünf Kategorien einteilen: Datenkonvertierungs‑Plugins, Cache‑Plugins, Alarm‑Plugins, globale Datenkonvertierungs‑Plugins sowie Parameterverarbeitungs‑Plugins.
• Alle Plugins liegen als JAR‑Dateien vor und müssen entweder im extlib‑ oder im lib‑Verzeichnis der DBAPI abgelegt werden; nach einem Neustart der DBAPI sind sie einsatzbereit.

Cache‑Plugin

• Das Cache‑Plugin speichert die Ergebnisse von Ausführern, etwa beim SQL‑Executor: Abfragen werden zwischengespeichert, um wiederholte Datenbankabfragen zu vermeiden und die Datenbank zu entlasten.
• Die Caching‑Logik wird vom Benutzer selbst implementiert; die Daten können beispielsweise in Redis, MongoDB, Elasticsearch usw. gespeichert werden.
• Wird ein Datensatz nicht aus dem Cache gefunden, erfolgt die Ausführung des Ausführers, und das Ergebnis wird anschließend erneut im Cache gespeichert.

Mehrere SQL‑Anweisungen im SQL‑Executor

Bei einem SQL‑Executor, der mehrere SQL‑Anweisungen enthält, kapselt das Cache‑Plugin die Ergebnisse aller Anweisungen – sofern für einzelne Anweisungen Konvertierungs‑Plugins konfiguriert sind, werden deren Ergebnisse zuerst konvertiert – und speichert das Gesamtergebnis.

Alarm‑Plugin

• Wenn innerhalb einer API ein Fehler auftritt, kann das Alarm‑Plugin entsprechende Warnmeldungen versenden, etwa per E‑Mail oder SMS.
• Die Alarmlogik wird vom Benutzer selbst definiert.

Datenkonvertierungs‑Plugin

• Manchmal liefert eine SQL‑Abfrage nicht direkt das gewünschte Datenformat; mit Hilfe eines Datenkonvertierungs‑Plugins lässt sich dies leichter erreichen. Der Benutzer programmiert die Logik zur Datenkonvertierung selbst.
• Beispielsweise können Telefonnummern oder Bankkontonummern im SQL‑Ergebnis maskiert oder formatiert werden.

Mehrere SQL‑Anweisungen im SQL‑Executor

Bei einem SQL‑Executor, der mehrere SQL‑Anweisungen enthält, wird für jede einzelne Anweisung ein eigenes Datenkonvertierungs‑Plugin konfiguriert; jedes Plugin konvertiert ausschließlich die Ergebnisse der jeweiligen SQL‑Anweisung.

Globales Datenkonvertierungs‑Plugin

• Standardmäßig werden von der API zurückgegebene Daten im Format {success:true,msg:xxx,data:xxx} geliefert.
• In manchen Fällen ist jedoch eine Umwandlung des Antwortformats erforderlich; beispielsweise verlangt das Low‑Code‑Frontend‑Framework AMIS, dass die API‑Antwort das Feld status enthält. Hier bietet sich das globale Datenkonvertierungs‑Plugin an, das das gesamte Rückgabedatum der API entsprechend umwandelt.

Unterschied zwischen Datenkonvertierungs‑ und globalem Datenkonvertierungs‑Plugin

Das Datenkonvertierungs‑Plugin wandelt das Ergebnis eines Ausführers um (z. B. die Ergebnisse einer SQL‑Abfrage), während das globale Datenkonvertierungs‑Plugin das gesamte Ergebnis einer API‑Ausführung umwandelt.

Parameterverarbeitungs‑Plugin

• Es ermöglicht benutzerdefinierte Verarbeitungen der Anforderungsparameter.
• Beispiele: Umwandlung aller Parameterwerte in Großbuchstaben; Entschlüsselung verschlüsselter Parameter durch benutzerdefinierte Logik; bei paginierten Abfragen Hinzufügen eines Offset‑Parameters, dessen Wert gleich (pageNo-1)*pageSize ist.

Versionsunterstützung

Das Parameterverarbeitungs‑Plugin wird ab Version 4.0.16 in der Personal‑Edition sowie ab Version 4.1.10 in der Enterprise‑Edition unterstützt.

Entwicklungsprozess eines Plugins

Vorbereitungen

• Plugins werden in Java entwickelt. Stellen Sie sicher, dass eine Java‑Entwicklungsumgebung (Java 8 oder höher) vorhanden ist, und erstellen Sie ein neues Maven‑Projekt. Fügen Sie im POM‑File die Abhängigkeit dbapi-plugin hinzu:

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

Plugin‑Entwicklung

Entwicklung des Cache‑Plugins

• Erstellen Sie eine neue Java‑Klasse, die das Interface com.gitee.freakchicken.dbapi.plugin.CachePlugin implementiert:

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

import java.util.Map;

public class Cdemo extends CachePlugin {

    /**
     * Name des Plugins, der auf der Benutzeroberfläche angezeigt wird.
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * Beschreibung der Funktionalität des Plugins, die auf der Benutzeroberfläche angezeigt wird.
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * Beschreibung der Plugin‑Parameter, die auf der Benutzeroberfläche angezeigt wird.
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * Initialisierungsmethode des Plugins, die beim Instanziieren ausgeführt wird und nur einmalig aufgerufen wird.
     * Häufig dient sie dazu, einen Verbindungspool zu erstellen.
     */
    @Override
    public void init() {

    }

    /**
     * Methode zum Setzen des Caches:
     *
     * @param config           API‑Konfiguration
     * @param requestParams    Anforderungsparameter
     * @param data             Zu speichernde Daten
     * @param localPluginParam Lokale Plugin‑Parameter
     */
    public void set(ApiConfig config, Map<String, Object> requestParams, Object data, String localPluginParam){

    }

    /**
     * Methode zum Löschen des gesamten Caches:
     *
     * @param config           API‑Konfiguration
     * @param localPluginParam Lokale Plugin‑Parameter
     */
    public void clean(ApiConfig config, String localPluginParam){

    }

    /**
     * Methode zum Abrufen des Caches:
     *
     * @param config           API‑Konfiguration
     * @param requestParams    Anforderungsparameter
     * @param localPluginParam Lokale Plugin‑Parameter
     * @return
     */
    public Object get(ApiConfig config, Map<String, Object> requestParams, String localPluginParam){
        return null;
    }
}

• Die Methode init() wird einmalig beim Laden des Plugins aufgerufen und dient meist der Initialisierung von Ressourcen wie Verbindungspools (z. B. Redis‑Verbindungspool).

• Die Methode get() dient zum Abrufen von Daten aus dem Cache; ihr erster Parameter ist die API‑Konfiguration, der zweite die Anforderungsparameter.

• Die Methode set() wird aufgerufen, sobald der Ausführer seine Arbeit abgeschlossen hat; ihr erster Parameter ist die API‑Konfiguration, der zweite die Anforderungsparameter, der dritte das Ergebnis des Ausführers – sofern ein Datenkonvertierungs‑Plugin konfiguriert wurde, handelt es sich um das konvertierte Ergebnis.

• Die Methode clean() wird aufgerufen, wenn die API geändert, deaktiviert oder entfernt wird; sie löscht sämtliche im Cache gespeicherten Daten.

Entwicklung des Datenkonvertierungs‑Plugins

• Erstellen Sie eine neue Java‑Klasse, die das Interface com.gitee.freakchicken.dbapi.plugin.TransformPlugin implementiert:

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 {

    /**
     * Name des Plugins, der auf der Benutzeroberfläche angezeigt wird.
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * Beschreibung der Funktionalität des Plugins, die auf der Benutzeroberfläche angezeigt wird.
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * Beschreibung der Plugin‑Parameter, die auf der Benutzeroberfläche angezeigt wird.
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * Initialisierungsmethode des Plugins, die beim Instanziieren ausgeführt wird und nur einmalig aufgerufen wird.
     */
    public void init() {
    }

    /**
     * Logik zur Datenkonvertierung:
     *
     * @param data             Ergebnis des Ausführers
     * @param localPluginParam Lokale Plugin‑Parameter
     * @return
     */
    public Object transform(Object data, String localPluginParam) {
        return null;
    }
}

• Die Logik zur Datenkonvertierung wird in der Methode transform() implementiert.

• Der erste Parameter ist das Ergebnis des Ausführers; bei einem SQL‑Executor handelt es sich um die SQL‑Ergebnisse, die als List<JSONObject> vorliegen. Diese Daten können explizit in den Typ List<JSONObject> umgewandelt werden.

• Der zweite Parameter sind die lokalen Plugin‑Parameter.

Entwicklung des globalen Datenkonvertierungs‑Plugins

• Erstellen Sie eine neue Java‑Klasse, die das Interface com.gitee.freakchicken.dbapi.plugin.GlobalTransformPlugin implementiert:

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

public class AmisGlobalTransformPlugin extends GlobalTransformPlugin {

    /**
     * Name des Plugins, der auf der Benutzeroberfläche angezeigt wird.
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * Beschreibung der Funktionalität des Plugins, die auf der Benutzeroberfläche angezeigt wird.
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * Beschreibung der Plugin‑Parameter, die auf der Benutzeroberfläche angezeigt wird.
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * Initialisierungsmethode des Plugins, die beim Instanziieren ausgeführt wird und nur einmalig aufgerufen wird.
     */
    public void init() {
    }

    /**
     * Logik zur Datenkonvertierung:
     *
     * @param data             Rückgabe der API
     * @param localPluginParam Lokale Plugin‑Parameter
     * @return
     */
    public Object transform(ResponseDto data, String localPluginParam) {
        return null;
    }
}

• Die Logik zur Datenkonvertierung wird in der Methode transform() implementiert; der erste Parameter ist das Ergebnis der API‑Ausführung, der zweite die lokalen Plugin‑Parameter.

Entwicklung des Alarm‑Plugins

• Erstellen Sie eine neue Java‑Klasse, die das Interface com.gitee.freakchicken.dbapi.plugin.AlarmPlugin implementiert:

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

import javax.servlet.http.HttpServletRequest;

public class EmailAlarmPlugin extends AlarmPlugin {

    /**
     * Name des Plugins, der auf der Benutzeroberfläche angezeigt wird.
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * Beschreibung der Funktionalität des Plugins, die auf der Benutzeroberfläche angezeigt wird.
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * Beschreibung der Plugin‑Parameter, die auf der Benutzeroberfläche angezeigt wird.
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * Initialisierungsmethode des Plugins, die beim Instanziieren ausgeführt wird und nur einmalig aufgerufen wird.
     */
    @Override
    public void init() {

    }

    /**
     * Alarmlogik:
     *
     * @param e                Ausnahme
     * @param config           API‑Metadaten
     * @param request          Anforderung
     * @param localPluginParam Lokale Plugin‑Parameter
     */
    public void alarm(Exception e, ApiConfig config, HttpServletRequest request, String localPluginParam) {

    }
}

• Die Alarmlogik wird in der Methode alarm() implementiert.

Entwicklung des Parameterverarbeitungs‑Plugins

• Erstellen Sie eine neue Java-Klasse und implementieren Sie 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 {
    /**
     * Name des Plugins, der auf der Seite angezeigt wird, um den Benutzer zu informieren
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * Beschreibung der Funktionalität des Plugins, die auf der Seite angezeigt wird, um den Benutzer zu informieren
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * Beschreibung der Plugin-Parameter, die auf der Seite angezeigt wird, um den Benutzer zu informieren
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * Initialisierungsmethode des Plugins, die beim Instanziieren des Plugins ausgeführt wird und nur einmalig erfolgt
     */
    @Override
    public void init() {

    }

    /**
     * Verarbeitung der Parameter
     *
     * @param requestParam   Die Anfrageparameter
     * @param apiConfig      Metadaten der API
     * @param localPluginParam Lokale Parameter des Verarbeitungsplugins
     */
    @Override
    public void process(Map<String, Object> requestParam, ApiConfig apiConfig, String localPluginParam) {

    }
}

• Die Logik zur Verarbeitung der Parameter wird in der Methode process implementiert.
• requestParam sind die Anfrageparameter, apiConfig sind die Metadaten der API und localPluginParam sind die lokalen Parameter des Plugins.

Registrierung von Plugins

• DBAPI-Plugins werden mithilfe der Java-SPI-Mechanismus registriert. Folgende Schritte sind erforderlich:

1. Erstellen Sie im Verzeichnis resources einen neuen Ordner namens META-INF, und innerhalb dieses Ordners legen Sie einen weiteren Ordner namens services an.

2. Erstellen Sie im Ordner META-INF/services eine Datei namens com.gitee.freakchicken.dbapi.plugin.CachePlugin und tragen Sie darin den Namen der eben erstellten Java-Klasse für das Cache-Plugin ein.

3. Erstellen Sie im Ordner META-INF/services eine weitere Datei namens com.gitee.freakchicken.dbapi.plugin.TransformPlugin und geben Sie darin den Namen der eben erstellten Java-Klasse für das Datenkonvertierungs-Plugin an.

4. Erstellen Sie im Ordner META-INF/services eine Datei namens com.gitee.freakchicken.dbapi.plugin.GlobalTransformPlugin und tragen Sie darin den Namen der eben erstellten Java-Klasse für das globale Datenkonvertierungs-Plugin ein.

5. Erstellen Sie im Ordner META-INF/services eine Datei namens com.gitee.freakchicken.dbapi.plugin.AlarmPlugin und geben Sie darin den Namen der eben erstellten Java-Klasse für das Alarm-Plugin an.

6. Erstellen Sie im Ordner META-INF/services eine Datei namens com.gitee.freakchicken.dbapi.plugin.ParamProcessPlugin und tragen Sie darin den Namen der eben erstellten Java-Klasse für das Parameterverarbeitungs-Plugin ein.

Erläuterungen zu den Plugins

Globale Parameter

• Zweck der Definition globaler Plugin-Parameter ist es, die Nutzung eines Plugins in verschiedenen Umgebungen zu erleichtern.
• Globale Plugin-Parameter sind spezifische Einstellungen jedes einzelnen Plugins und unabhängig von der jeweiligen API. Beispielsweise benötigt das Cache-Plugin die IP-Adresse und den Port des Redis-Servers; diese Informationen werden in der Konfigurationsdatei conf/plugin.properties festgelegt.
• Diese globalen Parameter dienen vor allem dazu, den Wechsel zwischen unterschiedlichen Umgebungen zu vereinfachen. Wenn beispielsweise die Testumgebung und die Produktionsumgebung unterschiedliche Redis-Adressen verwenden, lassen sich die entsprechenden Adressinformationen einfach in der Konfigurationsdatei hinterlegen.
• Falls Nutzer zusätzliche globale Konfigurationen hinzufügen möchten, können sie dies direkt in der Datei conf/plugin.properties tun, etwa wie folgt:

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

• So rufen Sie den Wert eines globalen Plugin-Parameters ab:

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

Lokale Parameter

• Der Zweck der Definition lokaler Plugin-Parameter besteht darin, ein Plugin flexibel für mehrere APIs wiederverwenden zu können.

• Lokale Plugin-Parameter sind spezifische Einstellungen, die für jede einzelne API separat definiert werden. Die Werte dieser Parameter werden über die Benutzeroberfläche konfiguriert (beim Erstellen oder Bearbeiten einer API).

• Nehmen wir zum Beispiel das Redis-Cache-Plugin: Verschiedene APIs müssen möglicherweise unterschiedliche Cache-Zeiten festlegen. Wenn jeder API-Aufruf dasselbe Cache-Plugin verwendet, kann jeweils ein anderer Zeitwert übergeben werden.

• Oder nehmen wir das Feldverschlüsselungs-Plugin: Jede API hat unterschiedliche Felder, die verschlüsselt werden sollen. Wenn dieselbe Feldverschlüsselungsfunktion für verschiedene APIs genutzt wird, kann jeweils ein anderer Feldname übergeben werden. Auf diese Weise lässt sich ein einzelnes Plugin flexibel für mehrere APIs wiederverwenden.

• So rufen Sie den Wert eines lokalen Plugin-Parameters ab:

// Die lokalen Plugin-Parameter wurden bereits in die entsprechende Methode des Plugins übergeben; der Parametername lautet localPluginParam.
// Zum Beispiel bei der Alarm-Methode des Alarm-Plugins ist der letzte Parameter der lokale Plugin-Parameter.
    public void alarm(Exception e, ApiConfig config, HttpServletRequest request, String localPluginParam) {

    }

Protokollierung im Plugin

• Wenn Sie im Plugin Protokolleinträge ausgeben möchten, empfiehlt es sich, direkt die Logger-Methode der Elternklasse aufzurufen.

super.logger.debug("Daten in den Cache schreiben");

Beschreibung des Plugins

• Alle Plugins müssen die drei Methoden getName, getDescription und getParamDescription implementieren. Diese Methoden dienen dazu, den Nutzern auf der Benutzeroberfläche die Funktion des Plugins sowie das Format der lokalen Plugin-Parameter klar zu vermitteln.

Verwendung von Plugins

• Nachdem Sie ein Plugin entwickelt haben, packen Sie es in ein Archiv. Kopieren Sie die resultierende JAR-Datei sowie alle abhängigen JAR-Dateien in das Verzeichnis extlib oder lib von DBAPI (wir empfehlen jedoch die Verwendung des extlib-Verzeichnisses, da dies eine zentralisierte Verwaltung erleichtert). Starten Sie anschließend den DBAPI-Dienst neu (bei Clusterbetrieb muss auf jedem Knoten die JAR-Datei kopiert und der Cluster neu gestartet werden), um das Plugin nutzen zu können.
• Falls das Plugin globale Parameter verwendet, müssen Sie zusätzlich die entsprechenden Einstellungen in der Datei conf/plugin.properties vornehmen und den Dienst neu starten, damit die Änderungen wirksam werden (auch hier gilt: Bei Clusterbetrieb muss auf jedem Knoten die entsprechende Konfiguration vorgenommen und der Cluster neu gestartet werden).

Vollständiges Entwicklungsbeispiel für ein Plugin

Beispiel-Demo