Skip to content

커스텀 플러그인 - Base API ​

Ktor는 여러 애플리케이션에서 재사용 가능한 기능을 구현하는 커스텀 플러그인을 개발할 수 있도록 Base API를 제공합니다.

Base API를 사용하면 다양한 파이프라인 단계를 가로채(intercept) 요청 및 응답 처리에 커스텀 로직을 추가할 수 있습니다. 예를 들어, Monitoring 단계를 가로채 들어오는 요청을 로깅하거나 메트릭을 수집할 수 있습니다.

플러그인 생성 ​

Base API로 커스텀 플러그인을 생성하려면:

  1. 플러그인 클래스를 생성하고 플러그인 인터페이스를 구현하는 컴패니언 객체(companion object)를 선언합니다.
  2. 컴패니언 객체에서 key 프로퍼티와 install() 함수를 구현합니다.
  3. 플러그인 구성(configuration)을 제공합니다.
  4. 필요한 파이프라인 단계를 가로채 호출을 처리합니다.
  5. 플러그인을 설치합니다.

컴패니언 객체 생성 ​

커스텀 플러그인의 클래스에는 다음 인터페이스 중 하나를 구현하는 컴패니언 객체가 있어야 합니다:

BaseApplicationPlugin 인터페이스는 다음 타입 매개변수를 받습니다:

  • 플러그인이 지원하는 파이프라인 타입.
  • 플러그인의 구성 타입.
  • 플러그인 인스턴스 타입.
kotlin
class CustomHeader() {
    companion object Plugin : BaseApplicationPlugin<ApplicationCallPipeline, Configuration, CustomHeader> {
        // ...
    }
}

'key' 프로퍼티 및 'install()' 함수 구현 ​

BaseApplicationPlugin을 구현하는 컴패니언 객체는 다음을 정의해야 합니다:

  • key 프로퍼티는 플러그인을 식별합니다. Ktor는 플러그인 인스턴스를 애플리케이션의 속성(attribute)에 저장하고 이 키를 사용하여 플러그인 인스턴스에 접근합니다.
  • install() 함수는 플러그인을 구성합니다. 이 함수에서 필요한 파이프라인 단계를 가로채고 플러그인 인스턴스를 반환합니다. 파이프라인 단계를 가로채는 방법은 호출 처리 섹션에 설명되어 있습니다.
kotlin
class CustomHeader() {
    companion object Plugin : BaseApplicationPlugin<ApplicationCallPipeline, Configuration, CustomHeader> {
        override val key = AttributeKey<CustomHeader>("CustomHeader")
        override fun install(pipeline: ApplicationCallPipeline, configure: Configuration.() -> Unit): CustomHeader {
            val plugin = CustomHeader()
            // Intercept a pipeline ...
            return plugin
        }
    }
}

호출 처리 ​

커스텀 플러그인에서는 기존 파이프라인 단계나 새로 정의된 단계를 가로채 요청과 응답을 처리할 수 있습니다. 예를 들어, Authentication(인증) 플러그인은 기본 파이프라인에 Authenticate 및 Challenge 커스텀 단계를 추가합니다.

특정 단계를 가로채면 호출 처리의 특정 단계에 접근할 수 있습니다:

  • ApplicationCallPipeline.Monitoring: 요청 로깅, 메트릭, 트레이싱 및 유사한 모니터링 작업에 이 단계를 사용합니다.
  • ApplicationCallPipeline.Plugins: 호출을 처리하거나 커스텀 헤더 추가와 같은 응답 파라미터를 수정하는 데 이 단계를 사용합니다.
  • ApplicationReceivePipeline.Transform 및 ApplicationSendPipeline.Transform: 클라이언트로부터 수신하거나 클라이언트로 전송하는 데이터에 접근하고 변환(transform)하는 데 이 단계를 사용합니다.

다음 예제는 ApplicationCallPipeline.Plugins 단계를 가로채 각 응답에 커스텀 헤더를 추가합니다:

