Как работают аннотации в Retrofit

Как работают аннотации в Retrofit

Аннотации в Retrofit — это основа для декларативного описания сетевых запросов. Они позволяют преобразовать методы Java/Kotlin-интерфейса в HTTP-вызовы, абстрагируя разработчика от рутинной работы с HttpURLConnection или OkHttpClient. Retrofit использует аннотации времени компиляции и рефлексию (или динамические прокси в рантайме) для генерации реализаций этих методов.

Основные типы аннотаций и их роль

1. Аннотации HTTP-методов:

   • @GET, @POST, @PUT, @DELETE, @PATCH — определяют тип HTTP-запроса. В параметре указывается относительный или абсолютный URL эндпоинта.

   @GET("users/{id}")
   suspend fun getUser(@Path("id") userId: Long): User
   

2. Аннотации параметров:

   • @Path — подставляет значение в placeholder {id} в URL.
   • @Query — добавляет query-параметр, например ?sort=desc.
   • @Body — отправляет объект как тело запроса в формате JSON (если используется конвертер, например Gson).
   • @Field / @FieldMap — для form-encoded данных (требует @FormUrlEncoded).
   • @Header — добавляет или переопределяет заголовок запроса.

3. Аннотации модификаторов запроса:

   • @Headers — статические заголовки для метода.
   • @Multipart / @Part — для загрузки файлов.
   • @FormUrlEncoded — для отправки данных формы.

Как Retrofit обрабатывает аннотации

Процесс можно разделить на три этапа:

1. Определение метода при создании Retrofit-экземпляра: При вызове Retrofit.create() создается динамический прокси-объект, который перехватывает вызовы методов интерфейса. Retrofit анализирует аннотации метода и строит ServiceMethod — внутреннее представление запроса.

2. Парсинг аннотаций: Для каждой аннотации Retrofit использует ParameterHandler — классы, которые знают, как обработать конкретный тип параметра. Например:

• ParameterHandler.Path — заменяет {id} в URL.
• ParameterHandler.Query — добавляет параметр в строку запроса.
• ParameterHandler.Body — передает объект в конвертер для сериализации.

3. Выполнение запроса: При вызове метода прокси создает OkHttpCall, который:

• Динамически строит HTTP-запрос на основе ServiceMethod.
• Использует OkHttpClient для отправки запроса.
• Передает ответ в Converter для десериализации в указанный тип (например, User).

Пример комплексного использования

interface ApiService {
    @Headers("Cache-Control: max-age=3600")
    @GET("search/repositories")
    suspend fun searchRepos(
        @Query("q") query: String,
        @Query("page") page: Int,
        @Query("sort") sort: String = "stars"
    ): RepoResponse

    @Multipart
    @POST("upload")
    suspend fun uploadFile(
        @Part("description") description: RequestBody,
        @Part file: MultipartBody.Part
    ): UploadResult
}

Ключевые аспекты реализации

• Конвертеры (например, Gson, Moshi) работают в паре с аннотациями @Body и типом возвращаемого значения, автоматически сериализуя/десериализуя данные.
• Адаптеры (например, для RxJava, Coroutines) преобразуют вызов метода в нужный формат (например, suspend-функцию).
• Кастомные аннотации можно создать через @Qualifier и обрабатывать с помощью собственных ParameterHandler.

Преимущества подхода

• Декларативность: логика запроса описывается аннотациями, а не кодом.
• Безопасность типов: ошибки в URL или параметрах часто обнаруживаются на этапе компиляции.
• Тестируемость: интерфейсы легко мокать в unit-тестах.
• Гибкость: благодаря цепочке вызовов OkHttp и конвертерам можно кастомизировать любую часть процесса.

Таким образом, аннотации в Retrofit служат DSL (Domain Specific Language) для описания HTTP-запросов, превращая рутинную работу с сетью в простой и надежный процесс. Это достигается за счет комбинации кодогенерации (через обработку аннотаций) и использования мощного HTTP-клиента OkHttp под капотом.