تقدير المشروع
← كل المقالات

التعرف على Ktor من منظور Spring Boot. الجزء 2

نواصل استكشاف Ktor بعيون مطوّر يعرف Spring Boot جيداً. يتناول هذا الجزء معالجة طلبات HTTP والاستثناءات، وعملاء HTTP، والاختبار، ويوضح كيف تبسّط المزايا المدمجة في Ktor كل مجال من هذه المجالات.

17 دقائق قراءة
Spring BootKotlinKtorKotlinServerSide

نواصل هنا استكشاف Ktor من وجهة نظر مطوّر يعرف Spring Boot بالفعل. وضع الجزء الأول الأسس، فتناول إعداد التطبيق ومحركات الخادم والإعدادات وحقن الاعتمادات. وننتقل هذه المرة إلى مواضيع أكثر تقدماً في بناء تطبيقات الويب باستخدام Ktor. في هذا الجزء سأتناول معالجة طلبات HTTP ومعالجة الاستثناءات، وعملاء HTTP، والاختبار، لأوضح كيف تبسّط المزايا المدمجة في Ktor كل مجال من هذه المجالات.

معالجة طلبات HTTP

تُعد معالجة طلبات HTTP عبر نقاط نهاية REST المكشوفة من أهم مهام تطبيق الويب. ولهذا يأتي كل إطار عمل ويب بآليات لمعالجة الطلبات، سواء سارت الأمور على ما يرام أو وقعت أخطاء.

وكما في المجالات الأخرى، يتعامل Spring Boot وKtor مع هذا الأمر بشكل مختلف، بما يتماشى مع فلسفتيهما المختلفتين. في هذا الفصل سنرى كيف يتيح لك كل إطار عمل تعريف المسارات وتنظيمها، والتعامل مع معاملات الطلب، والاستجابة للحالات الاستثنائية.

تعريف المسارات وتنظيمها

Spring Boot

