プラグイン

プラグインマーケット

• DBAPI 公式では、よく使用されるいくつかのプラグインを提供しています。プラグインマーケットからダウンロードできます。

プラグインの役割

• DBAPI のプラグインは5種類に分類されます。データ変換プラグイン、キャッシュプラグイン、アラートプラグイン、グローバルデータ変換プラグイン、パラメータ処理プラグインです。
• プラグインはすべて JAR パッケージであり、DBAPI の extlib ディレクトリまたは lib ディレクトリに配置し、DBAPI を再起動することで利用できます。

キャッシュプラグイン

• 実行結果をキャッシュします。たとえば SQL 実行器では、クエリ系の SQL に対してクエリ結果をキャッシュし、頻繁なデータベースアクセスによる負荷を軽減します。
• キャッシュのロジックはユーザーが自ら実装します。Redis、MongoDB、Elasticsearch などにキャッシュすることも可能です。
• キャッシュからデータが取得できない場合にのみ、実行器を実行し、その結果を再度キャッシュします。

SQL 実行器における複数 SQL のシナリオ

SQL 実行器で1つの実行器内に複数の SQL が含まれる場合、各 SQL の実行結果（個別の SQL に変換プラグインが設定されている場合は、まず変換された結果を処理）をひとまとめにして、全体としてキャッシュします。

アラートプラグイン

• API 内でエラーが発生した際に、メールや SMS などで通知する機能を提供します。
• アラートのロジックはユーザーが自ら実装します。

データ変換プラグイン

• SQL だけでは望む形式のデータを得られない場合があります。そのような場合には、コードでデータを加工・変換することでより便利になります。このため、データ変換プラグインを使用します。
• たとえば、SQL のクエリ結果に含まれる携帯電話番号や銀行口座番号を変換して機密情報を保護するといった用途に適しています。

SQL 実行器における複数 SQL のシナリオ

SQL 実行器で1つの実行器内に複数の SQL が含まれる場合、各 SQL に対して個別のデータ変換プラグインが設定されます。データ変換プラグインは常に個々の SQL のクエリ結果を対象に変換を行います。

グローバルデータ変換プラグイン

• API が返すデータ形式はデフォルトで {success:true,msg:xxx,data:xxx} です。
• 場合によっては、レスポンスデータの形式を変更する必要があることがあります。たとえば、フロントエンドの低コードフレームワーク「AMIS」では、インターフェースが必ず status フィールドを含む形式でデータを返すことが求められます。このような場合、「グローバルデータ変換プラグイン」を使用して、API 全体の返却データの形式を変換できます。

データ変換プラグインとグローバルデータ変換プラグインの違い

データ変換プラグインは、実行器の実行結果（例：SQL 実行器でクエリを実行した結果）の形式を変換するものであるのに対し、グローバルデータ変換プラグインは、API 全体の実行結果の形式を変換するものです。

パラメータ処理プラグイン

• リクエストパラメータをユーザー独自のロジックで処理します。
• たとえば、リクエストパラメータの値をすべて大文字に変換する、暗号化されたパラメータを受け取る際にはユーザーが定義したロジックで復号する、ページングクエリの際に offset パラメータを追加してその値を (pageNo-1) * pageSize にするといった処理が可能です。

バージョンサポートについて

パラメータ処理プラグインは、個人版では 4.0.16、企業版では 4.1.10 以降でサポートされています。

プラグインの開発手順

準備作業

• プラグインは Java 言語で開発します。Java (8+) の開発環境を準備し、Maven プロジェクトを作成して、pom.xml に dbapi-plugin を導入します。

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

プラグインの開発

キャッシュプラグインの開発

• 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 設定、2つ目の引数はリクエストパラメータです。

• set メソッドはキャッシュを設定するためのメソッドで、実行器が実行された後に呼び出されます。最初の引数は API 設定、2つ目の引数はリクエストパラメータ、3つ目の引数は実行結果です。データ変換プラグインが設定されている場合は、変換後の結果となります。

• clean メソッドはキャッシュをクリアするためのメソッドで、API の修正・オフライン・削除の際に実行されます。

データ変換プラグインの開発

• 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 実行器であれば SQL の実行結果となり、List<JSONObject> のデータ型になります。data を強制的に List<JSONObject> に変換できます。

• 2つ目の引数はプラグインのローカルパラメータです。

グローバルデータ変換プラグインの開発

• 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 が返す結果で、2つ目の引数はプラグインのローカルパラメータです。

