Пример использования Retrofit 2 в приложениях Android

Привет! В этой статье мы будем разбираться как работать с библиотекой Retrofit, которая призвана значительно сократить трудозатраты при работе с API веб-сервисов, а также напишем простой пример использования Retrofit 2 в тестовом приложении.


1.Retrofit. Что это?

Retrofit – это REST клиент для android и Java от компании Square. Он может относительно легко получать и разбирать JSON (или другие структуированные данные) через вебсервисы, использующие REST. В Retrofit для (де)сериализации данных используются конверторы, которые необходимо указывать вручную. Типичным  конвертором для JSON формата является библиотека GSon, но вы можете воспользоваться кастомным конвертером для обработки XML или прочих протоколов. Для HTTP запросов Retrofit использует OkHttp библиотеку.

Вы можете создать Java объекты основанные на JSON через сервис по ссылке http://www.jsonschema2pojo.org/

Для работы с Retrofit нам потребуется выполнить три шага:

1)Создать класс модели, который будет перегоняться в JSON

2)Создать интерфейс, определяющий возможные HTTP Операции (API)

3)Настроить Retrofit с помощью Retrofit.Builder класса.

Сейчас наверняка вам ничего не понятно, но далее на примерах всё встанет на свои места.

Каждый метод из интерфейса (созданного на шаге 2) представляет одну реализацию вызова API вебсервиса. Метод должен иметь HTTP аннотацию(GET, POST, и т.д.) для указания типа запроса и URL адрес. Возвращаемое значение оборачивается в ответе в Call объект, параметризованный типом ожидаемого результата(нашей моделью из 1 шага).

 

Вы можете менять части и параметры URL для настройки запроса. Замена части URL выполняется с помощью фигурных скобок {} . С помощью аннотации @Path мы связываем значение параметра метода со значtнием из скобок {} в аннотации.

Для того что бы выполнить запрос с параметрами их необходимо добавить с аннотацией @Query в сигнатуру метода, в результате чего при вызове они добавятся в конец URL

Аннотация @Body на параметре метода заставит Retrofit использовать объект как тело запроса.

 


2.Retrofit конверторы и адаптеры.

2.1 Конверторы.

Retrofit может быть настроен с использованием специфичных конверторов. Задача конверторов – выполнить (де)сериализацию объектов. Некоторые конверторы для различных преобразований данных:

Для преобразования в JSON и обратно:

  • Gson: com.squareup.retrofit:converter-gson
  • Jackson: com.squareup.retrofit:converter-jackson
  • Moshi: com.squareup.retrofit:converter-moshi

Для работы с протоколами сереализации (Protocol Buffers):

  • Protobuf: com.squareup.retrofit:converter-protobuf
  • Wire: com.squareup.retrofit:converter-wire

Ну и для работы с XML (куда же без него…):

Simple XML: com.squareup.retrofit:converter-simplexml

Ну а если вам захотелось каких то особых извращений или пришлось работать с неким специфичным протоколом – всегда можно создать собственный конвертор, унаследовавшись от класса Converter.Factory

 

2.2 Retrofit адаптеры

Ретрофит можно расширить адаптерами для связи с такими библиотеками как RxJava 2.x, Java 8 и Guava.

С выбором адаптеров можете ознакомиться на Гитхабе square/retrofit/retrofit-adapters/

Для примера RxJava 2.x адаптер может быть добавлен с помощью Gradle:

Или используя Maven

Добавление адаптера в коде выглядит примерно таким методом

Точнее :

С этим адаптером будут добавлены Retrofit интерфейсы, способные возвращать RxJava 2.x типы, например Observable, Flowable или Single и т.д.


  1. Аутентификация в Retrofit

Аутентификация может производиться как используя логин с паролем(Http Basic authentication), так и с применением токенов.

Существует 2 пути для обработки процедуры аутентификации. Первый – использование заголовков с помощью аннотаций. Второй – использование интерцепторов OkHttp. Посмотрим как с этим работать.

3.1 Аутентификация с помощью аннотаций.

Предположим, что вам необходимо получить данные пользователя, для доступа к которым требуется аутентификация. Вы можете сделать это, добавив новые параметры в ваш API интерфейс, например как в коде ниже:

С помощью аннотации @Header(«Authorization») мы просим Retrofit добавить поле Authorization в заголовок запроса со значением, предоставленным в параметре credentials.

Для создания данных пользователя(credentials) мы можем использовать класс Credentials из библиотеки OkHttp, а именно его метод basic(String, String). Как видно из сигнатуры, этот метод получает логин с паролем и возвращает данные для проверки подлинности

Если вы хотите использовать токен, просто вызовите метод getUserDetails(String)

3.2 Аутенфитикация с OkHttp интерцепторами.

Если у вас много вызовов, использующих аутентификацию, то стоит задуматься о использовании интерцепторов. Интерцептор используется для модификации каждого запроса перед его использованием и меняет его заголовок. Преимущество тут заключается в том, что вам не приходится добавлять аннотации  @Header(«Authorization») в каждый вызов методов API.

Что бы добавить интерцептор, вы должны выполнить метод okhttp3.OkHttpClient.Builder.addInterceptor(Interceptor):

Созданный okHttpClient должен быть добавлен как ваш Retrofit клиент в методе retrofit2.Retrofit.Builder.client(OkHttpClient)

Как и в примере с аутенфификацией с помощью аннотаций, вы можете пользоваться токеном везде, где используется класс Credentials


