Գնահատել նախագիծը
← Բոլոր հրապարակումները

Ծանոթանում ենք Ktor-ին Spring Boot-ի տեսանկյունից. Մաս 2

Շարունակում ենք ուսումնասիրել Ktor-ը Spring Boot-ը լավ իմացող ծրագրավորողի աչքերով։ Այս մասում քննարկվում են HTTP հարցումների և բացառությունների մշակումը, HTTP կլիենտները և թեստավորումը՝ ցույց տալով, թե ինչպես են Ktor-ի ներկառուցված հնարավորությունները պարզեցնում այս ոլորտներից յուրաքանչյուրը։

17 րոպե
Spring BootKotlinKtorKotlinServerSide

Այստեղ շարունակում ենք ուսումնասիրել Ktor-ը այն ծրագրավորողի տեսանկյունից, որն արդեն գիտի Spring Boot-ը։ Առաջին մասը դրեց հիմքերը՝ ընդգրկելով հավելվածի կարգավորումը (Application Setup), սերվերի շարժիչները (Server Engines), կոնֆիգուրացիան (Configuration) և Dependency Injection-ը։ Այս անգամ անցնում ենք Ktor-ով վեբ հավելվածներ կառուցելու ավելի առաջադեմ թեմաներին։ Այս մասում կանդրադառնամ HTTP հարցումների և բացառությունների մշակմանը (HTTP Request Handling & Exception Handling), HTTP կլիենտներին (HTTP Clients) և թեստավորմանը (Testing)՝ ցույց տալով, թե ինչպես են Ktor-ի ներկառուցված հնարավորությունները պարզեցնում այս ոլորտներից յուրաքանչյուրը։

HTTP հարցումների մշակում

Բացահայտված REST endpoint-ների միջոցով HTTP հարցումների մշակումը վեբ հավելվածի ամենահիմնարար խնդիրներից է։ Այդ իսկ պատճառով յուրաքանչյուր վեբ ֆրեյմվորք ունի հարցումների մշակման մեխանիզմներ՝ ինչպես այն դեպքում, երբ ամեն ինչ լավ է ընթանում, այնպես էլ սխալների ժամանակ։

Ինչպես մյուս ոլորտներում, Spring Boot-ը և Ktor-ը սրան մոտենում են տարբեր կերպ՝ համաձայն իրենց տարբեր փիլիսոփայությունների։ Այս գլխում կնայենք, թե ինչպես է յուրաքանչյուր ֆրեյմվորք թույլ տալիս սահմանել և կառուցվածքավորել երթուղիները, աշխատել հարցման պարամետրերի հետ և արձագանքել արտակարգ իրավիճակներին։

Երթուղիների սահմանում և կազմակերպում

Spring Boot

Spring Boot-ը հենվում է annotation-ների վրա հիմնված կոնտրոլերների վրա, որոնք կարելի է խմբավորել ըստ իրենց բացահայտած endpoint-ների։ Գործարկման ժամանակ ֆրեյմվորքն ինքնուրույն գտնում և գրանցում է այս կոնտրոլերները component scanning-ի շնորհիվ։

@RestController
@RequestMapping("/api/users")
class UserController(private val userService: UserService) {

    @GetMapping("/{id}")
    fun getUserById(@PathVariable id: Long): User = userService.getUserById(id)

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    fun createUser(@RequestBody user: User): User = userService.createUser(user)

    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    fun deleteUser(@PathVariable id: Long) = userService.deleteUser(id)
}

@RestController 
@RequestMapping("/api/orders") 
class OrderController(private val orderService: OrderService) {

    @GetMapping("/{id}")
    fun getOrderById(@PathVariable id: Long): User = orderService.getOrderByIt(id)
}

Ktor

Ktor-ի երթուղավորման համակարգը օգտագործում է Kotlin-ի հզոր DSL հնարավորությունները և առաջարկում է երթուղիները ներդնելու սահուն, հիերարխիկ եղանակ, որպեսզի դրանց կառուցվածքը բնականորեն արտացոլի URL ուղիները։ Ի տարբերություն annotation-ների վրա հիմնված ֆրեյմվորքների՝ Ktor-ը խրախուսում է մոդուլայնացումը extension ֆունկցիաներով, ուստի ծրագրավորողները կարող են առնչվող երթուղիները դնել առանձին ֆայլերում։

// Application.kt
fun Application.configureRouting() {
    routing {
        userRoutes()
        orderRoutes()
    }
}

// UserRoutes.kt
fun Route.userRoutes() {
    route("/api") {
        route("/users") {

            get("/{id}") {
                val id = call.parameters["id"]?.toLongOrNull() 
                        ?: return@get call.respondText("Invalid ID", status = BadRequest)

                val user = userService.getUserById(id)
                if (user != null) {
                     call.respond(user)
                } else {
                    call.respond(HttpStatusCode.NotFound)
                }
           }

            post {
                val user = call.receive<User>()
                val createdUser = userService.createUser(user)
                call.respond(HttpStatusCode.Created, createdUser)
            }

            delete("/{id}") {
                val id = call.parameters["id"]?.toLongOrNull() 
                    ?: return@delete call.respondText("Invalid ID", status = BadRequest)

                userService.deleteUser(id)
                call.respond(HttpStatusCode.NoContent)
            }
        }
    }
}

