설치 및 초기화

이 가이드는 NetFUNNEL Java 에이전트의 설치 및 초기화 과정을 설명합니다.

---

1단계: 라이브러리 설치

Gradle (Kotlin DSL)

build.gradle.kts에 다음 의존성을 추가합니다:

implementation(files("libs/netfunnel-agent.jar"))
implementation("com.google.code.gson:gson:2.9.1")
implementation("com.fasterxml.jackson.module:jackson-module-kotlin")

Gradle (Groovy DSL)

build.gradle에 다음 의존성을 추가합니다:

implementation files('libs/netfunnel-agent.jar')
implementation 'com.google.code.gson:gson:2.9.1'
// Java 사용시
implementation 'com.fasterxml.jackson.module:jackson-module-kotlin'

Maven

pom.xml에 다음 의존성을 추가합니다:

<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.9.1</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.module</groupId>
    <artifactId>jackson-module-kotlin</artifactId>
    <version>2.15.2</version>
</dependency>

netfunnel-agent.jar 파일은 libs 폴더에 추가하고 다음 설정을 추가합니다:

<dependency>
    <groupId>com.stclab</groupId>
    <artifactId>netfunnel-agent</artifactId>
    <version>4.0.1</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/libs/netfunnel-agent.jar</systemPath>
</dependency>

---

2단계: Client ID 및 Secret Key 가져오기

1. NetFUNNEL 콘솔로 이동
2. 우측 상단의 프로필 아이콘 클릭
3. 통합 자격 증명 (Integration Credentials) 메뉴 선택
4. Client ID 및 Secret Key 복사

Client ID 및 Secret Key 확인 위치

콘솔 화면 우측 상단의 프로필 아이콘을 클릭한 후, 통합 자격 증명 메뉴에서 확인할 수 있습니다.

---

3단계: Interceptor 또는 Filter 적용

프로젝트 구조에 맞게 Interceptor와 Filter 중 하나만 선택하여 적용합니다. 두 방식 모두 동일한 NetFUNNEL 대기열 제어 기능을 제공하므로 중복으로 구현할 필요는 없습니다.

Interceptor 적용 방법

1. Interceptor 생성

서버의 요청을 먼저 수신하는 Interceptor에 아래와 같은 코드를 작성합니다:

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

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

@Component
public class NetFunnelInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        NetFunnelInitialize config = NetFunnelInitialize.Companion.builder()
            .clientId("{{CLIENT_ID}}")  // 2단계에서 가져온 Client ID
            .secretKey("{{SECRET_KEY}}")  // 2단계에서 가져온 Secret Key
            .build();
        Netfunnel netfunnel = new Netfunnel(config, new NetFunnelServletService(request, response), null, null);
        return netfunnel.run();
    }
}

2. Interceptor 등록

생성한 interceptor를 WebMvcConfigurer의 addInterceptors 메서드를 override해서 등록합니다:

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 NetFunnelInterceptor netFunnelInterceptor;
    
    @Autowired
    public WebConfig(NetFunnelInterceptor netFunnelInterceptor) {
        this.netFunnelInterceptor = netFunnelInterceptor;
    }
    
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(netFunnelInterceptor)
                .addPathPatterns("/**");
    }
}

Filter 적용 방법

1. Filter 생성

서버의 요청을 먼저 수신하는 Filter에 아래와 같은 코드를 작성합니다:

import com.stclab.Netfunnel;
import com.stclab.servlet.NetFunnelServletService;
import com.stclab.utils.NetFunnelInitialize;

import javax.servlet.*;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

public class NetFunnelFilter 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}}")  // 2단계에서 가져온 Client ID
            .secretKey("{{SECRET_KEY}}")  // 2단계에서 가져온 Secret Key
            .build();
        Netfunnel netfunnel = new Netfunnel(config, new NetFunnelServletService(request, response), null, null);
        if (!netfunnel.run()) {
            return;
        }
        chain.doFilter(servletRequest, servletResponse);
    }
}

2. Filter 등록

생성한 Filter를 빈에 등록합니다:

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

import javax.servlet.Filter;

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

---

4단계: 초기화 설정

초기화 설정에 대한 자세한 정보는 초기화 설정 문서를 참조하세요.

기본 초기화 예제

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

---

5단계: 설치 확인

에이전트가 올바르게 설치되었는지 확인하려면 다음을 확인하세요:

1. 의존성 확인: netfunnel-agent.jar, gson, jackson-module-kotlin이 올바르게 추가되었는지 확인
2. 초기화 성공: 서버 시작 시 에러가 발생하지 않아야 합니다
3. Interceptor/Filter 적용: 요청이 올바르게 처리되는지 확인

---

문제 해결

라이브러리 설치 실패:

• netfunnel-agent.jar 파일이 libs 폴더에 있는지 확인
• Gradle/Maven 의존성이 올바르게 추가되었는지 확인

초기화 실패:

• clientId와 secretKey가 올바르게 설정되었는지 확인
• 빈 문자열이 아닌지 확인

Interceptor/Filter가 동작하지 않음:

• Interceptor/Filter가 올바르게 등록되었는지 확인
• addPathPatterns가 올바르게 설정되었는지 확인

---

다음 단계

• 빠른 시작: 기본 예제로 시작하기
• 통합 방법: URL-Triggered 통합 개요
• API 참조: 완전한 함수 사양