А теперь давайте создадим на android приложение, которое будет выгребать с сайта umori.li анекдоты с помощью Retrofit. Пример будет довольно примитивный и несет в себе лишь цель понять, как необходимо взаимодействовать с основными частями библиотеки.

Итак, помните я в начале упоминал про 3 сущности? Давайте поочередно их создавать. Первая — класс-модель. Воспользуемся сервисом http://www.jsonschema2pojo.org/ для получения класса AnekdotModel. Для этого идём по адресу  http://www.umori.li/api, знакомимся с API, делаем запрос http://www.umori.li/api/get?site=anekdot.ru&name=new+anekdot&num=1 , и вставляем результат ответа уже в наш чудо-сервис. Выбираем JSON, стиль аннотаций Gson, включение сеттеров и геттеров. В результате получаем класс-модель, отражающий данные, которые будут приходить по сети.

С первым разобрались. Перед созданием второй сущности – интерфейса с описанием будущего API, давайте подключим библиотеку Retrofit в наше приложение. Для этого в Gradle необходимо добавить

Есть так же способы подключения библиотеки с помощью Maven или добавления Jar файла, с ними можете ознакомиться на сайте разработчиков библиотеки.

Приступим к созданию интерфейса с API. Он будет состоять из метода получения портянки с анекдотами.

Взглянув на аннотации, мы видим что будет использоваться метод GET, который к базовому URL добавит /api/get?name=”первый параметр”&num=”второй параметр”.

Третья сущность – класс, в котором будем инициализировать Retrofit. Назовем его Controller. Дёргая его за метод getApi мы получаем готовый экземпляр реализации нашего API, который описывали на втором шаге.

Теперь нам осталось собрать все части в единое целое. Получаемыми данными в активности будем наполнять RecyclerView,  часть Gradle с нужыми библиотеками в результате выглядит так

Также не забываем добавить в файл манифеста разрешения на прогулки по интернету.

Создаем файлы разметки для активити и элемента списка RecyclerView:

activity_main.xml

post_item.xml

Для работы с RecyclerView пишем адаптер. Надеюсь написание всех побочных вещей не вызывает у вас вопросов. Но если вы впервые видите RecyclerView, то можете прочитать о принципах работы с ней тут.

Ну и сам класс MainActivity, где вся магия обретает жизнь:

Закомментирован участок где демонстрируется синхронный вариант вызова. Но вы же знаете, что в главном потоке не кошерно вызывать методы, которые могут подвесить UI, так что пользуйтесь им в бэкграунде по необходимости.



Подведя итог можно выделить следующие фазы написания приложения:

А) Подготовительная. Добавление зависимостей в Gradle, разрешений на работу сетью.

Б) Создание модели данных, так называемого POJO объекта(англ. Plain Old Java Object — «старый добрый Java-объект»). Выполняем запрос к ресурсу, ответ вставляем в один из сервисов(например http://www.jsonschema2pojo.org/) и забираем готовую модель. Можете и вручную описать класс, это уже на ваше усмотрение.

В) Реализация инициализации retrofit’а. Тут вы сами вольны принять архитектурныое решение и разместить инициализацию где вашей душе угодно.  Можете сделать это в отдельном контроллере, как в коде выше, в централизованном месте(например в классе App, кунаследовавшись от Application), или же выполнить реализацию в активити, непосредственно перед использованием библиотеки.

Г) Вызов методов API из реализации модели, которую построит при инициализации Retrofit.Builder и обработка результатов их работы. Размещение данных для показа пользователю, запись в базу данных, построение графика и т.д.

Согласитесь, Retrofit отлично справляется с задачей сокрытия низкоуровневых вызовов, оставляя нам методы API и обработку их обратных вызовов. Надеюсь, что вы сможете избежать массы костылей при работе с сетью, используя эту чудесную библиотеку!

P.s. код на гитхабе


Комментарии:

Пример использования Retrofit 2 в приложениях Android: 10 комментариев

  1. У меня получается следующая ошибка:
    После запроса к серверу — уходит в OnFailure с ошибкой:
    OnFailure: java.lang.IllegalStateException: Expected BEGIN_ARRAY but was STRING at line 1 column 1 path $

    Подскажите, пожалуйста, в чем может быть проблема?
    Заранее спасибо за ответ.

    1. Добрый день. Скажите, пожалуйста, вы решили проблему с этой ошибкой? просто у меня та же ошибка и не могу найти решение. Спасибо.

      1. В общем я разобрался почему такую ошибку выдает, по такому адресу сервер возвращает «This page requires that your browser supports frames.»

        Нужно в BASE_URL вместо «www.umori.li» поставить
        «umorili.herokuapp.com»

        1. Мне такую ошибку не выводило, а просто выводило ответный json, который на сколько я понял, не совсем корректный. Но внешне они идентичны. Понял это по тому, как парсит этот json встроенный в хром плагин. Так вот, с сайта umiori.li он не парсился, в то время как с umorili.herokuapp.com все хорошо парсится и код работает. Непонятно =)

      1. Спасибо за замечательный туториал, но возникла одна проблемка. Я новичок в ретрофите и вообще в роботе с веб — сервисами и джсоном. У меня возникло исключение- IllegalStateException: Expected BEGIN_ARRAY but was STRING at line 1 column 1 path $. Подскажите, пожалуйста, что с этим поделать.

  2. А как, это, собственно, исправить? я прост новичок в ретрофите, можете подсказать как решить подобную проблему?

Добавить комментарий

Ваш e-mail не будет опубликован. Обязательные поля помечены *