يعتمد Spring Boot على متحكمات (controllers) قائمة على التعليقات التوضيحية (annotations)، يمكنك تجميعها حسب نقاط النهاية التي تكشفها. عند بدء التشغيل، يعثر الإطار على هذه المتحكمات ويسجلها تلقائياً بفضل مسح المكونات (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

يستفيد نظام التوجيه (routing) في Ktor من قدرات DSL القوية في Kotlin ويوفر طريقة سلسة وهرمية لتداخل المسارات بحيث تعكس بنيتها مسارات URL بشكل طبيعي. وعلى عكس الأطر القائمة على annotations، يشجع Ktor على التقسيم إلى وحدات باستخدام دوال الامتداد، فيستطيع المطورون وضع المسارات ذات الصلة في ملفات منفصلة.

// 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() التي تثبّت إضافة Routing في تطبيق Ktor. وداخل جسم lambda تُنفَّذ دالتا امتداد تعرّفان مسارات Users وOrders.

يبدأ تعريف المسار بالمسار نفسه، المحدد بدالة DSL مثل route(“/api/users”). وداخل lambda المقابلة، تُعلن نقاط النهاية بدوال تحمل أسماء طرق HTTP (get وpost وput وهكذا).

لمعالجة الطلبات الواردة وإرجاع الاستجابات، تعتمد عادةً على الخاصية call، وهي نسخة من RoutingCall. وبواسطتها يمكنك:

  • الحصول على متغير المسار، مثل call.parameters[“id”]
  • الحصول على معامل الطلب، مثل call.request.queryParameters[“name”]
  • الحصول على حمولة الطلب، مثل call.receive()
  • إرسال استجابة، مثل call.respond(HttpStatusCode.NotFound)

التوجيه مع أمان الأنواع

Spring Boot

يمنحك نموذج Spring Boot القائم على المتحكمات أمان الأنواع لأجسام الطلبات والاستجابات، لكن متغيرات المسار ومعاملات الطلب تُربط عبر سلاسل نصية، تُحلّ وقت التشغيل ولذلك فهي غير آمنة من ناحية الأنواع.

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

Ktor

يوفر Ktor خياراً أكثر أماناً من ناحية الأنواع عبر ميزة Resources. فهي تتجاوز تعريفات المسارات القائمة على السلاسل النصية بنمذجة بنية واجهتك البرمجية كتسلسل هرمي من الأصناف، يكون فيه كل مسار كائناً قوي الأنواع بمعاملات ذات أنواع صحيحة.

ونتيجة لذلك، تُفحص معاملات المسارات ومساراتها وقت الترجمة، مما يستبعد أخطاء وقت التشغيل المعتادة، وتتيح لك الدالة href() توليد عناوين URL بطريقة آمنة من ناحية الأنواع. وبما أن المسارات تُنمذج كأصناف لا كسلاسل نصية، تصبح إعادة الهيكلة أكثر أماناً وأسهل في التعامل. كل ما عليك هو تعريف التسلسل الهرمي للأصناف الذي يصف واجهتك البرمجية واستخدامه في تعريف التوجيه.

// 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

لتفعيل Resources في Ktor، أضف الاعتماد أدناه وثبّت إضافة Resources:

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

معالجة الاستثناءات

Spring Boot

يقدم Spring Boot عدداً من الطرق لمعالجة الاستثناءات: المعالجة العامة بالتعليق التوضيحي @ControllerAdvice، ومعالجة أدق على مستوى المتحكم بـ @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

نادراً ما يكتفي تطبيق ويب حديث، إن وُجد، بكشف واجهة برمجية دون التحدث إلى أنظمة أخرى. ويزداد هذا أهمية في بنية الخدمات المصغّرة، حيث تضطر الخدمات كثيراً إلى التعاون لتنفيذ عملية عمل واحدة.

وغالباً ما يتخذ هذا التواصل شكل استدعاء HTTP متزامن، أي أن التطبيق يحتاج إلى عميل HTTP. يوفر كل من Spring Boot وKtor مكتبتي عميل HTTP قويتين، لكنهما تتبعان فلسفتين ونهجين مختلفين. يتناول هذا الفصل كيف تختلف هذه النهج.

معالجة الطلبات والاستجابات

Spring Boot

يمنحك Spring Boot عدة خيارات لعميل HTTP. للاستدعاءات المتزامنة هناك مكتبتان: RestTemplate الأقدم والمعروفة بواجهتها القائمة على أسلوب القوالب (template method)، وRestClient الأحدث بواجهتها العصرية السلسة. وإذا احتجت إلى استدعاءات غير متزامنة، فهناك WebClient، وهو خيار تفاعلي (reactive) غير حاجب يناسب الأنظمة ذات الإنتاجية العالية.

يقدم كلا العميلين وظائف غنية، مثل التعامل مع الطلبات والاستجابات ومعالجة الأخطاء والتسلسل/إلغاء التسلسل التلقائي. ومع ذلك، يُفضَّل WebClient عادةً للشيفرة الجديدة بفضل تصميم واجهته العصري وتكامله الأوثق مع منظومة Spring التفاعلية. وسأستخدم WebClient لمقارنة قدرات عميل HTTP في Spring Boot بقدرات Ktor.

إليك كيفية استدعاء نقطة النهاية /resources/{id} مع ترويسة التفويض وترويسة Accept ومعالجة الاستجابة باستخدام 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

يعتمد عميل HTTP في Ktor على دوال suspend في Kotlin وعلى DSL ليقدم صياغة مدمجة لإرسال الطلبات: فطريقة HTTP مجرد استدعاء دالة عادي، وlambda منشئ الطلب تحمل الإعداد. ويبدو استدعاء نقطة النهاية من المثال السابق مع ترويستي التفويض وAccept هكذا.

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

بفضل الإعداد التلقائي، يكون إعداد WebClient في Spring Boot سهلاً: يُسجَّل bean لمنشئ WebClient تلقائياً، ويمكنك حقنه وتخصيصه بشيفرة قليلة جداً. يمكنك بناء bean مخصص بالكامل لـ WebClient يدوياً، لكن غالباً يكفي أخذ المنشئ المُعدّ مسبقاً وإضافة تخصيصاتك.

يمكن ضبط إعدادات مثل مهل الاتصال وأحجام الاستجابات في خصائص التطبيق بدلاً من الشيفرة. لكن إذا احتجت إلى ذلك، يمكنك أيضاً إعداد 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. ويمكن استبدالها بعميل HTTP التفاعلي الخاص بـ Jetty إذا كانت jetty-reactive-httpclient في مسار الفئات (classpath)، أو بـ Apache HttpComponents إذا توفرت httpclient5-reactive. ويكتشف Spring Boot اعتماداتك ويعدّ الموصّل المطابق تلقائياً.

Ktor

يوفر عميل HTTP في Ktor نظام إعداد مرناً مبنياً على الإضافات (plugins) وDSL، يتيح لك إضافة مزايا مثل التسجيل ومعالجة المهل وآلية إعادة المحاولة وتسلسل JSON بصياغة قصيرة مقروءة. جميع المزايا معطلة افتراضياً، لذا عليك تفعيل كل منها صراحةً بتثبيت إضافتها و(عادةً) إضافة الاعتمادات المناسبة.

يعمل العميل مع عدة تنفيذات محركات قابلة للتبديل: CIO (Coroutine-based I/O)، وهو المحرك الأصلي في Ktor المضبوط لكوروتينات Kotlin؛ وApache لدعم الأنظمة القديمة؛ وOkHttp لتطبيقات JVM وAndroid؛ وHttpClient من Java لتطبيقات JVM القياسية؛ ومحركات خاصة بالمنصات لأهداف JavaScript وNative. وبهذه الطريقة يمكنك اختيار التنفيذ الأنسب لبيئة التشغيل لديك مع إبقاء استخدام الواجهة البرمجية كما هو.

مزيد من المعلومات عن محركات العميل متاح هنا.

يعدّ الإعداد أدناه عميل Ktor للعمل مع JSON. فهو يسجّل جميع بيانات الطلبات والاستجابات، ويضبط المهل وإعادة محاولة الطلبات.

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

يمنحك عميل HTTP في Ktor طريقتين لمعالجة الأخطاء. يمكنك التعامل معها برمجياً بالتقاط استثناءات محددة للتحقق من الاستجابة، أو الاعتماد على الإضافة المخصصة HttpCallValidator التي توفر آلية معالجة أخطاء عامة.

للخيار الأول، عليك ضبط العلم “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
        }
    }
}