// OrderRoutes.kt
fun Route.orderRoutes() {
    route("/api/orders") {

        get("/{id}") {
            val id = call.parameters["id"]?.toLongOrNull() 
                    ?: return@get call.respondText("Invalid ID", status = BadRequest)

            val user = orderService.getOrderById(id)
            if (user != null) {
                call.respond(user)
            } else {
                call.respond(HttpStatusCode.NotFound)
            }
        }
    }
}

Application.configureRouting() ֆունկցիան կանչում է routing() մեթոդը, որը Ktor հավելվածում տեղադրում է Routing plugin-ը։ Լամբդայի մարմնի ներսում աշխատում են երկու extension ֆունկցիա, որոնք սահմանում են Users-ի և Orders-ի երթուղիները։

Երթուղու սահմանումը սկսվում է ուղուց, որը նշվում է DSL ֆունկցիայով, օրինակ՝ route(“/api/users”)։ Համապատասխան լամբդայի ներսում endpoint-ները հայտարարվում են HTTP մեթոդների անուններով ֆունկցիաներով (get, post, put և այլն)։

Մուտքային հարցումները մշակելու և պատասխաններ վերադարձնելու համար սովորաբար հենվում եք call հատկության վրա, որը RoutingCall-ի օրինակ է։ Դրա միջոցով կարող եք՝

  • Ստանալ path փոփոխականը, օր.՝ call.parameters[“id”]
  • Ստանալ հարցման պարամետրը, օր.՝ call.request.queryParameters[“name”]
  • Ստանալ հարցման բեռը (payload), օր.՝ call.receive()
  • Ետ ուղարկել պատասխան, օր.՝ call.respond(HttpStatusCode.NotFound)

Երթուղավորում տիպերի անվտանգությամբ

Spring Boot

Spring Boot-ի կոնտրոլերների վրա հիմնված մոդելը ձեզ տալիս է տիպերի անվտանգություն հարցման և պատասխանի մարմինների համար, բայց path փոփոխականներն ու հարցման պարամետրերը համապատասխանեցվում են տողերի միջոցով, որոնք լուծվում են գործարկման ժամանակ և հետևաբար տիպերով ապահովված չեն։

@GetMapping("/users/{id}") // not type safe
fun getUser(@PathVariable id: Long): User {
    return userService.getUser(id)
}

Ktor

Ktor-ը տիպերով ավելի անվտանգ տարբերակ է տալիս Resources հնարավորության միջոցով։ Այն երթուղավորումը տանում է տողերի վրա հիմնված ուղիների սահմանումներից այն կողմ՝ ձեր API-ի կառուցվածքը մոդելավորելով որպես դասերի հիերարխիա, որում յուրաքանչյուր երթուղի խիստ տիպավորված օբյեկտ է՝ ճիշտ տիպավորված պարամետրերով։

Արդյունքում երթուղու պարամետրերն ու ուղիները ստուգվում են կոմպիլյացիայի ժամանակ, ինչը բացառում է գործարկման ժամանակի տիպական սխալները, իսկ href() ֆունկցիան թույլ է տալիս URL-ներ գեներացնել տիպերի անվտանգությամբ։ Քանի որ երթուղիները մոդելավորվում են որպես դասեր, ոչ թե տողեր, ռեֆակտորինգն ավելի անվտանգ և հեշտ է դառնում։ Պարզապես սահմանում եք դասերի հիերարխիան, որը նկարագրում է ձեր API-ն, և օգտագործում եք այն երթուղավորման սահմանման մեջ։

// Define route structure as a class hierarchy
@Resource("/api/users")
class Users {

    @Resource("/{id}")
    class Id(val parent: Users, val id: Long) {

        @Resource("/orders")
        class Orders(val parent: Id)
    }

    @Resource("/search")
    class Search(val parent: Users, val sort: String? = "ASC")
}

// Use type-safe routing
routing {
    get<Users> {
        call.respond(userService.getAllUsers())
    }

    get<Users.Id> { route ->
        call.respond(userService.getUser(route.id))
    }

    get<Users.Id.Orders> { route ->
        call.respond(orderService.getOrdersForUser(route.parent.id))
    }

    get<Users.Search> { route ->
        call.respond(userService.searchUsers(route.sort))
    }
}

// Generate URLs type-safely
val usersUrl = application.href(Users()) // /api/users
val userUrl = application.href(Users.Id(Users(), 123)) // /api/users/123

Ktor-ում Resources-ը միացնելու համար ավելացրեք ստորև բերված կախվածությունը և տեղադրեք Resources plugin-ը.

dependencies {
    implementation("io.ktor:ktor-server-resources:$ktor_version")
}
fun Application.myAppModule() {
    install(Resources)
}

Բացառությունների մշակում

Spring Boot

