Eliminate BaseResponse Wrapper in Retrofit Using a Custom Converter.Factory

When backend APIs return a uniform wrapper such as BaseResponse (containing fields like code , data , message ), developers often have to write repetitive code to unwrap the data field in every Retrofit service method.

This article proposes an elegant solution that removes the need for a BaseResponse type by creating a custom Converter.Factory (named ConvexConverterFactory ) which intercepts the method annotations, applies a user‑defined ConvexTransformer , and forwards the transformed InputStream to the regular Gson converter.

The key steps are:

Define a ConvexTransformer interface that converts the original response stream into a stream containing only the business data .

Create a @Transformer annotation that references a concrete ConvexTransformer class and apply it to Retrofit service methods.

Implement ConvexConverterFactory and ConvexConverter that detect the annotation, obtain the appropriate transformer, and delegate the final conversion to the next factory (e.g., GsonConverterFactory ).

Register ConvexConverterFactory as the first converter in the Retrofit.Builder .

Example code snippets:

public interface UserService {
    @GET("/users")
    @Transformer(TestConvexTransformer::class)
    suspend fun getAllUsers(): List
}

class ConvexConverterFactory : Converter.Factory() {
    override fun responseBodyConverter(
        type: Type,
        annotations: Array
,
        retrofit: Retrofit
    ): Converter
? {
        return annotations.filterIsInstance
()
            .firstOrNull()?.value?.let { transformerClazz ->
                retrofit.nextResponseBodyConverter
(this, type, annotations)
                    ?.let { converter -> ConvexConverter(transformerClazz, converter) }
            }
    }
}

interface ConvexTransformer {
    @Throws(IOException::class)
    fun transform(original: InputStream): InputStream
}

Finally, the article shows a complete usage scenario with the public WanAndroid API, demonstrating how to define a WanAndroidConvexTransformer , a service interface, and how to invoke the API inside a coroutine.

The approach centralises the unwrapping logic, supports multiple response formats, and leverages Retrofit’s extensibility via the annotations parameter of Converter.Factory .