Java 통합 가이드

NetFUNNEL Java 에이전트는 Java Spring Boot 서버에서 NetFUNNEL 서버와 통신하는 전용 클라이언트입니다.

1. 최소 요구 사항

• Spring Boot 3.x 이상
• 외부 라이브러리: gson, jackson-module-kotlin, logback-classic

2. 에이전트 동작 흐름

대기열 제어 지점은 NetFUNNEL 콘솔의 세그먼트 트리거 규칙을 통해 설정할 수 있습니다. 사용자가 접속한 페이지의 URL과 트리거 규칙을 비교하여 일치하는 경우 대기열이 적용됩니다.

• 대기 전: 페이지 요청 → 에이전트 초기화 → 트리거 규칙 매치
• 대기 중: 넷퍼넬 서버 요청 → 넷퍼넬 키 발급 → 대기실 페이지로 이동
• 대기 후: 서비스 페이지 진입 → 넷퍼넬 키 반납

3. 에이전트 설치

3.1 에이전트 추가

NetFUNNEL 콘솔의 에이전트 탭에서 Java 에이전트(netfunnel-agent.jar)를 다운로드하여 프로젝트의 libs 디렉터리에 복사합니다.

프로젝트 루트/
├── libs/
│   └── netfunnel-agent.jar
├── src/
└── build.gradle

3.2 의존성 추가

build.gradle에 에이전트와 외부 라이브러리 의존성을 추가합니다.

Kotlin DSL (build.gradle.kts)

build.gradle.kts

dependencies {
    // NetFUNNEL Java 에이전트
    implementation(files("libs/netfunnel-agent.jar"))

    // 외부 라이브러리
    implementation("com.google.code.gson:gson:2.9.1")
    implementation("com.fasterxml.jackson.module:jackson-module-kotlin")
}

Groovy DSL (build.gradle)

build.gradle

dependencies {
    // NetFUNNEL Java 에이전트
    implementation files('libs/netfunnel-agent.jar')

    // 외부 라이브러리
    implementation 'com.google.code.gson:gson:2.9.1'
    implementation 'com.fasterxml.jackson.module:jackson-module-kotlin'
}

참고

에이전트는 Kotlin으로 작성되어 있어 Java 프로젝트에서도 jackson-module-kotlin이 필요합니다. 로그 레벨 설정(logLevel)에는 logback-classic이 사용되며, Spring Boot 기본 로깅(spring-boot-starter-logging)에 포함되어 있습니다.

4. 에이전트 적용

서버의 요청을 먼저 수신하는 Interceptor 또는 Filter에 NetFUNNEL 에이전트를 적용합니다. 두 방식 모두 같은 대기열 제어를 제공합니다.

주의

Interceptor와 Filter를 함께 적용하면 하나의 요청에 대기열이 중복으로 적용될 수 있습니다. 둘 중 한 가지 방식만 사용하세요.

netfunnel.run()의 결과가 true이면 요청을 계속 처리하고, false이면 에이전트가 사용자를 대기실로 이동시키므로 요청 처리를 중단합니다.

4.1 Interceptor

Spring MVC의 HandlerInterceptor를 구현하고, preHandle()에서 NetFUNNEL 에이전트를 실행합니다.

DemoInterceptor.java

import com.stclab.Netfunnel;
import com.stclab.servlet.NetFunnelServletService;
import com.stclab.utils.NetFunnelInitialize;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;

@Component
public class DemoInterceptor implements HandlerInterceptor {

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        NetFunnelInitialize config = NetFunnelInitialize.Companion.builder()
                .clientId("{CLIENT_ID}")
                .secretKey("{SECRET_KEY}")
                .build();

        Netfunnel netfunnel = new Netfunnel(config, new NetFunnelServletService(request, response), null, null);

        // true: 요청 계속 처리 / false: 대기실로 이동하므로 요청 중단
        return netfunnel.run();
    }
}

작성한 Interceptor를 WebMvcConfigurer에 등록하여 모든 요청에 대기열 제어를 적용합니다.

WebConfig.java

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebConfig implements WebMvcConfigurer {

    private final DemoInterceptor demoInterceptor;

    @Autowired
    public WebConfig(DemoInterceptor demoInterceptor) {
        this.demoInterceptor = demoInterceptor;
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(demoInterceptor)
                .addPathPatterns("/**");
    }
}

4.2 Filter

Servlet Filter를 구현하고, doFilter()에서 NetFUNNEL 에이전트를 실행합니다. run()의 결과가 true일 때만 다음 필터로 요청을 전달합니다.

DemoFilter.java

import com.stclab.Netfunnel;
import com.stclab.servlet.NetFunnelServletService;
import com.stclab.utils.NetFunnelInitialize;
import jakarta.servlet.Filter;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.ServletRequest;
import jakarta.servlet.ServletResponse;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;

