repository·master·Indexed 24 days ago
https://github.com/foso/ktorfitA Kotlin Multiplatform HTTP client library that uses KSP to generate type-safe implementations of API interfaces, similar to Retrofit. It supports Android, iOS, JS, JVM, and Linux, utilizing Ktor clients and a compiler plugin to automate the instantiation of API implementation classes.
The Ktorfit repository is organized into several modules. Understanding these helps in locating specific parts of the library or finding examples:
compiler plugin: Source code for the compiler plugin.ktorfit-annotations: Module containing the annotations used by Ktorfit.ktorfit-ksp: Source code for the KSP (Kotlin Symbol Processing) plugin.ktorfit-lib-core: Core logic for the Ktorfit library.ktorfit-lib: Combines ktorfit-lib-core with dependencies on platform-specific clients.sandbox: Experimental module for testing new features.example: Contains sample projects demonstrating how to use Ktorfit.docs: Source files for the GitHub documentation page.There are two ways to send multipart data in Ktorfit:
Pass a parameter of type MultiPartFormDataContent annotated with @Body. You can construct this using Ktor's formData builder.
Annotate the function with @Multipart. Individual parts are defined using the @Part annotation. All @Part parameters are combined into a single MultiPartFormDataContent request.
// Option 1: @Body
interface ExampleService {
@POST("upload")
suspend fun upload(@Body map: MultiPartFormDataContent)
}
// Option 2: @MultiPart
@Multipart
@POST("upload")
suspend fun uploadFile(@Part("description") description: String, @Part("") file: List<PartData>): StringKtorfit operates using three main components that work together during the build process to turn annotated interfaces into functional API clients:
@GET) and generates the implementation classes.create() function to inject the generated implementation.When you define an interface like ExampleApi, KSP generates a class named _ExampleApiImpl in the same package. It also generates a ClassProvider and an extension function createExampleApi() to facilitate instantiation.
package com.example
import com.example.model.People
import de.jensklingenberg.ktorfit.http.GET
interface ExampleApi {
@GET("/test")
suspend fun exampleGet(): People
}create function from Ktorfit-lib and automatically injects the generated implementation class as an argument. The plugin uses the type parameter provided to the create function to deduce the correct implementation class name (e.g., if you pass ExampleApi, it looks for _ExampleApiImpl).Ktorfit uses a compiler plugin to automate the instantiation of API implementations. When you call the generic create<T>() function, the compiler plugin intercepts this call and replaces it with a call that provides the specific generated implementation class as an argument.
Original Code:
val api = jvmKtorfit.create<ExampleApi>()Transformed Code (at compile time):
val api = jvmKtorfit.create<ExampleApi>(_ExampleApiImpl(jvmKtorfit))If the compiler plugin is not correctly applied (e.g., the Gradle plugin is missing), the create() function will throw an IllegalArgumentException with the message ENABLE_GRADLE_PLUGIN because it expects the default null value to be replaced by the plugin.
public fun <T> create(data: T? = null): T {
if (data == null) {
throw IllegalArgumentException(ENABLE_GRADLE_PLUGIN)
}
return data
}Converters are used to transform HTTP responses or request parameters. To use a converter, you must wrap it in a Converter.Factory and register that factory with the Ktorfit builder using the converterfactories() function.
There are three main types of converters:
suspend functions.Ktorfit is designed to provide a developer experience similar to Retrofit for Kotlin Multiplatform (KMP) projects.
Key architectural decisions include:
When using @NoDelegation, the Ktorfit compiler plugin changes how the implementation class is structured.
For a regular interface (without the annotation), Ktorfit generates a delegation clause (e.g., by _SuperTestService1Impl(_ktorfit)). For an interface marked with @NoDelegation, this delegation clause is omitted for that specific interface in the generated class.
// Example of what is generated for TestService:
public class _TestServiceImpl(
private val _ktorfit: Ktorfit,
) : TestService, SuperTestService1 by com.example.api._SuperTestService1Impl(_ktorfit) {
// No delegation for SuperTestService2 because it was marked @NoDelegation
}ResponseConverter only when you cannot use a suspend function in your interface. Because Ktor relies on Coroutines by default, Ktorfit functions typically require the suspend modifier. For most standard use cases, you should use SuspendResponseConverter instead of a ResponseConverter.When implementing custom converters, the SuspendResponseConverter interface has been renamed to Converter.SuspendResponseConverter.
If you are implementing a Converter.Factory, you should now use the suspendResponseConverter method to return an instance of Converter.SuspendResponseConverter.
public class CallConverterFactory : Converter.Factory {
override fun suspendResponseConverter(
typeData: TypeData,
ktorfit: Ktorfit
): Converter.SuspendResponseConverter<HttpResponse, *>? {
// implementation
}
}Call? as a return type in your API interfaces, you must explicitly add the ktorfit-converters-call dependency and register the CallConverterFactory in your Ktorfit instance.