الاختبار

لا تقتصر أهمية الاختبار على التحقق من أن شيفرتك تلبي المتطلبات، بل تشمل أيضاً ضمان استمرارها في العمل بشكل صحيح مع تغيرها. للموضوع جوانب كثيرة، لكن للتبسيط سأركز على ثلاثة أنواع من الاختبارات يستخدمها المطورون في مشاريعهم أكثر من غيرها: اختبارات الوحدة، واختبارات التكامل، واختبارات الشرائح (slice tests).

في هذا الفصل سترى كيف تُكتب هذه الاختبارات عادةً في Spring Boot وكيف تحصل على النتائج نفسها في Ktor باستخدام إطار Kotest. وبما أن هذا المقال يهدف إلى تقديم نظرة عامة على أطر الويب هذه، فإنه لا يخوض في تفاصيل Kotest كاملة.

اختبارات الوحدة

Spring Boot

تفحص اختبارات الوحدة سلوك الأصناف أو الدوال المنفردة بمعزل عن غيرها. وهي سريعة وتساعد على اكتشاف الأخطاء المنطقية قبل إشراك الاعتمادات والأنظمة الخارجية. وبما أن اختبارات الوحدة تعمل على مستوى الصنف، فإن إطار Spring Boot لا يقدم دعماً خاصاً لها. وعادةً نكتب اختبارات الوحدة بمكتبة اختبار (JUnit أو TestNG أو Spock في Groovy، وغيرها) مع Mockito الذي يمكنه محاكاة اعتمادات الصنف المختبَر. المثال أدناه مبني على 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 مزايا خاصة لاختبار الوحدة. وبحسب إطار حقن الاعتمادات الذي تستخدمه، قد تحتاج اختبارات الوحدة إلى بعض الشيفرة الجاهزة الإضافية. فمع Koin (كما وُصف في الفصول السابقة)، مثلاً، عليك تشغيل سياق Koin وتعريف وحدة اختبار تزوّد اعتماداتك المحاكاة.

في المثال أدناه، عرّفت وحدة اختبار فيها UserRepository محاكى، يمكن ضبط سلوكه بشكل منفصل لكل حالة اختبار. أما النظام قيد الاختبار (UserService) فهو نسخة حقيقية تحصل على المستودع المحاكى عبر حقن الاعتمادات. وهذا يتيح لك تشكيل سلوك المستودع بما يناسب الاحتياجات الخاصة بكل اختبار.

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) }
        }
    }
}

اختبارات التكامل

تغطي اختبارات التكامل جزءاً أكبر من تطبيقك، وعادةً ما تشغّل السياق بأكمله (بخادم HTTP حقيقي واتصالات بقاعدة البيانات وعمليات ترحيل وتسلسل وغيرها) للتحقق من أن المكونات تتعاون بشكل صحيح. وهي تميل إلى أن تكون أبطأ من اختبارات الوحدة، لكنها قيّمة للغاية في اكتشاف أخطاء الإعداد وعدم التطابق وقت التشغيل ونقاط التكامل التي لا تكشفها اختبارات الوحدة وحدها.

Spring Boot

تعتمد اختبارات التكامل في Spring Boot عادةً على التعليق التوضيحي @SpringBootTest، الذي يشغّل سياق التطبيق الكامل، بما في ذلك المتحكمات والخدمات والمستودعات وأي إعداد لخادم أو قاعدة بيانات مدمجة. وتؤكد هذه الاختبارات أن Spring beans مربوطة بشكل صحيح، وأن خصائص الإعداد تسري، وأن المكونات الحقيقية (مثل مستودعات JPA العاملة مع قاعدة بيانات مدمجة أو للاختبار) تتفاعل كما هو مقصود. يفحص المثال أدناه عملية إنشاء مستخدم في تطبيق 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 عادةً محرك الاختبار المدمج (عبر testApplication { … }) لتشغيل وحداتك وإضافاتك في خادم داخل الذاكرة ثم التعامل معه بعميل HTTP تماماً كما يفعل عميل حقيقي. يمكنك توصيل قواعد بيانات للاختبار (مثل H2 أو TestContainers) وتشغيل عمليات الترحيل، لكن يجب تثبيت كل ميزة وإعدادها صراحةً في إعداد الاختبار.