public class DemoFilter implements Filter {

    @Override
    public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain chain)
            throws IOException, ServletException {
        HttpServletRequest request = (HttpServletRequest) servletRequest;
        HttpServletResponse response = (HttpServletResponse) servletResponse;

        NetFunnelInitialize config = NetFunnelInitialize.Companion.builder()
                .clientId("{CLIENT_ID}")
                .secretKey("{SECRET_KEY}")
                .build();

        Netfunnel netfunnel = new Netfunnel(config, new NetFunnelServletService(request, response), null, null);

        // false: 대기실로 이동하므로 요청 중단
        if (!netfunnel.run()) {
            return;
        }
        chain.doFilter(servletRequest, servletResponse);
    }
}

작성한 Filter를 FilterRegistrationBean으로 등록하여 모든 요청에 대기열 제어를 적용합니다.

FilterConfig.java

import jakarta.servlet.Filter;
import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class FilterConfig {

    @Bean
    public FilterRegistrationBean<Filter> filterRegistrationBean() {
        FilterRegistrationBean<Filter> registration = new FilterRegistrationBean<>();
        registration.setFilter(new DemoFilter());
        registration.addUrlPatterns("/*");
        registration.setOrder(1);
        return registration;
    }
}

5. Initialize 설정

NetFunnelInitialize.Companion.builder()에 아래 설정값을 추가합니다.

필드	타입	기본값	필수	설명	에이전트 버전
clientId	String	N/A	O	콘솔에서 발급받은 클라이언트 아이디를 입력합니다.	4.0.1 이상
secretKey	String	N/A	O	콘솔에서 발급받은 암호화 키를 입력합니다.	4.0.1 이상
serverUrl	String	N/A	X	NetFUNNEL 서버의 URL입니다. CNAME을 사용하지 않고, clientId 기반의 URL 조합이 아닌 별도의 URL로 서버에 접근할 때 사용합니다. (기존 방식과의 호환성을 위해 지원됩니다.)	4.0.1 이상
settingUrl	String	N/A	X	NetFUNNEL 환경설정 파일의 URL입니다. 별도의 URL로 설정 파일을 불러올 때 사용합니다. (기존 방식과의 호환성을 위해 지원됩니다.)	4.0.1 이상
vwrPageUrl	String	N/A	X	NetFUNNEL VWR Page의 URL입니다. 별도의 URL로 대기실 페이지에 진입해야 할 때 지정합니다.	4.0.1 이상
returnKey	boolean	true	X	사용자가 대기열을 통과해 페이지에 진입하면 즉시 다음 사용자가 입장할 수 있습니다. 비활성화하면 진입 후에도 일정 시간 다음 사용자가 대기합니다. (타임아웃은 콘솔의 세그먼트 설정 > 고급설정에서 가능합니다.)	4.0.1 이상
logLevel	Level	Level.OFF	X	로그 레벨을 설정합니다. ch.qos.logback.classic.Level의 ERROR, WARN, INFO, DEBUG, TRACE, OFF 중 선택합니다.	4.0.1 이상
goodBots	String[]	N/A	X	선의의 봇(검색엔진 등)을 진입 요청에서 제외합니다. 예시: ["Googlebot", "Bingbot"]	4.0.1 이상
userId	String	N/A	X	화이트리스트·영구 차단 사용자 구분에 사용할 ID입니다. 콘솔의 반복 요청 차단 > 사용자 설정 > 접속자 관리에서 설정한 ID가 적용됩니다.	4.0.1 이상
vwrPageDomain	String	N/A	X	CNAME 도메인만으로 VWR Page URL을 구성할 때 사용합니다. 예시: https://vwr.example.com	4.0.1 이상
cookieDomain	String	N/A	X	발급되는 NetFUNNEL 쿠키의 도메인 값을 직접 지정합니다.	4.0.1 이상

설정 예시

import ch.qos.logback.classic.Level;

NetFunnelInitialize config = NetFunnelInitialize.Companion.builder()
        .clientId("{CLIENT_ID}")
        .secretKey("{SECRET_KEY}")
        .returnKey(true)
        .logLevel(Level.INFO)
        .goodBots(new String[] { "Googlebot", "Bingbot" })
        .build();

6. 트리거 규칙 설정

대기열 제어 지점은 NetFUNNEL 콘솔의 세그먼트 트리거 규칙을 통해 설정할 수 있습니다. 사용자가 접속한 페이지의 URL과 트리거 규칙을 비교하여 일치하는 경우 대기열이 적용됩니다.

트리거 규칙 설정 방법은 트리거 규칙 문서를 참고하세요.