Ktor — βασικές έννοιες, βιβλιοθήκη πελάτη και Kotlin Multiplatform

Τι είναι το Ktor;

Ktor — είναι ένα πλαίσιο για τη δημιουργία HTTP πελατών και διακομιστών στη γλώσσα Kotlin, που αναπτύχθηκε από την εταιρεία JetBrains. Σε αντίθεση με τις παραδοσιακές βιβλιοθήκες, το Ktor σχεδιάστηκε από την αρχή για πολυπλατφορμική ανάπτυξη και λειτουργεί σε όλες τις πλατφόρμες που υποστηρίζονται από την Kotlin.

Το Ktor χρησιμοποιεί την προσέγγιση των ενδιάμεσων χειριστών, εμπνευσμένη από την αρχιτεκτονική Kodein και Express.js. Κάθε αίτημα περνά μέσα από έναν αγωγό συναρτήσεων χειριστών που μπορούν να τροποποιήσουν το αίτημα και την απόκριση. Αυτό παρέχει ευελιξία που δεν είναι διαθέσιμη σε βιβλιοθήκες με άκαμπτη αρχιτεκτονική βασισμένη σε σχολιασμούς.

Η τρέχουσα έκδοση Ktor 3.0 περιλαμβάνει υποστήριξη για Kotlin 2.0, τον μεταγλωττιστή K2 και μια νέα μηχανή CIO (Coroutine I/O) με βελτιωμένη απόδοση. Η βιβλιοθήκη διανέμεται υπό την άδεια Apache 2.0 και είναι διαθέσιμη για εμπορική χρήση χωρίς περιορισμούς.

Το τμήμα πελάτη του Ktor είναι πλήρως χτισμένο σε coroutines Kotlin, εξασφαλίζοντας αποτελεσματική ασύγχρονη εκτέλεση αιτημάτων χωρίς αποκλεισμό νημάτων. Το τμήμα διακομιστή επιτρέπει τη δημιουργία HTTP διακομιστών με δρομολόγηση, επεξεργασία αιτημάτων και συνδέσεις WebSocket.

Το Ktor χρησιμοποιεί αρχιτεκτονική πρόσθετων: όλες οι πρόσθετες λειτουργίες — καταγραφή, σειριοποίηση, αυθεντικοποίηση — συνδέονται μέσω πρόσθετων. Αυτό καθιστά τη βιβλιοθήκη αρθρωτή και επιτρέπει τη σύνδεση μόνο των απαραίτητων στοιχείων, μειώνοντας το μέγεθος της τελικής εφαρμογής.

Χάρη στο ενοποιημένο API σε όλες τις πλατφόρμες, ο προγραμματιστής δεν χρειάζεται να μάθει διαφορετικούς HTTP πελάτες για iOS και Android. Σε ένα πολυπλατφορμικό έργο, ο κώδικας του επιπέδου δικτύου είναι πλήρως κοινόχρηστος και η υλοποίηση που είναι ειδική για την πλατφόρμα είναι κρυμμένη πίσω από τη μηχανή HttpClient. Αυτό συντομεύει τον χρόνο ανάπτυξης και μειώνει τον αριθμό σφαλμάτων που σχετίζονται με τις διαφορές πλατφορμών.

Βασικές δυνατότητες του Ktor

Το Ktor προσφέρει ένα σύνολο λειτουργιών που το καθιστούν ελκυστική επιλογή για σύγχρονα έργα Kotlin, ιδιαίτερα πολυπλατφορμικά.

Υποστήριξη πολλαπλών πλατφορμών

Το Ktor λειτουργεί σε JVM, Android, iOS, macOS, Windows, Linux, JavaScript και Wasm. Ο ίδιος κώδικας HTTP πελάτη εκτελείται σε όλες τις πλατφόρμες χωρίς αλλαγές. Αυτό είναι ένα βασικό πλεονέκτημα σε σύγκριση με βιβλιοθήκες που είναι δεσμευμένες στο OkHttp ή το URLSession.

Ασύγχρονοτητα σε coroutines

Τα coroutines Kotlin παρέχουν φυσική ασύγχρονοτητα χωρίς callbacks. Κάθε αίτημα είναι μια συνάρτηση suspend που μπορεί να κληθεί από οποιοδήποτε coroutine. Το Ktor υποστηρίζει ροή αποκρίσεων μέσω Flow, που είναι βολικό για μεγάλες συνδέσεις και WebSocket.

Αρχιτεκτονική πρόσθετων

Τα πρόσθετα Ktor συνδέονται μέσω μπλοκ install και διαμορφώνονται ξεχωριστά. Κύρια πρόσθετα: ContentNegotiation για σειριοποίηση, Logging για καταγραφή, Auth για αυθεντικοποίηση και WebSockets για αμφίδρομη επικοινωνία. Κάθε πρόσθετο μπορεί να ενεργοποιηθεί ή να απενεργοποιηθεί ανεξάρτητα.