kotlin
class CustomHeader() {
    companion object Plugin : BaseApplicationPlugin<ApplicationCallPipeline, Configuration, CustomHeader> {
        override val key = AttributeKey<CustomHeader>("CustomHeader")
        override fun install(pipeline: ApplicationCallPipeline, configure: Configuration.() -> Unit): CustomHeader {
            val plugin = CustomHeader()
            pipeline.intercept(ApplicationCallPipeline.Plugins) {
                call.response.header("X-Custom-Header", "Hello, world!")
            }
            return plugin
        }
    }
}

이 예제에서는 헤더 이름과 값이 하드코딩되어 있습니다. 플러그인을 재사용할 수 있도록 하려면 사용자가 헤더 이름과 값을 지정할 수 있는 구성(configuration)을 제공하세요.

커스텀 플러그인은 서로 다른 핸들러 간에 호출과 연관된 값을 공유할 수 있습니다. 자세한 내용은 호출 상태 공유를 참조하세요.

플러그인 구성 제공 ​

이전 섹션에서는 각 응답에 사전 정의된 커스텀 헤더를 추가하는 플러그인을 생성하는 방법을 살펴보았습니다. 이 플러그인을 재사용 가능하게 만들려면 사용자가 헤더 이름과 값을 지정할 수 있는 구성을 정의하세요.

먼저, 플러그인 클래스 내부에 구성 클래스를 정의합니다:

kotlin
class Configuration {
    var headerName = "Custom-Header-Name"
    var headerValue = "Default value"
}

플러그인 설치 중에 플러그인 구성 프로퍼티를 업데이트할 수 있습니다. 플러그인이 인터셉터에서 이러한 값을 사용하는 경우, install() 함수 내부의 로컬 변수에 저장합니다:

kotlin
class CustomHeader(configuration: Configuration) {
    private val name = configuration.headerName
    private val value = configuration.headerValue

    class Configuration {
        var headerName = "Custom-Header-Name"
        var headerValue = "Default value"
    }
}

그런 다음 install() 함수에서 구성을 읽고 해당 프로퍼티를 사용합니다:

kotlin
class CustomHeader(configuration: Configuration) {
    private val name = configuration.headerName
    private val value = configuration.headerValue

    class Configuration {
        var headerName = "Custom-Header-Name"
        var headerValue = "Default value"
    }

    companion object Plugin : BaseApplicationPlugin<ApplicationCallPipeline, Configuration, CustomHeader> {
        override val key = AttributeKey<CustomHeader>("CustomHeader")
        override fun install(pipeline: ApplicationCallPipeline, configure: Configuration.() -> Unit): CustomHeader {
            val configuration = Configuration().apply(configure)
            val plugin = CustomHeader(configuration)
            pipeline.intercept(ApplicationCallPipeline.Plugins) {
                call.response.header(plugin.name, plugin.value)
            }
            return plugin
        }
    }
}

플러그인 설치 ​

애플리케이션에 커스텀 플러그인을 설치하려면 Application.install() 함수를 호출하고 필요한 구성 파라미터를 전달합니다:

kotlin
install(CustomHeader) {
    headerName = "X-Custom-Header"
    headerValue = "Hello, world!"
}

예제 ​

다음 예제는 Base API로 빌드된 여러 커스텀 플러그인을 보여줍니다.

실행 가능한 전체 프로젝트는 custom-plugin-base-api를 참조하세요.

요청 로깅 ​

다음 예제는 들어오는 요청을 로깅하는 커스텀 플러그인을 생성합니다:

kotlin
package com.example.plugins

import io.ktor.serialization.*
import io.ktor.server.application.*
import io.ktor.server.plugins.*
import io.ktor.util.*

class RequestLogging {
    companion object Plugin : BaseApplicationPlugin<ApplicationCallPipeline, Configuration, RequestLogging> {
        override val key = AttributeKey<RequestLogging>("RequestLogging")
        override fun install(pipeline: ApplicationCallPipeline, configure: Configuration.() -> Unit): RequestLogging {
            val plugin = RequestLogging()
            pipeline.intercept(ApplicationCallPipeline.Monitoring) {
                call.request.origin.apply {
                    println("Request URL: $scheme://$localHost:$localPort$uri")
                }
            }
            return plugin
        }
    }
}

커스텀 헤더 ​

다음 예제는 각 응답에 커스텀 헤더를 추가하는 플러그인을 생성합니다:

