Ծանոթանում ենք Ktor-ին Spring Boot-ի տեսանկյունից. Մաս 2
Շարունակում ենք ուսումնասիրել Ktor-ը Spring Boot-ը լավ իմացող ծրագրավորողի աչքերով։ Այս մասում քննարկվում են HTTP հարցումների և բացառությունների մշակումը, HTTP կլիենտները և թեստավորումը՝ ցույց տալով, թե ինչպես են Ktor-ի ներկառուցված հնարավորությունները պարզեցնում այս ոլորտներից յուրաքանչյուրը։
Այստեղ շարունակում ենք ուսումնասիրել 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-ը հաջողությամբ օգտագործելու համար հավանաբար ստիպված կլինեք ավելին սովորել։