Путеводитель по Google-Http-клиент

1. Обзор

В этой статье мы посмотрим на Библиотека клиентов Google HTTP для Java , которая является быстрой, хорошо абстрактной библиотекой для доступа к любым ресурсам через протокол подключения HTTP.

Основными особенностями клиента являются:

слой абстракции HTTP, который позволяет отделить любую библиотеку низкого уровня
быстрый, эффективный и гибкий JSON и XML, анализ моделей отклика и содержания запросов HTTP
просты в использовании аннотации и абстракции для отображения ресурсов HTTP

Библиотека также может быть использована в Java 5 и выше, что делает ее значительным выбором для устаревших (SE и EE ) проектов.

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

2. Мейвен зависимостей

Чтобы воспользоваться библиотекой, нам понадобится Google-http-клиент зависимость:


    com.google.http-client
    google-http-client
    1.23.0

Последнюю версию можно найти на Мавен Центральный .

3. Создание простого запроса

Давайте начнем с простого запроса GET на страницу GitHub, чтобы продемонстрировать, как Google Http Клиент работает из коробки:

HttpRequestFactory requestFactory
  = new NetHttpTransport().createRequestFactory();
HttpRequest request = requestFactory.buildGetRequest(
  new GenericUrl("https://github.com"));
String rawResponse = request.execute().parseAsString()

Чтобы сделать простейший запрос, нам нужно, по крайней мере:

HttpRequestFactory это используется для создания наших запросов
HttpTransport абстракция низкоуровневого транспортного слоя HTTP
ОбщиеУрль класс, который обертывает Url
HttpRequest обрабатывает фактическое выполнение запроса

Мы пройдемся по всем этим и более сложным примерам с фактическим API, который возвращает формат JSON в следующих разделах.

4. Подключенный транспорт HTTP

Библиотека имеет хорошо абстрагированную HttpTransport класс, который позволяет нам строить на нем и изменение базовой низкоуровневой транспортной библиотеки HTTP по выбору :

public class GitHubExample {
    static HttpTransport HTTP_TRANSPORT = new NetHttpTransport();
}

В этом примере мы используем NetHttpТранспорт , который основан на HttpURLConnection который находится во всех Java SDKs. Это хороший стартовый выбор, так как он хорошо известен и надежен.

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

Для такого рода случаев, есть ApacheHttpТранспорт:

public class GitHubExample {
    static HttpTransport HTTP_TRANSPORT = new ApacheHttpTransport();
}

ApacheHttpТранспорт основана на популярном Apache HttpClient который включает в себя широкий выбор вариантов для настройки соединений.

Кроме того, библиотека предоставляет возможность создания низкоуровневой реализации, что делает ее очень гибкой.

5. JSON Разбор

Клиент Google Http включает в себя еще одну абстракцию для разбора JSON. Основным преимуществом этого является то, что выбор библиотеки низкоуровневой разбора является взаимозаменяемым .

Есть три встроенных варианта, все из которых распространяются на JsonFactory, и она также включает в себя возможность осуществления наших собственных.

5.1. Библиотека взаимозаменяемого разбора

В нашем примере мы собираемся использовать реализацию Jackson2, которая требует Google-http-клиент-jackson2 зависимость:


    com.google.http-client
    google-http-client-jackson2
    1.23.0

После этого, теперь мы можем включить JsonFactory:

public class GitHubExample {

    static HttpTransport HTTP_TRANSPORT = new NetHttpTransport();
    staticJsonFactory JSON_FACTORY = new JacksonFactory();
}

тем ДжексонФактория является самой быстрой и популярной библиотекой для операций разбора/сериализации.

Это происходит за счет размера библиотеки (что может быть проблемой в определенных ситуациях). По этой причине, Google также предоставляет GsonFactory , которая является осуществлением библиотеки Google GSON, легкий JSON разбор библиотеки.

Существует также возможность написания нашей низкоуровневой реализации парсера.

5.2. @Key Аннотация

Мы можем использовать @Key аннотация для обозначения полей, которые должны быть разобрано или сериализованы для JSON:

public class User {
 
    @Key
    private String login;
    @Key
    private long id;
    @Key("email")
    private String email;

    // standard getters and setters
}

Здесь мы делаем Пользователь абстракция, которую мы получаем в пакете от GitHub API (мы доберемся до фактического разбора позже в этой статье) .

Обратите внимание, что поля, которые не имеют @Key аннотация считается внутренней и не анализируется и не сериализируется на JSON . Кроме того, видимость полей не имеет значения, равно как и существование методов getter или сеттера.

Мы можем указать стоимость @Key аннотация, чтобы сопоставить его с правильным ключом JSON.

5.3. ДженерикДжсон

Только поля мы объявляем, и пометить, как @Key разобрались.

Чтобы сохранить другой контент, мы можем объявить наш класс, чтобы расширить ДженерикДжсон:

public class User extends GenericJson {
    //...
}

ДженерикДжсон реализует карта интерфейс, что означает, что мы можем использовать методы get and put для настройки/получить содержимое JSON в запросе/ответе.

6. Вызов

Чтобы подключиться к конечной точке с клиентом Google Http, нам понадобится HttpRequestFactory , который будет настроен с нашими предыдущими абстракциями HttpTransport и JsonFactory:

public class GitHubExample {