Διαχείριση σφαλμάτων και χρονικά όρια

Η διαχείριση σφαλμάτων στο Ktor βασίζεται σε εξαιρέσεις. Η κλάση ClientRequestException εκτοξεύεται σε κωδικούς 4xx, ServerResponseException σε 5xx και IOException σε σφάλματα δικτύου. Τα χρονικά όρια διαμορφώνονται μέσω του πρόσθετου HttpTimeout, το οποίο ορίζει τον χρόνο αναμονής για σύνδεση, ανάγνωση και εγγραφή. Για επαναλήψεις χρησιμοποιείται το πρόσθετο Retry με ρυθμίσεις αριθμού προσπαθειών και καθυστέρησης.

Πώς λειτουργεί το Ktor;

Το Ktor χρησιμοποιεί αρχιτεκτονική αγωγού, όπου κάθε αίτημα περνά μέσα από μια αλυσίδα χειριστών. Ο πελάτης δημιουργεί μια διαμόρφωση HttpClient με εγκατεστημένα πρόσθετα, και κάθε κλήση μεθόδου get ή post περνά μέσα από τα πρόσθετα με τη σειρά σύνδεσής τους.

Αρχιτεκτονική HttpClient

Το αντικείμενο HttpClient δημιουργείται με μια μηχανή ειδική για την πλατφόρμα: CIO για JVM και Android, Darwin για iOS και macOS, OkHttp για συμβατότητα με Android, Js για πρόγραμμα περιήγησης. Η μηχανή μπορεί να επιλεγεί ρητά ή να αφεθεί στην αυτόματη επιλογή. Κάθε αίτημα επιστρέφει HttpResponse, το οποίο περιέχει το σώμα απόκρισης, τις κεφαλίδες και την κατάσταση.

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        json(Json {
            ignoreUnknownKeys = true
        })
    }
}

suspend fun fetchUsers(): List<User> {
    return client.get("https://api.example.com/users").body()
}

Εγκατάσταση και ρύθμιση του Ktor

Η εγκατάσταση του Ktor γίνεται μέσω Gradle ή Maven. Σε πολυπλατφορμικά έργα, οι εξαρτήσεις καθορίζονται στα sourceSets για κάθε στόχο. Το Ktor διανέμεται μέσω Maven Central.

Σύνδεση μέσω Gradle

Στο build.gradle.kts προσθέστε την εξάρτηση ktor-client-core για κοινόχρηστο κώδικα και τη μηχανή για τη συγκεκριμένη πλατφόρμα. Η έκδοση Ktor ορίζεται μέσω μιας μεταβλητής στο gradle.properties. Το Ktor 3.x απαιτεί Kotlin 2.0+ και υποστηρίζει τον μεταγλωττιστή K2.

val ktorVersion = "3.0.3"

dependencies {
    implementation("io.ktor:ktor-client-core:$ktorVersion")
    implementation("io.ktor:ktor-client-cio:$ktorVersion")
    implementation("io.ktor:ktor-client-content-negotiation:$ktorVersion")
    implementation("io.ktor:ktor-serialization-kotlinx-json:$ktorVersion")
    implementation("io.ktor:ktor-client-logging:$ktorVersion")
}

Ρύθμιση για iOS

Για iOS χρησιμοποιείται η μηχανή Darwin, η οποία περιβάλλει το εγγενές URLSession. Στο Kotlin Multiplatform, αυτό επιτρέπει τη μέγιστη απόδοση και ενσωμάτωση με τους μηχανισμούς προσωρινής αποθήκευσης του συστήματος iOS. Η μηχανή προστίθεται ως ξεχωριστή εξάρτηση στο sourceSet iOS.

Ένα σημαντικό χαρακτηριστικό του Ktor — υποστήριξη διαφορετικών μορφών σειριοποίησης μέσω ContentNegotiation. Εκτός από JSON, το πρόσθετο υποστηρίζει Protobuf, CBOR, XML και προσαρμοσμένες μορφές. Για σειριοποίηση χρησιμοποιούνται οι βιβλιοθήκες kotlinx.serialization ή Jackson, και ο προγραμματιστής μπορεί να εναλλάσσεται μεταξύ τους χωρίς να αλλάζει τον κώδικα αιτημάτων.

Παραδείγματα χρήσης του Ktor

Τα παραδείγματα παρακάτω δείχνουν τυπικά σενάρια εργασίας με τον πελάτη Ktor: βασικό αίτημα GET, αποστολή δεδομένων και εργασία με πολυπλατφορμικό κώδικα.

Αίτημα GET με αποσειριοποίηση JSON

