플러그인

플러그인 마켓

• DBAPI 공식에서는 이미 일부 자주 사용되는 플러그인을 제공하고 있으며, 플러그인 마켓에서 다운로드하실 수 있습니다.

플러그인의 역할

• DBAPI의 플러그인은 데이터 변환 플러그인, 캐시 플러그인, 알림 플러그인, 전역 데이터 변환 플러그인, 파라미터 처리 플러그인 등 5가지 범주로 나뉩니다.
• 모든 플러그인은 JAR 파일 형태이며, 해당 JAR 파일을 DBAPI의 extlib 디렉토리 또는 lib 디렉토리에 배치한 뒤 DBAPI를 재시작하면 바로 사용 가능합니다.

캐시 플러그인

• 실행기 결과를 캐시하여, 예를 들어 SQL 실행기의 경우 조회형 SQL의 쿼리 결과를 캐시함으로써 데이터베이스에 대한 잦은 접근을 줄이고 부하를 완화합니다.
• 캐시 로직은 사용자가 직접 작성하며, Redis, MongoDB, Elasticsearch 등 다양한 저장소에 결과를 저장할 수 있습니다.
• 캐시에서 데이터를 찾지 못할 경우에만 실행기를 호출하고, 그 결과를 다시 캐시에 저장합니다.

SQL 실행기의 다중 SQL 시나리오

SQL 실행기에서 하나의 실행기에 여러 개의 SQL이 포함되어 있을 경우, 각 SQL마다 별도의 캐시 플러그인을 설정해야 합니다. 단일 SQL에 변환 플러그인이 적용된 경우, 먼저 변환된 결과를 캐시합니다.

알림 플러그인

• API 내부에서 오류가 발생했을 때, 이 알림 플러그인을 통해 이메일이나 문자 메시지 등으로 오류 정보를 알릴 수 있습니다.
• 알림 로직은 사용자가 직접 작성합니다.

데이터 변환 플러그인

• 때로는 SQL로 원하는 형식의 데이터를 한 번에 얻기 어려울 수 있습니다. 이때 코드를 이용해 데이터를 처리하거나 변환하면 더욱 편리하게 작업할 수 있습니다. 이러한 경우 데이터 변환 플러그인을 활용합니다.
• 예를 들어, SQL 쿼리 결과에 포함된 사용자의 휴대폰 번호나 은행 계좌번호를 변환하여 개인정보를 보호할 수 있습니다.

SQL 실행기의 다중 SQL 시나리오

SQL 실행기에서 하나의 실행기에 여러 개의 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){

    }

    /**
     * 모든 캐시를 삭제하는 메서드.
     *
     * @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 구성, 두 번째 매개변수는 요청 파라미터입니다.

• set 메서드는 캐시를 설정하는 메서드로, 실행기가 실행된 후 호출됩니다. 첫 번째 매개변수는 API 구성, 두 번째 매개변수는 요청 파라미터, 세 번째 매개변수는 실행 결과입니다. 데이터 변환 플러그인이 설정된 경우, 변환된 결과를 전달합니다.

• 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>로 강제 형변환할 수 있습니다.

• 두 번째 매개변수는 플러그인의 로컬 파라미터입니다.

전역 데이터 변환 플러그인 개발

• 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가 반환한 결과 데이터이며, 두 번째 매개변수는 플러그인의 로컬 파라미터입니다.

알림 플러그인 개발

• 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. 같은 디렉터리에 com.gitee.freakchicken.dbapi.plugin.TransformPlugin 파일을 생성하고, 데이터 변환 플러그인의 Java 클래스 이름을 기재합니다.
4. 또 다른 com.gitee.freakchicken.dbapi.plugin.GlobalTransformPlugin 파일을 생성하여 글로벌 데이터 변환 플러그인의 Java 클래스 이름을 기재합니다.
5. com.gitee.freakchicken.dbapi.plugin.AlarmPlugin 파일을 생성하여 알림 플러그인의 Java 클래스 이름을 기재합니다.
6. 마지막으로 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마다 암호화 대상 필드가 다르므로, 각 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 세 가지 메서드를 반드시 구현해야 합니다.
• 이들 메서드는 페이지 상에서 플러그인의 역할과 로컬 파라미터 형식을 사용자에게 명확히 안내하기 위한 것입니다.

플러그인 사용법

• 사용자는 플러그인 개발을 완료한 후, 최종적으로 생성된 JAR 파일과 플러그인 의존 JAR 파일들을 DBAPI의 extlib 또는 lib 디렉터리에 복사합니다(통합 관리를 위해 extlib 디렉터리에 배치하는 것을 권장합니다). 이후 DBAPI 서비스를 재시작하면(클러스터 모드인 경우 각 노드마다 JAR 파일을 복사하고 클러스터를 재시작해야 함), 플러그인을 사용할 수 있게 됩니다.
• 플러그인에 글로벌 파라미터가 사용된 경우, conf/plugin.properties 파일에 해당 설정을 추가하고 재시작하여 적용해야 합니다(클러스터 모드인 경우 각 노드마다 설정을 추가하고 재시작해야 합니다).

플러그인 개발 완전 사례

사례 데모