Spring Boot-ը բացառությունները մշակելու մի քանի եղանակ է առաջարկում. գլոբալ մշակում @ControllerAdvice annotation-ով, ավելի նուրբ մշակում կոնտրոլերի մակարդակում @ExceptionHandler-ով, HandlerExceptionResolver-ի իրականացում, AbstractHandlerExceptionResolver-ի ընդլայնում կամ ErrorController ինտերֆեյսի օգտագործում։

Ահա @ControllerAdvice-ի վրա հիմնված գլոբալ մոտեցման օրինակ.

@RestControllerAdvice
class GlobalExceptionHandler {

    @ExceptionHandler(UserNotFoundException::class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    fun handleUserNotFound(e: UserNotFoundException): ErrorResponse {
        return ErrorResponse.from(e)
    }

    @ExceptionHandler(ValidationException::class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    fun handleValidation(e: ValidationException): ErrorResponse {
        return ErrorResponse.from(e)
    }

    @ExceptionHandler(Exception::class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    fun handleGeneric(e: Exception): ErrorResponse> {
        return ErrorResponse.from(e)
    }
}

Ktor

Ktor-ը ունի մեխանիզմ՝ հավելվածի ներսում նետված բացառությունները մշակելու և համապատասխան պատասխաններ վերադարձնելու համար։ Ինչպես սովորաբար Ktor-ում, այս հնարավորությունը պետք է միացնել install() ֆունկցիայով և ավելացնել համապատասխան կախվածությունը։

dependencies {
    implementation("io.ktor:ktor-server-status-pages:$ktor_version")
}
fun Application.configureErrorHandling() {
    install(StatusPages) {
        exception<UserNotFoundException> { call, cause ->
            call.respond(HttpStatusCode.NotFound, ErrorResponse.from(cause))
        }

        exception<ValidationException> { call, cause ->
            call.respond(HttpStatusCode.BadRequest, ErrorResponse.from(cause))
        }

        exception<Throwable> { call, cause ->
            call.respond(HttpStatusCode.InternalServerError, ErrorResponse.from("An unexpected error occurred"))
        }
    }
}

HTTP կլիենտներ

Հազիվ թե ժամանակակից որևէ վեբ հավելված (եթե ընդհանրապես որևէ մեկը) պարզապես բացահայտի API և չշփվի այլ համակարգերի հետ։ Սա առավել կարևոր է միկրոսերվիս ճարտարապետությունում, որտեղ սերվիսները հաճախ ստիպված են համագործակցել բիզնես գործողություն կատարելու համար։

Նման հաղորդակցությունը առավել հաճախ ընդունում է սինխրոն HTTP կանչի տեսք, ինչը նշանակում է, որ հավելվածին HTTP կլիենտ է պետք։ Spring Boot-ը և Ktor-ը երկուսն էլ հզոր HTTP կլիենտ գրադարաններ են առաջարկում, բայց հետևում են տարբեր փիլիսոփայությունների և մոտեցումների։ Այս գլուխը քննում է, թե ինչով են այդ մոտեցումները տարբերվում։

Հարցումների և պատասխանների մշակում

Spring Boot

Spring Boot-ը ձեզ տալիս է HTTP կլիենտի մի քանի տարբերակ։ Սինխրոն կանչերի համար կան երկու գրադարան՝ ավելի հին և հայտնի RestTemplate-ը՝ իր template մեթոդների API-ով, և ավելի նոր RestClient-ը՝ ժամանակակից, սահուն API-ով։ Եթե ասինխրոն կանչեր են պետք, կա WebClient-ը՝ ռեակտիվ, չարգելափակող տարբերակ, որը լավ հարմար է բարձր թողունակության համակարգերին։

Երկու կլիենտներն էլ հարուստ ֆունկցիոնալություն են առաջարկում, ինչպիսին են հարցումների և պատասխանների մանիպուլյացիան, սխալների մշակումը և ավտոմատ սերիալիզացիան/դեսերիալիզացիան։ Այդուհանդերձ, WebClient-ը սովորաբար նախընտրելի ընտրություն է նոր կոդի համար՝ իր ժամանակակից API նախագծման և Spring-ի ռեակտիվ էկոհամակարգի հետ ավելի սերտ ինտեգրման շնորհիվ։ WebClient-ը կօգտագործեմ՝ Spring Boot-ի HTTP կլիենտի հնարավորությունները Ktor-ի հնարավորությունների հետ համեմատելու համար։

Ահա թե ինչպես կանչել /resources/{id} endpoint-ը authorization header-ով և Accept header-ով և մշակել պատասխանը WebClient-ով։

fun getResource(id: Long): Mono<Resource> =
    webClient.get()
        .uri("/resources/{id}", id)
        .header(HttpHeaders.AUTHORIZATION, "Bearer token")
        .accept(MediaType.APPLICATION_JSON)
        .retrieve()
        .bodyToMono(Resource::class.java)

Ktor

Ktor-ի HTTP կլիենտը հենվում է Kotlin-ի suspend ֆունկցիաների և DSL-ի վրա՝ հարցումներ ուղարկելու կոմպակտ շարահյուսություն առաջարկելով. HTTP մեթոդը սովորական ֆունկցիայի կանչ է, իսկ կոնֆիգուրացիան պահում է հարցման builder լամբդան։ Նախորդ օրինակի endpoint-ի կանչը authorization և Accept header-ներով հետևյալ տեսքն ունի։

suspend fun getResource(id: Long): Resource =  
    client.get("https://api.example.com/resources/$id") {
        header(HttpHeaders.Authorization, "Bearer token")
        accept(ContentType.Application.Json)
    }.body()

HTTP կլիենտի կարգավորում

Վերևի օրինակները ենթադրում են, որ HTTP կլիենտներն արդեն կարգավորված են։ Սակայն դրանք օգտագործելուց առաջ պետք է ճիշտ կոնֆիգուրացիա լինի։ Այս բաժնում կբացատրեմ, թե ինչպես են երկու ֆրեյմվորքները տարբերվում կոնֆիգուրացիայի իրենց մոտեցմամբ։

Spring Boot

Auto-configuration-ի շնորհիվ Spring Boot-ում WebClient-ի կարգավորումը հեշտ է. WebClient builder bean-ը գրանցվում է ավտոմատ, և կարող եք այն ներարկել ու հարմարեցնել շատ քիչ կոդով։ Կարող եք ձեռքով կառուցել ամբողջությամբ հարմարեցված WebClient bean, բայց հաճախ բավական է վերցնել նախակարգավորված builder-ը և ավելացնել ձեր սեփական հարմարեցումները։

Այնպիսի կարգավորումներ, ինչպիսին են կապի timeout-ները և պատասխանների չափերը, կարելի է կոնֆիգուրացնել application properties-ում՝ կոդի փոխարեն։ Եթե պետք լինի, սակայն, կարող եք նաև WebClient-ը կարգավորել ձեռքով և սահմանել ձեր սեփական հարմարեցված bean-ը։

@Configuration
class WebClientConfig {

    @Bean
    fun webClient(): WebClient {
        return WebClient.builder()
            .baseUrl("https://api.example.com")
            .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
            .clientConnector(ReactorClientHttpConnector(HttpClient.create()
                .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 5000)
                .responseTimeout(Duration.ofMillis(5000))
                .doOnConnected { conn ->
                    conn.addHandlerLast(ReadTimeoutHandler(5, TimeUnit.SECONDS))
                    conn.addHandlerLast(WriteTimeoutHandler(5, TimeUnit.SECONDS))
                }
            ))
            .build()
    }
}

WebClient-ին աշխատելու համար պետք է հիմքում ընկած HTTP կլիենտի գրադարան։ Լռելյայն այն օգտագործում է Reactor Netty։ Այն կարելի է փոխարինել Jetty-ի ռեակտիվ HTTP կլիենտով, եթե jetty-reactive-httpclient-ը classpath-ում է, կամ Apache HttpComponents-ով, եթե հասանելի է httpclient5-reactive-ը։ Spring Boot-ը հայտնաբերում է ձեր կախվածությունները և ավտոմատ կարգավորում է համապատասխան connector-ը։

Ktor

Ktor-ի HTTP կլիենտը տալիս է plugin-ների և DSL-ի վրա կառուցված ճկուն կոնֆիգուրացիայի համակարգ, որը թույլ է տալիս ավելացնել այնպիսի հնարավորություններ, ինչպիսիք են logging-ը, timeout-ների մշակումը, կրկնության (retry) մեխանիզմը և JSON սերիալիզացիան՝ կարճ, ընթեռնելի շարահյուսությամբ։ Բոլոր հնարավորությունները լռելյայն անջատված են, ուստի յուրաքանչյուրը պետք է բացահայտ միացնել՝ տեղադրելով դրա plugin-ը և (սովորաբար) ավելացնելով համապատասխան կախվածությունները։

Կլիենտը աշխատում է մի քանի փոխարինելի engine իրականացումներով՝ CIO (Coroutine-based I/O), Ktor-ի բնիկ engine-ը՝ հարմարեցված Kotlin կորուտիններին. Apache՝ հին համակարգերի աջակցության համար. OkHttp՝ JVM և Android հավելվածների համար. Java-ի HttpClient՝ ստանդարտ JVM հավելվածների համար. և պլատֆորմին հատուկ engine-ներ JavaScript և Native թիրախների համար։ Այսպես կարող եք ընտրել իրականացումը, որն առավել հարմար է ձեր գործարկման միջավայրին, պահպանելով API-ի օգտագործումը նույնը։

Կլիենտի engine-ների մասին ավելին հասանելի է այստեղ։

Ստորև բերված կոնֆիգուրացիան կարգավորում է Ktor-ի կլիենտը JSON-ի հետ աշխատելու համար։ Այն գրանցում է հարցումների և պատասխանների բոլոր տվյալները և կարգավորում է timeout-ներն ու հարցումների կրկնությունները։

val client = HttpClient(CIO) {

    // Install content negotiation plugin with JSON support
    install(ContentNegotiation) {
        json()
   }

    // Logging configuration
    install(Logging) {
        logger = Logger.DEFAULT
        level = LogLevel.ALL
    }

    // Timeouts configuration
    install(HttpTimeout) {
        requestTimeoutMillis = 5000
        connectTimeoutMillis = 5000
        socketTimeoutMillis = 5000
    }

    // Retries
    install(HttpRequestRetry) {
        retryOnServerErrors(maxRetries = 3)
        exponentialDelay()
    }

    // Engine-specific configuration
    engine {
        pipelining = true
        endpoint {
            connectTimeout = 5000
            socketTimeout = 5000
            requestTimeout = 5000
            keepAliveTime = 5000
        }
    }
}

Անհրաժեշտ կախվածություններ.

implementation("io.ktor:ktor-server-content-negotiation:$ktor_version")
implementation("io.ktor:ktor-serialization-kotlinx-json:$ktor_version")
implementation("io.ktor:ktor-client-core:$ktor_version")
implementation("io.ktor:ktor-client-cio:$ktor_version")
implementation("ch.qos.logback:logback-classic:$logback_version")

Սխալների մշակում

Բաշխված հաշվարկների ութ մոլորություններից առաջինն ասում է, որ «ցանցը հուսալի է»։ Քանի որ գիտենք, որ դա սխալ է, պետք է սխալներ կանխատեսենք, երբ HTTP կլիենտը ցանցային կանչեր է անում։ Քանի որ սա այսքան տարածված մտահոգություն է, HTTP կլիենտի գրադարանների մեծ մասը, այդ թվում՝ Spring Boot-ինն ու Ktor-ինը, գալիս են սխալների մշակման ներկառուցված մեխանիզմներով։ Տեսնենք, թե ինչպես են դրանք համեմատվում։

Spring Boot

Spring Boot-ում WebClient-ը սխալները մշակում է դեկլարատիվ կերպով onStatus ֆունկցիայի միջոցով, որը թույլ է տալիս ծրագրավորողներին սահմանել սխալների մշակման սեփական տրամաբանություն՝ կախված HTTP կարգավիճակի կոդերից։ Ֆրեյմվորքը գալիս է բացառությունների լայն հիերարխիայով, որում WebClientResponseException-ի ենթատիպերը համապատասխանում են սխալների տարբեր կատեգորիաների (4xx, 5xx), և դրանք կարելի է բռնել ու մշակել բացառությունների մշակման ստանդարտ տեխնիկաներով։

webClient.get()
    .uri("/resources/{id}", id)
    .retrieve()
    .onStatus({ it.is4xxClientError }) { response ->
        when (response.statusCode()) {
            HttpStatus.NOT_FOUND -> Mono.error(ResourceNotFoundException("Resource not found"))
            HttpStatus.UNAUTHORIZED -> Mono.error(UnauthorizedException("Unauthorized access"))
            else -> response.bodyToMono(String::class.java)
                .flatMap { Mono.error(ClientException("Client error: ${response.statusCode()}, body: $it")) }
        }
    }
    .onStatus({ it.is5xxServerError }) { response ->
        Mono.error(ServerException("Server error: ${response.statusCode()}"))
    }
    .bodyToMono(Resource::class.java)
    .onErrorResume(ResourceNotFoundException::class.java) { ex ->
        // Fallback logic
        Mono.just(Resource.notFound())
    }

Ktor

Ktor-ի HTTP կլիենտը սխալների մշակման երկու եղանակ է տալիս։ Կարող եք դրանց անդրադառնալ ծրագրային եղանակով՝ բռնելով պատասխանի վալիդացիայի կոնկրետ բացառություններ, կամ կարող եք հենվել հատուկ HttpCallValidator plugin-ի վրա, որն առաջարկում է սխալների գլոբալ մշակման մեխանիզմ։

Առաջին տարբերակի համար պետք է “expectSuccess” դրոշակը դնել true՝ կամ HTTP կլիենտի կոնֆիգուրացիայում, կամ առանձին հարցման համար։ Սա ստիպում է Ktor-ի կլիենտին 4xx և 5xx կարգավիճակի կոդերի դեպքում նետել համապատասխան բացառություններ։

//  HTTP client configuration
val client = HttpClient(CIO) {
    expectSuccess = true
    // …
}

suspend fun getResource(id: Long): Result<Resource> {
    return try {
        val resource = client.get<Resource>("https://api.example.com/resources/$id")
        Result.success(resource)
    } catch (e: ClientRequestException) {
        // 4xx responses
        when (e.response.status.value) {
            404 -> Result.failure(ResourceNotFoundException("Resource not found"))
            401 -> Result.failure(UnauthorizedException("Unauthorized access"))
            else -> Result.failure(e)
        }
    } catch (e: ServerResponseException) {
        // 5xx responses
        Result.failure(ServerException("Server error: ${e.response.status.value}"))
    } catch (e: Exception) {
        // Connection, timeout, or other errors
        Result.failure(e)
    }
}

Եվ ահա թե ինչպես կարգավորել գլոբալ մշակումը HttpCallValidator-ով։

install(HttpCallValidator) {
    handleResponseExceptionWithRequest { exception, request ->
        when (exception) {
            is ClientRequestException -> {
                val response = exception.response
                if (response.status.value == 401) {
                    throw UserUnauthorizedException(exception)
                } else {
                    handleClientException(exception)
                }
            }
            is ServerResponseException -> {
                handleServerError(exception)
            }
            else -> throw exception
        }
    }
}

Թեստավորում

Թեստավորումը կարևոր է ոչ միայն ստուգելու համար, որ ձեր կոդը բավարարում է պահանջները, այլև ապահովելու համար, որ այն շարունակում է ճիշտ աշխատել փոփոխվելիս։ Թեման բազմաթիվ կողմեր ունի, բայց պարզության համար կկենտրոնանամ թեստերի այն երեք տեսակների վրա, որոնք ծրագրավորողները առավել հաճախ օգտագործում են իրենց նախագծերում՝ unit, integration և slice թեստեր։

Այս գլխում կտեսնեք, թե ինչպես են այս թեստերը սովորաբար գրվում Spring Boot-ում և ինչպես նույն արդյունքներին հասնել Ktor-ում Kotest ֆրեյմվորքով։ Քանի որ այս հոդվածի նպատակը այս վեբ ֆրեյմվորքների ակնարկ տալն է, այն չի խորանում Kotest-ի բոլոր մանրամասների մեջ։

Unit թեստեր

Spring Boot

Unit թեստերը ստուգում են առանձին դասերի կամ մեթոդների վարքը մեկուսացված վիճակում։ Դրանք արագ են և օգնում են բռնել տրամաբանական սխալները՝ նախքան կախվածությունները և արտաքին համակարգերը ներգրավվելը։ Քանի որ unit թեստերն աշխատում են դասի մակարդակում, Spring Boot ֆրեյմվորքը դրանց համար հատուկ աջակցություն չի առաջարկում։ Սովորաբար unit թեստեր գրում ենք թեստավորման գրադարանով (JUnit, TestNG, Groovy-ում՝ Spock և այլն) Mockito-ի հետ միասին, որը կարող է stub անել թեստավորվող դասի կախվածությունները։ Ստորև բերված օրինակը հիմնված է JUnit 5-ի վրա։

@ExtendWith(MockitoExtension::class)
class UserServiceTest {

    @Mock
    private lateinit var repo: UserRepository

    @InjectMocks
    private lateinit var systemUnderTest: UserService

    @Test
    fun `should return user when found`() {
        val user = User(1L, "Alice")
        whenever(repo.findById(1L)).thenReturn(Optional.of(user))

        val result = systemUnderTest.findById(1L)

        assertThat(result.name).isEqualTo("Alice")
        verify(repo).findById(1L)
    }

    @Test
    fun `should throw when not found`() {
        whenever(repo.findById(any())).thenReturn(Optional.empty())

        assertThatThrownBy { systemUnderTest.findById(42L) }
          .isInstanceOf(NotFoundException::class.java)
    }
}

Kotest / Koin

Ճիշտ ինչպես Spring Boot-ը, Ktor-ը unit թեստավորման համար հատուկ հնարավորություններ չունի։ Կախված այն բանից, թե որ dependency-injection ֆրեյմվորքն եք օգտագործում, unit թեստերին կարող է պետք գալ որոշ լրացուցիչ boilerplate։ Օրինակ՝ Koin-ի դեպքում (ինչպես նկարագրված է նախորդ գլուխներում) պետք է գործարկել Koin համատեքստը և սահմանել թեստային մոդուլ, որը մատակարարում է ձեր mock արված կախվածությունները։

Ստորև բերված օրինակում սահմանել եմ թեստային մոդուլ mock արված UserRepository-ով, որի վարքը կարելի է առանձին կարգավորել յուրաքանչյուր թեստային դեպքի համար։ Թեստավորվող համակարգը (UserService), մյուս կողմից, իրական օրինակ է, որը mock արված repository-ն ստանում է dependency injection-ով։ Սա թույլ է տալիս repository-ի վարքը հարմարեցնել յուրաքանչյուր թեստի հատուկ կարիքներին։

class UserServiceTest : StringSpec(), KoinTest {
    private val testModule = module {
        single<UserRepository> { mockk(relaxed = true) }
        single { UserService(get()) }
    }

    private val repo: UserRepository by inject()
    private val systemUnderTest: UserService by inject()

    init {
        beforeSpec {
            startKoin { modules(testModule) }
        }
        afterSpec {
            stopKoin()
        }

        "should return user when found" {
            val user = User(1, "Alice")
            every { repo.getById(1) } returns user
            systemUnderTest.findById(1).name shouldBe "Alice"
            verify { repo.getById(1) }
        }

        "should throw exception when not found" {
            every { repo.getById(any()) } returns null
            shouldThrow<NotFoundException> { systemUnderTest.findById(42) }
        }
    }
}

Integration թեստեր

Integration թեստերը ընդգրկում են ձեր հավելվածի ավելի մեծ մասը՝ սովորաբար գործարկելով ամբողջ համատեքստը (իրական HTTP սերվերով, տվյալների բազայի կապերով, միգրացիաներով, սերիալիզացիայով և այլն)՝ ստուգելու, որ բաղադրիչները ճիշտ են համագործակցում։ Դրանք հակված են unit թեստերից ավելի դանդաղ լինել, բայց չափազանց արժեքավոր են կոնֆիգուրացիայի սխալները, գործարկման ժամանակի անհամապատասխանությունները և ինտեգրման կետերը գտնելու համար, որոնք միայն unit թեստերը չեն կարող բացահայտել։

Spring Boot

Spring Boot integration թեստերը սովորաբար հենվում են @SpringBootTest annotation-ի վրա, որը գործարկում է հավելվածի ամբողջ համատեքստը՝ ներառյալ ձեր կոնտրոլերները, սերվիսները, repository-ները և ցանկացած ներկառուցված սերվերի կամ տվյալների բազայի կոնֆիգուրացիա։ Նման թեստերը հաստատում են, որ ձեր Spring bean-ները ճիշտ են միացված, որ կոնֆիգուրացիայի property-ները ուժի մեջ են մտնում, և որ իրական բաղադրիչները (օր.՝ JPA repository-ները, որոնք աշխատում են ներկառուցված կամ թեստային տվյալների բազայի դեմ) փոխազդում են նախատեսված կերպով։ Ստորև բերված օրինակը ստուգում է օգտատիրոջ ստեղծման գործընթացը Spring Boot հավելվածում։

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class UserIntegrationTest {

    @Autowired
    private lateinit var rest: TestRestTemplate

    @Test
    fun `create and fetch user`() {
        val newUser = mapOf("name" to "Alice")
        val create = rest.postForEntity("/users", newUser, UserDto::class.java)
        assertThat(create.statusCode).isEqualTo(HttpStatus.CREATED)

        val id = create.body!!.id
        val get = rest.getForEntity("/users/$id", UserDto::class.java)
        assertThat(get.body!!.name).isEqualTo("Alice")
    }
}

Ktor

Ktor integration թեստերը սովորաբար օգտագործում են ներկառուցված թեստային engine-ը (testApplication { … }-ի միջոցով)՝ ձեր մոդուլներն ու plugin-ները գործարկելու համար in-memory սերվերում, ապա այն փորձարկում են HTTP կլիենտով, ճիշտ ինչպես իրական կլիենտը կաներ։ Կարող եք միացնել թեստային տվյալների բազաներ (օր.՝ H2 կամ TestContainers) և կատարել ձեր միգրացիաները, բայց յուրաքանչյուր հնարավորություն պետք է բացահայտ տեղադրվի և կարգավորվի ձեր թեստի կարգավորման մեջ։

Մինչդեռ Spring Boot-ը ավտոմատ կերպով գործարկում է հավելվածի ամբողջ համատեքստը, Ktor integration թեստերը ավելի արագ են բեռնվում և ձեզ տալիս են ճշգրիտ վերահսկողություն, քանի որ յուրաքանչյուր հնարավորություն բացահայտ տեղադրվում և կարգավորվում է։ Spring Boot թեստերն, իրենց հերթին, առաջնահերթություն են տալիս հարմարությանը և ձեր հավելվածի ավտոմատ կարգավորված միջավայրի ավելի լայն ընդգրկմանը։ Ստորև բերված օրինակը թեստավորում է օգտատիրոջ ստեղծումը մեր հավելվածում H2 in-memory տվյալների բազայով։

class UserIntegrationTest : StringSpec({
    "create and fetch user" {
        testApplication {
            environment {
                config = MapApplicationConfig(
                    "ktor.deployment.port" to "0",
                    "database.url" to "jdbc:h2:mem:test;DB_CLOSE_DELAY=-1",
                    "database.username" to "sa",
                    "database.password" to "XXX"
                )
            }
            application {
                myAppModule()
            }
            val client = createClient {
                install(io.ktor.client.plugins.contentnegotiation.ContentNegotiation) {
                    json()
                }
            }
            val createResp = client.post("/users") {
                contentType(ContentType.Application.Json)
                setBody(UserDto(name = "Alice"))
            }
            createResp.status shouldBe HttpStatusCode.Created
            val id = createResp.body<UserDto>().id
            // Fetch user
            val getResp = client.get("/users/$id")
            getResp.status shouldBe HttpStatusCode.OK
            getResp.body<UserDto>().name shouldBe "Alice"
        }
    }
})

Slice թեստեր

Slice թեստերը թիրախավորում են ձեր հավելվածի մեկ շերտը կամ «slice»-ը, օրինակ՝ վեբ, սերվիսի կամ տվյալների շերտը։ Վեբ հավելվածներում դրանք սովորաբար օգտագործվում են կոնտրոլերները կամ երթուղավորումը թեստավորելու համար՝ առանց ամբողջ հավելվածը գործարկելու։ Բեռնվում են միայն այն bean-ները և կոնֆիգուրացիան, որոնք անհրաժեշտ են slice-ին, իսկ մնացած ամեն ինչ mock է արվում։ Այդ իսկ պատճառով դրանք ավելի արագ են, քան ամբողջական integration թեստերը, միևնույն ժամանակ ստուգելով slice-ի ներսի իրական փոխազդեցությունները։

Spring Boot

Spring Boot slice թեստերը օգտագործում են հատուկ թեստային annotation-ներ, ինչպիսիք են @WebMvcTest-ը, @DataJpaTest-ը կամ @RestClientTest-ը, որպեսզի բեռնեն հավելվածի համատեքստի միայն տվյալ շերտին պատկանող մասերը՝ մնացած ամենինը mock անելով։ Ստորև բերված կոդը թեստավորում է UserController-ը @WebMvcTest annotation-ով, որը գործարկում է կոնտրոլերի slice-ը և հենվում է mock արված UserService-ի վրա՝ ստուգելու, որ կոնտրոլերը ճիշտ է վարվում։

@WebMvcTest(UserController::class)
class UserControllerTest {

    @Autowired
    private lateinit var mvc: MockMvc

    @MockBean
    private lateinit var service: UserService

    @Test
    fun `should return user`() {
        given(service.findById(1L)).willReturn(User(1L, "Alice"))

        mvc.perform(get("/users/1"))
           .andExpect(status().isOk)
           .andExpect(jsonPath("$.name").value("Alice"))
    }
}

Ktor

Ktor-ը slice թեստերի համար հատուկ հնարավորություն չունի։ Սակայն կարող եք օգտագործել վերը նշված testApplication DSL-ը՝ գործարկելու միայն այն կոնկրետ մոդուլները կամ երթուղիները, որոնք ուզում եք ստուգել, տեղադրելով միայն ընտրված plugin-ները (օր.՝ ContentNegotiation, Authentication) և մնացածի համար միացնելով Koin override-ներ կամ mock արված կախվածություններ։

Սա թույլ է տալիս անմիջապես փորձարկել այդ slice-երը և ստուգել սերիալիզացիայի, վալիդացիայի և երթուղավորման տրամաբանությունը՝ իրական տվյալների բազայից կամ արտաքին սերվիսներից մեկուսացված։ Ստորև բերված օրինակը օգտագործում է testApplication DSL-ը՝ JSON content negotiation տեղադրելու, Koin մոդուլ սահմանելու mock արված UserService-ով և միայն օգտատիրոջ հետ կապված երթուղիները սահմանելու համար, որպեսզի թեստավորվի միայն երթուղավորման slice-ը։

class UserRoutesTest : StringSpec({
    "should return user" {
        val mockService = mockk<UserService>()
        every { mockService.findById(1) } returns User(1, "Alice")

        testApplication {
            install(ContentNegotiation) { json() }
            install(Koin) {
                modules(module { single { mockService } })
            }

            routing { userRoutes() }
            val response = client.get("/users/1")
            response.status shouldBe HttpStatusCode.OK
            response.body<UserDto>().name shouldBe "Alice"
        }
    }
})

Մաս 2-ի ամփոփում

Հոդվածի այս մասի նպատակն էր ներկայացնել Ktor ֆրեյմվորքը՝ նշելով դրա հիմնական հնարավորությունները և դրանք կապելով Spring Boot-ի ծանոթ հասկացությունների հետ՝ ուսուցումը հեշտացնելու համար։ Ահա քննարկված և համեմատված թեմաների ամփոփումը։

HTTP հարցումների մշակում

  • Spring Boot. annotation-ների վրա հիմնված կոնտրոլերներ
  • Ktor. DSL-ի վրա հիմնված երթուղավորում extension ֆունկցիաներով, ինչպես նաև լիովին տիպերով անվտանգ երթուղավորում

Բացառությունների մշակում

  • Spring Boot. հենվում է @ControllerAdvice-ի և @ExceptionHandler-ի վրա
  • Ktor. հենվում է StatusPages plugin-ի վրա՝ գրանցված handler-ներով

HTTP կլիենտներ

  • Spring Boot. տրամադրում է RestTemplate և WebClient՝ դեկլարատիվ սխալների մշակմամբ
  • Ktor. հենվում է suspend ֆունկցիաների, plugin-ների միջոցով կոնֆիգուրացիայի և ծրագրային սխալների մշակման վրա

Թեստավորում

  • Spring Boot. հենվում է JUnit 5-ի (կամ այլ JVM ֆրեյմվորքների) և Mockito-ի վրա unit թեստերի համար, @WebMvcTest + MockMvc-ի վրա՝ կոնտրոլերների slice թեստերի համար (կամ այլ շերտերի դեպքում դրանց համարժեքների), և @SpringBootTest + TestRestTemplate-ի վրա՝ լիարժեք integration թեստերի համար։
  • Ktor. հենվում է Kotest-ի և MockK-ի (գումարած, օրինակ, DI-ի համար Koin-ի) վրա unit թեստերի համար, և testApplication { … } DSL-ի վրա՝ և slice, և integration թեստերի համար, in-process HTTP կլիենտով և կարգավորելի հավելվածի միջավայրով – սա ձեզ տալիս է ավելի շատ վերահսկողություն այն բանի վրա, ինչ թեստավորում եք, ավելի շատ ծիսակարգի գնով։

Հոդվածի երկու մասերն էլ շատ բան են ընդգրկում, բայց չեն շոշափում այն ամենը, ինչ պետք է Ktor-ով վեբ հավելված կառուցելիս։ Ձեր նախագծերում Ktor-ը հաջողությամբ օգտագործելու համար հավանաբար ստիպված կլինեք ավելին սովորել։