Ένα απλό αίτημα GET με αυτόματη αποσειριοποίηση της απόκρισης σε κλάση δεδομένων. Το Ktor χρησιμοποιεί το πρόσθετο ContentNegotiation με kotlinx.serialization για τη μετατροπή JSON σε αντικείμενα. Ο κώδικας είναι συνοπτικός και ασφαλής ως προς τους τύπους.

@Serializable
data class Post(
    val id: Int,
    val title: String,
    val body: String
)

suspend fun getPosts(): List<Post> {
    val response = client.get("https://jsonplaceholder.typicode.com/posts")
    return response.body()
}

Αίτημα POST με σώμα JSON

Το αίτημα POST στο Ktor στέλνει μια κλάση δεδομένων ως σώμα JSON μέσω της μεθόδου post με contentType και setBody. Το πρόσθετο ContentNegotiation αυτόματα σειριοποιεί το αντικείμενο σε συμβολοσειρά JSON. Η απόκριση μπορεί να υποβληθεί σε επεξεργασία σύγχρονα ή ασύγχρονα.

suspend fun createPost(): Post {
    val newPost = Post(
        id = 0,
        title = "Νέα δημοσίευση",
        body = "Περιεχόμενο δημοσίευσης"
    )
    val response = client.post("https://jsonplaceholder.typicode.com/posts") {
        contentType(ContentType.Application.Json)
        setBody(newPost)
    }
    return response.body()
}

Μεταφόρτωση αρχείου μέσω Multipart

Η μέθοδος submitFormWithBinaryData στο Ktor επιτρέπει την αποστολή αρχείων και φορμών σε μορφή multipart. Το Ktor αυτόματα χωρίζει τα δεδομένα σε μέρη και προσθέτει κεφαλίδες. Για την παρακολούθηση της προόδου χρησιμοποιείται το onUpload, το οποίο λαμβάνει bytes των σταλμένων δεδομένων.

suspend fun uploadFile(fileBytes: ByteArray) {
    client.submitFormWithBinaryData(
        url = "https://api.example.com/upload",
        formData = formData {
            append("file", fileBytes, Headers.build {
                append(HttpHeaders.ContentType, "image/png")
                append(HttpHeaders.ContentDisposition, "filename=\"photo.png\"")
            })
        }
    )
}

Ktor ή Retrofit: τι να επιλέξω;

Η επιλογή μεταξύ Ktor και Retrofit εξαρτάται από την αρχιτεκτονική του έργου και τις απαιτήσεις πολυπλατφορμικότητας. Το Retrofit παραμένει το πρότυπο για έργα μόνο Android, ενώ το Ktor είναι η καλύτερη επιλογή για Kotlin Multiplatform.

Το Ktor παρέχει επίσης ενσωματωμένη υποστήριξη για WebSocket και SSE (Server-Sent Events), καθιστώντας το βολικό για εφαρμογές πραγματικού χρόνου. Το Retrofit δεν υποστηρίζει WebSocket άμεσα — για αυτό απαιτείται ξεχωριστή βιβλιοθήκη OkHttp WebSocket. Το Ktor επίσης διαμορφώνεται ευκολότερα για διαφορετικά περιβάλλοντα χάρη στο σύστημα πρόσθετων, όπου κάθε πρόσθετο είναι υπεύθυνο για μία λειτουργία.

Αυθεντικοποίηση στο Ktor

Το πρόσθετο Auth στο Ktor υποστηρίζει βασική αυθεντικοποίηση, Bearer tokens, Digest και OAuth2. Η διαμόρφωση αυθεντικοποίησης γίνεται δηλωτικά: ο προγραμματιστής καθορίζει τον πάροχο, την πηγή token και το πεδίο δράσης. Το Ktor προσθέτει αυτόματα κεφαλίδες αυθεντικοποίησης στα αιτήματα και μπορεί να ανανεώσει το token όταν λήξει.

Εάν το έργο χρησιμοποιεί Kotlin Multiplatform με κοινόχρηστο κώδικα σε iOS και Android, το Ktor είναι η μοναδική επιλογή που λειτουργεί και στις δύο πλατφόρμες χωρίς πρόσθετα στρώματα. Το Retrofit είναι αυστηρά δεσμευμένο στο OkHttp και το JVM, καθιστώντας το ακατάλληλο για iOS.

Για έργα μόνο Android, το Retrofit παρέχει πιο ώριμο API, περισσότερους μετατροπείς και OkHttp παρεμβολείς. Το Ktor λειτουργεί και σε αυτό το σενάριο, αλλά το οικοσύστημα πρόσθετων του είναι λιγότερο εκτεταμένο. Και οι δύο βιβλιοθήκες υποστηρίζουν coroutines και παρέχουν συγκρίσιμη απόδοση.