アラートプラグインの開発

• 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 を実装します。

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 のプラグインは Java の SPI 機制を利用して登録されます。以下の手順を行います。

1. resources ディレクトリ内に META-INF フォルダーを作成し、さらにその中に services フォルダーを作成します。

2. META-INF/services フォルダー内に com.gitee.freakchicken.dbapi.plugin.CachePlugin というファイルを作成し、先ほど作成したキャッシュプラグインの Java クラス名を記載します。

3. 同様に、META-INF/services フォルダー内に com.gitee.freakchicken.dbapi.plugin.TransformPlugin というファイルを作成し、先ほど作成したデータ変換プラグインの Java クラス名を記載します。

4. META-INF/services フォルダー内に com.gitee.freakchicken.dbapi.plugin.GlobalTransformPlugin というファイルを作成し、先ほど作成したグローバルデータ変換プラグインの Java クラス名を記載します。

5. META-INF/services フォルダー内に com.gitee.freakchicken.dbapi.plugin.AlarmPlugin というファイルを作成し、先ほど作成したアラートプラグインの Java クラス名を記載します。

6. META-INF/services フォルダー内に com.gitee.freakchicken.dbapi.plugin.ParamProcessPlugin というファイルを作成し、先ほど作成したパラメータ処理プラグインの Java クラス名を記載します。

プラグインの説明

グローバルパラメータ

• グローバルパラメータを設計する目的は、同一プラグインを異なる環境で容易に利用できるようにすることです。
• グローバルパラメータは各プラグイン独自の設定であり、API とは無関係です。例えば、キャッシュプラグインが接続する Redis の IP アドレスやポート番号といった情報は、conf/plugin.properties ファイルに設定します。
• グローバルパラメータは主に環境切り替えを容易にするためのもので、たとえばテスト環境と本番環境で異なる Redis アドレスを使用する場合、設定ファイルにアドレス情報を記載しておくことで便利です。
• ユーザーがプラグインのグローバル設定を追加したい場合は、conf/plugin.properties ファイルに直接設定を追加できます。例：

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

• グローバルパラメータの値を取得する方法：

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

ローカルパラメータ

• ローカルパラメータを設計する目的は、同一プラグインを複数の API で柔軟に再利用できるようにすることです。

• ローカルパラメータは各 API ごとに個別に指定される設定で、ページ上で設定（API の作成・編集時）されます。

• 例えば、Redis キャッシュプラグインの場合、異なる API で異なるキャッシュ期間を設定したい場合、同じキャッシュプラグインを呼び出す際でも、それぞれ異なる時間パラメータを渡すことができます。

• 同様に、フィールド暗号化プラグインの場合、各 API で暗号化対象のフィールドが異なるため、同じフィールド暗号化プラグインを呼び出す際でも、それぞれ異なるフィールド名パラメータを渡すことができます。これにより、同一プラグインを複数の API で柔軟に再利用することが可能になります。

• ローカルパラメータの値を取得する方法：

// ローカルパラメータは対応するプラグインのメソッドにすでに渡されています。パラメータ名は localPluginParam です。
// 例えば、アラートプラグインの alarm メソッドでは、最後の引数がローカルプラグインパラメータとなります。
public void alarm(Exception e, ApiConfig config, HttpServletRequest request, String localPluginParam) {

    }

プラグインのログ出力

• プラグイン内でログを出力したい場合は、親クラスの logger を直接使用することを推奨します。

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

プラグインの説明文

• すべてのプラグインは getName、getDescription、getParamDescription の3つのメソッドを実装する必要があります。
• これらのメソッドは、ページ上でプラグインの役割やローカルパラメータの形式をユーザーに提示するために用いられます。

プラグインの使用

• ユーザーがプラグインを開発し終えたら、それをパッケージ化し、最終的に生成された JAR ファイルとプラグイン依存の JAR ファイルを DBAPI の extlib または lib ディレクトリにコピーします（統一管理のため、extlib ディレクトリへの配置を推奨します）。その後、DBAPI サービスを再起動してください（クラスター構成の場合は、各ノードで JAR ファイルをコピーし、クラスター全体を再起動する必要があります）。
• プラグインにグローバルパラメータが使用されている場合は、conf/plugin.properties ファイルに該当する設定を追加し、再起動して反映させます（クラスター構成の場合は、各ノードで同様の設定を追加し、再起動する必要があります）。

プラグイン開発の完全な事例

デモ事例