وبينما يشغّل Spring Boot سياق التطبيق بالكامل تلقائياً، تُقلع اختبارات التكامل في Ktor أسرع وتمنحك تحكماً دقيقاً، لأن كل ميزة تُثبَّت وتُعدّ صراحةً. أما اختبارات Spring Boot فتعطي الأولوية بدورها للراحة ولتغطية أوسع لبيئة تطبيقك المعدّة تلقائياً. يختبر المثال أدناه إنشاء مستخدم في تطبيقنا بقاعدة بيانات H2 داخل الذاكرة.

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 tests)

تستهدف اختبارات الشرائح طبقة واحدة، أو «شريحة»، من تطبيقك، مثل طبقة الويب أو الخدمة أو البيانات. وفي تطبيقات الويب تُستخدم عادةً لاختبار المتحكمات أو التوجيه دون تشغيل التطبيق بأكمله. فلا تُحمَّل إلا beans والإعدادات التي تحتاجها الشريحة، ويُحاكى كل ما عداها. ولهذا فهي أسرع من اختبارات التكامل الكاملة مع أنها تتحقق من التفاعلات الحقيقية داخل الشريحة.

Spring Boot

تستخدم اختبارات الشرائح في Spring Boot تعليقات اختبار مخصصة مثل @WebMvcTest أو @DataJpaTest أو @RestClientTest لتحميل الأجزاء التي تنتمي إلى الطبقة المعنية فقط من سياق التطبيق، مع محاكاة كل ما عداها. يختبر الكود أدناه UserController بالتعليق @WebMvcTest، الذي يشغّل شريحة المتحكم ويعتمد على 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 ميزة مخصصة لاختبارات الشرائح. لكن يمكنك استخدام DSL المسماة testApplication المذكورة سابقاً لتشغيل الوحدات أو المسارات المعينة التي تريد فحصها فقط، مع تثبيت إضافات مختارة فقط (مثل ContentNegotiation وAuthentication) وتوصيل تجاوزات Koin أو اعتمادات محاكاة لما تبقى.

وهذا يتيح لك تمرين هذه الشرائح مباشرة والتحقق من منطق التسلسل والتحقق من الصحة والتوجيه بمعزل عن قاعدة البيانات الحقيقية أو الخدمات الخارجية. يستخدم المثال أدناه DSL المسماة testApplication لتثبيت التفاوض على محتوى JSON وتعريف وحدة Koin فيها UserService محاكى وتعريف المسارات المتعلقة بالمستخدم فقط، بحيث تُختبر شريحة التوجيه وحدها.

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: متحكمات قائمة على annotations
  • Ktor: توجيه قائم على DSL مع دوال امتداد، إضافة إلى توجيه آمن الأنواع بالكامل

معالجة الاستثناءات

  • Spring Boot: يعتمد على @ControllerAdvice و@ExceptionHandler
  • Ktor: يعتمد على إضافة StatusPages مع معالجات مسجّلة

عملاء HTTP

  • Spring Boot: يوفر RestTemplate وWebClient مع معالجة أخطاء تصريحية
  • Ktor: يعتمد على دوال suspend والإعداد عبر الإضافات ومعالجة الأخطاء برمجياً

الاختبار

  • Spring Boot: يعتمد على JUnit 5 (أو أطر JVM أخرى) وMockito لاختبارات الوحدة، و@WebMvcTest + MockMvc لاختبارات شرائح المتحكمات (أو ما يعادلها لشرائح أخرى)، و@SpringBootTest + TestRestTemplate لاختبارات التكامل الكاملة.
  • Ktor: يعتمد على Kotest وMockK (إضافة إلى Koin مثلاً لحقن الاعتمادات) لاختبارات الوحدة، وعلى DSL المسماة testApplication { … } لاختبارات الشرائح والتكامل معاً، مع عميل HTTP داخل العملية وبيئة تطبيق قابلة للإعداد – وهذا يمنحك تحكماً أكبر فيما تختبره، على حساب مزيد من الإجراءات الشكلية.

يغطي جزءا المقال معاً مساحة واسعة، لكنهما لا يتناولان كل ما تحتاجه عند بناء تطبيق ويب باستخدام Ktor. وربما سيتعين عليك تعلّم المزيد لاستخدام Ktor بنجاح في مشاريعك.