커스텀 플러그인 - Base API
코드 예제: custom-plugin-base-api
Ktor는 여러 애플리케이션에서 재사용 가능한 기능을 구현하는 커스텀 플러그인을 개발할 수 있도록 Base API를 제공합니다.
Base API를 사용하면 다양한 파이프라인 단계를 가로채(intercept) 요청 및 응답 처리에 커스텀 로직을 추가할 수 있습니다. 예를 들어, Monitoring 단계를 가로채 들어오는 요청을 로깅하거나 메트릭을 수집할 수 있습니다.
플러그인 생성
Base API로 커스텀 플러그인을 생성하려면:
- 플러그인 클래스를 생성하고 플러그인 인터페이스를 구현하는 컴패니언 객체(companion object)를 선언합니다.
- 컴패니언 객체에서
key프로퍼티와install()함수를 구현합니다. - 플러그인 구성(configuration)을 제공합니다.
- 필요한 파이프라인 단계를 가로채 호출을 처리합니다.
- 플러그인을 설치합니다.
컴패니언 객체 생성
커스텀 플러그인의 클래스에는 다음 인터페이스 중 하나를 구현하는 컴패니언 객체가 있어야 합니다:
- 애플리케이션 레벨 플러그인을 위한
BaseApplicationPlugin. - 특정 라우트에 설치되는 플러그인을 위한
BaseRouteScopedPlugin.
BaseApplicationPlugin 인터페이스는 다음 타입 매개변수를 받습니다:
- 플러그인이 지원하는 파이프라인 타입.
- 플러그인의 구성 타입.
- 플러그인 인스턴스 타입.
class CustomHeader() {
companion object Plugin : BaseApplicationPlugin<ApplicationCallPipeline, Configuration, CustomHeader> {
// ...
}
}'key' 프로퍼티 및 'install()' 함수 구현
BaseApplicationPlugin을 구현하는 컴패니언 객체는 다음을 정의해야 합니다:
key프로퍼티는 플러그인을 식별합니다. Ktor는 플러그인 인스턴스를 애플리케이션의 속성(attribute)에 저장하고 이 키를 사용하여 플러그인 인스턴스에 접근합니다.install()함수는 플러그인을 구성합니다. 이 함수에서 필요한 파이프라인 단계를 가로채고 플러그인 인스턴스를 반환합니다. 파이프라인 단계를 가로채는 방법은 호출 처리 섹션에 설명되어 있습니다.
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 단계를 가로채 각 응답에 커스텀 헤더를 추가합니다:
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)을 제공하세요.
커스텀 플러그인은 서로 다른 핸들러 간에 호출과 연관된 값을 공유할 수 있습니다. 자세한 내용은 호출 상태 공유를 참조하세요.
플러그인 구성 제공
이전 섹션에서는 각 응답에 사전 정의된 커스텀 헤더를 추가하는 플러그인을 생성하는 방법을 살펴보았습니다. 이 플러그인을 재사용 가능하게 만들려면 사용자가 헤더 이름과 값을 지정할 수 있는 구성을 정의하세요.
먼저, 플러그인 클래스 내부에 구성 클래스를 정의합니다:
class Configuration {
var headerName = "Custom-Header-Name"
var headerValue = "Default value"
}플러그인 설치 중에 플러그인 구성 프로퍼티를 업데이트할 수 있습니다. 플러그인이 인터셉터에서 이러한 값을 사용하는 경우, install() 함수 내부의 로컬 변수에 저장합니다:
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() 함수에서 구성을 읽고 해당 프로퍼티를 사용합니다:
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() 함수를 호출하고 필요한 구성 파라미터를 전달합니다:
install(CustomHeader) {
headerName = "X-Custom-Header"
headerValue = "Hello, world!"
}예제
다음 예제는 Base API로 빌드된 여러 커스텀 플러그인을 보여줍니다.
실행 가능한 전체 프로젝트는 custom-plugin-base-api를 참조하세요.
요청 로깅
다음 예제는 들어오는 요청을 로깅하는 커스텀 플러그인을 생성합니다:
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
}
}
}커스텀 헤더
다음 예제는 각 응답에 커스텀 헤더를 추가하는 플러그인을 생성합니다:
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
}
}
}본문 변환
다음 예제는 요청 및 응답 본문을 변환하는 플러그인을 생성합니다:
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 API | New API |
|---|---|
before ApplicationCallPipeline.Setup | on(CallFailed) |
ApplicationCallPipeline.Setup | on(CallSetup) |
ApplicationCallPipeline.Plugins | onCall() |
ApplicationCallPipeline.Call | onCallValidators() |
ApplicationReceivePipeline.Transform | onCallReceive() |
ApplicationSendPipeline.Transform | onCallRespond() |
ApplicationSendPipeline.After | on(ResponseBodyReadyForSend) |
ApplicationSendPipeline.Engine | on(ResponseSent) |
after Authentication.ChallengePhase | on(AuthenticationChecked) |