kotlin
package com.example.plugins

import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.util.*

class CustomHeader(configuration: Configuration) {
    private val name = configuration.headerName
    private val value = configuration.headerValue

    class Configuration {
        var headerName = "Custom-Header-Name"
        var headerValue = "Default value"
    }

    companion object Plugin : BaseApplicationPlugin<ApplicationCallPipeline, Configuration, CustomHeader> {
        override val key = AttributeKey<CustomHeader>("CustomHeader")
        override fun install(pipeline: ApplicationCallPipeline, configure: Configuration.() -> Unit): CustomHeader {
            val configuration = Configuration().apply(configure)
            val plugin = CustomHeader(configuration)
            pipeline.intercept(ApplicationCallPipeline.Plugins) {
                call.response.header(plugin.name, plugin.value)
            }
            return plugin
        }
    }
}

본문 변환 ​

다음 예제는 요청 및 응답 본문을 변환하는 플러그인을 생성합니다:

kotlin
package com.example.plugins

import io.ktor.serialization.*
import io.ktor.server.application.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.util.*
import io.ktor.utils.io.*

class DataTransformation {
    companion object Plugin : BaseApplicationPlugin<ApplicationCallPipeline, Configuration, DataTransformation> {
        override val key = AttributeKey<DataTransformation>("DataTransformation")
        override fun install(pipeline: ApplicationCallPipeline, configure: Configuration.() -> Unit): DataTransformation {
            val plugin = DataTransformation()
            pipeline.receivePipeline.intercept(ApplicationReceivePipeline.Transform) { data ->
                val newValue = (data as ByteReadChannel).readLine()?.toInt()?.plus(1)
                if (newValue != null) {
                    proceedWith(newValue)
                }
            }
            pipeline.sendPipeline.intercept(ApplicationSendPipeline.Transform) { data ->
                if (subject is Int) {
                    val newValue = data.toString().toInt() + 1
                    proceedWith(newValue.toString())
                }
            }
            return plugin
        }
    }
}

파이프라인 ​

Ktor에서 Pipeline은 하나 이상의 순서가 지정된 단계(phase)로 그룹화된 인터셉터(interceptor) 컬렉션입니다. 각 인터셉터는 요청 처리가 계속 진행되기 전후에 커스텀 로직을 실행할 수 있습니다.

ApplicationCallPipeline은 애플리케이션 호출을 실행합니다. 이 파이프라인은 다음과 같은 단계를 정의합니다:

  • Setup: 처리를 위해 호출 및 관련 속성(attribute)을 준비합니다.
  • Monitoring: 호출을 추적합니다. 요청 로깅, 메트릭, 오류 처리 및 유사한 작업에 이 단계를 사용합니다.
  • Plugins: 호출을 처리합니다. 대부분의 플러그인이 이 단계를 가로챕니다.
  • Call: 호출을 완료합니다.
  • Fallback: 이전 단계에서 처리되지 않은 호출을 처리합니다.

파이프라인 단계와 새 API 핸들러 매핑 ​

간소화된 커스텀 플러그인 API를 사용하여 커스텀 플러그인을 만들 수 있습니다. 대부분의 경우 이 API는 파이프라인 및 단계와 같은 내부 Ktor 개념을 직접 알 필요가 없습니다. 대신 요청 및 응답 처리의 다양한 단계에 대해 onCall(), onCallReceive(), onCallRespond()와 같은 핸들러를 제공합니다.

다음 표는 Base API 파이프라인 단계가 간소화된 API 핸들러에 어떻게 매핑되는지 보여줍니다:

Base APINew API
before ApplicationCallPipeline.Setupon(CallFailed)
ApplicationCallPipeline.Setupon(CallSetup)
ApplicationCallPipeline.PluginsonCall()
ApplicationCallPipeline.CallonCallValidators()
ApplicationReceivePipeline.TransformonCallReceive()
ApplicationSendPipeline.TransformonCallRespond()
ApplicationSendPipeline.Afteron(ResponseBodyReadyForSend)
ApplicationSendPipeline.Engineon(ResponseSent)
after Authentication.ChallengePhaseon(AuthenticationChecked)