    static HttpTransport HTTP_TRANSPORT = new NetHttpTransport();
    static JsonFactory JSON_FACTORY = new JacksonFactory();

    private static void run() throws Exception {
        HttpRequestFactory requestFactory 
          = HTTP_TRANSPORT.createRequestFactory(
            (HttpRequest request) -> {
              request.setParser(new JsonObjectParser(JSON_FACTORY));
          });
    }
}

Следующее, что нам понадобится, это URL для подключения. Библиотека обрабатывает это как класс, расширяющий ОбщиеУрль на котором любое объявленное поле рассматривается как параметр запроса:

public class GitHubUrl extends GenericUrl {

    public GitHubUrl(String encodedUrl) {
        super(encodedUrl);
    }

    @Key
    public int per_page;
 
}

Здесь, в нашем GitHubUrl, мы объявляем per_page свойство указывать, сколько пользователей мы хотим в одном вызове API GitHub.

Давайте продолжим строить наш звонок, используя GitHubUrl:

private static void run() throws Exception {
    HttpRequestFactory requestFactory
      = HTTP_TRANSPORT.createRequestFactory(
        (HttpRequest request) -> {
          request.setParser(new JsonObjectParser(JSON_FACTORY));
        });
    GitHubUrl url = new GitHubUrl("https://api.github.com/users");
    url.per_page = 10;
    HttpRequest request = requestFactory.buildGetRequest(url);
    Type type = new TypeToken>() {}.getType();
    List users = (List)request
      .execute()
      .parseAs(type);
}

Обратите внимание, как мы указать, сколько пользователей нам нужно для вызова API, а затем мы строим запрос с HttpRequestFactory .

После этого, поскольку ответ GitHub API содержит список пользователей, мы должны предоставить сложный Тип , который является Список .

Затем, на последней строке, мы делаем звонок и разобрать ответ на список наших Пользователь класс.

7. Пользовательские заготовки

Одна вещь, которую мы обычно делаем при запросе API, заключается в том, чтобы включить какой-то пользовательский заголовок или даже измененный:

HttpHeaders headers = request.getHeaders();
headers.setUserAgent("Baeldung Client");
headers.set("Time-Zone", "Europe/Amsterdam");

Мы делаем это, получая HttpHeaders после того, как мы создали наш запрос, но перед его выполнением и добавлением необходимых значений.

Пожалуйста, имейте в виду, что Google Http включает в себя некоторые заготовки в качестве специальных методов. Пользователь-агент заголовок, например, если мы попытаемся включить его только с набором метод он будет бросать ошибку.

8. Экспоненциальный бэкофф

Еще одной важной особенностью клиента Google Http является возможность повторной попытки запросов на основе определенных кодов статуса и пороговых значений.

Мы можем включить наши экспоненциальные настройки бэк-оффа сразу после создания объекта запроса:

ExponentialBackOff backoff = new ExponentialBackOff.Builder()
  .setInitialIntervalMillis(500)
  .setMaxElapsedTimeMillis(900000)
  .setMaxIntervalMillis(6000)
  .setMultiplier(1.5)
  .setRandomizationFactor(0.5)
  .build();
request.setUnsuccessfulResponseHandler(
  new HttpBackOffUnsuccessfulResponseHandler(backoff));

Экспоненциальный Backoff выключен по умолчанию в HttpRequest , поэтому мы должны включить пример HttpUnsuccessfulРеспонсЭндлер в HttpRequest активировать его.

9. Лесозаготовка

Клиент Google Http использует java.util.logging.Logger для регистрации http запросов и деталей ответа, включая URL, заголовники и содержимое.

Обычно журнал управляется с помощью logging.properts файл:

handlers = java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.level = ALL
com.google.api.client.http.level = ALL

В нашем примере мы используем КонсольХэндлер , но это также можно выбрать ФайлХэндлер .

Файл свойств настраивает работу лесозаготовительного центра JDK. Этот файл config может быть указан как свойство системы:

-Djava.util.logging.config.file=logging.properties

Таким образом, после настройки свойства файла и системы библиотека создат журнал, похожий на следующий:

-------------- REQUEST  --------------
GET https://api.github.com/users?page=1&per_page=10
Accept-Encoding: gzip
User-Agent: Google-HTTP-Java-Client/1.23.0 (gzip)

Nov 12, 2017 6:43:15 PM com.google.api.client.http.HttpRequest execute
curl -v --compressed -H 'Accept-Encoding: gzip' -H 'User-Agent: Google-HTTP-Java-Client/1.23.0 (gzip)' -- 'https://api.github.com/users?page=1&per_page=10'
Nov 12, 2017 6:43:16 PM com.google.api.client.http.HttpResponse 
-------------- RESPONSE --------------
HTTP/1.1 200 OK
Status: 200 OK
Transfer-Encoding: chunked
Server: GitHub.com
Access-Control-Allow-Origin: *
...
Link: ; rel="next", ; rel="first"
X-GitHub-Request-Id: 8D6A:1B54F:3377D97:3E37B36:5A08DC93
Content-Type: application/json; charset=utf-8
...

10. Заключение

В этом учебнике мы показали библиотеку клиентов Google HTTP для Java и ее более полезные функции. Их Гитхуб содержит более подробную информацию о нем, а также исходный код библиотеки.

Как всегда, полный исходный код этого учебника доступен более на GitHub .