HttpKit — простой и быстрый HTTP-клиент

• Основан на Apache httpclient 4.3.x;
• Поддерживает многопоточные асинхронные запросы;
• Включает в себя пул соединений для запросов;
• Имеет унифицированные настройки параметров;
• Обладает API, спроектированным по принципу конвейера;
• Обеспечивает двустороннюю аутентификацию;
• Позволяет повторно считывать Response;
• Обрабатывает Response (записывает файлы, потоки, преобразует объекты Json, строки или байтовые массивы);
• Реализует загрузку и выгрузку файлов;
• Работает с перенаправленными путями и сетевыми прокси;
• Предлагает простое сохранение сеанса;
• Предоставляет простую аутентификацию;
• Использует простой механизм повторных попыток при сбоях;
• Даёт возможность настраивать пользовательские перехватчики;
• Все эти функции доступны через один вход в HttpKit, что делает его очень простым в использовании.

Первый шаг использования HttpKit

Первый шаг работы с HttpKit начинается с простого и приятного старта.

HttpKit.get(url); // Создаём GET-запрос.
HttpKit.post(url); // Создаём POST-запрос.
HttpKit.delete(url); // Создаём DELETE-запрос.
HttpKit.put(url);  // Создаём PUT-запрос.

Здесь HttpKit предоставляет статические методы для доступа к API. Нет необходимости создавать объект HttpKit с помощью new. Фактически, все операции запроса начинаются отсюда. В настоящее время HttpKit поддерживает четыре типа запросов: get, post, delete и put. Каждый тип запроса имеет четыре перегруженных метода.

Рассмотрим метод post в качестве примера:

RequestBase post(String url); // ①
RequestBase post(URI uri);    // ②
RequestBase post(String url, RequestBase request); //③
RequestBase post(URI uri, RequestBase request);   //④

— ① Использование строки URL для запроса. — ② Использование объекта URI для запроса. — ③ Использование строки URL и объекта RequestBase в качестве текущего запроса. — ④ Использование объекта URI и объекта RequestBase в качестве текущего запроса.

Примечание: Для текущего запроса переданные объекты RequestBase будут использоваться как данные инициализации для конфигурации RequestConfig.Builder, CookieStore и Header. Это позволяет элегантно сохранять сеанс и легко передавать его в последующие запросы. Этот подход особенно полезен для запросов, требующих предварительной авторизации. Кроме того, метод автоматически распознаёт HTTPS-запросы и обрабатывает одностороннюю аутентификацию. Для HTTPS-запросов с двусторонней аутентификацией необходимо самостоятельно настроить сертификаты, см. RequestBase.setJks.

Объект RequestBase

Метод HttpKit.post(url) возвращает объект RequestBase, который предоставляет параметры настройки, прокси, Cookie, Header, userAgent, ContentType, аутентификацию, одностороннюю и двустороннюю аутентификацию, загрузку файлов и механизмы повторных попыток в случае сбоев. Также он обеспечивает выполнение запросов.

Настройка параметров запроса

С помощью объекта RequestBase можно настроить параметры запроса. HttpKit использует множество перегрузок методов для минимизации сложности настройки параметров.

Существует три способа настройки параметров:

1. Использовать addParameter для добавления параметров в список.
2. Использовать setParameters для установки параметров, при этом все ранее установленные параметры, включая добавленные, будут очищены. Поэтому следует выбирать подходящий способ в зависимости от ситуации.
3. Использовать useForm для настройки параметров, этот метод игнорирует ранее установленные или добавленные параметры и использует метод отправки данных, имитирующий форму. Таким образом, этот метод подходит для загрузки файлов через браузер.

Перегрузка методов настройки параметров

Перегрузка методов добавления параметров

Пример:

HttpKit.post("https://0oky.com").addParameter("name", "value");

Примечание: Значение параметра может быть любым объектом, и при настройке параметров будет вызван метод toString() этого объекта.

Загрузка файлов

FormPart form = FormPart.create("name", "value");
form.addParameter("fieldName", new File("test.txt"));
HttpKit.post("https://0oky.com").useForm(form);

FormPart используется только для настройки параметров формы и кодирования. Процесс настройки параметров является цепочечным. Например:

FormPart form = FormPart.create() .addParameter("name", "value") .addParameter("fieldName", new File("test.txt")) .addParameter("name2", "testString".getBytes());

### Работа с Cookie

> Используйте метод RequestBase.addCookie для установки нескольких Cookie, так как это вариативный параметр, можно передать любое количество объектов Cookie.
> Кроме того, API предоставляет методы setCookieStore и getCookieStore для получения, установки, удаления и истечения срока действия Cookie.

```java
HttpKit.post("https://0oky.com").addCookie(new BasicClientCookie("name", "value"));
HttpKit.post("https://0oky.com").addCookie(new BasicClientCookie("name", "value"), new BasicClientCookie("name2", "value2"));

Работа с заголовками

Методы RequestBase могут использоваться для управления заголовками.

HttpKit.post("https://0oky.com").setProxy("192.168.10.10", 1182);

Установка механизма повторных попыток при сбое

Можно настроить механизм повторных попыток с помощью метода RequestBase.setRetryTimes.

О двусторонней аутентификации HTTPS

Для настройки сертификата двусторонней аутентификации используйте метод RequestBase.setJKS.

Об аутентификации

Установите схему аутентификации с помощью метода setCredentials объекта RequestBase. В настоящее время доступны следующие схемы аутентификации:

• Basic: базовая схема аутентификации, описанная в RFC2617. Эта схема небезопасна, поскольку информация об учётных данных передаётся в открытом виде.
• Digest: схема дайджест-аутентификации, также описанная в RFC2617. Считается более безопасной, чем базовая схема.
• NTLM: схема аутентификации NTLM, разработанная Microsoft и оптимизированная для платформы Windows. Считается более надёжной, чем схема Digest.
• SPNEGO/Kerberos: SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) — это «псевдомеханизм» GSSAPI, используемый для согласования реального механизма аутентификации. SPNEGO наиболее часто используется в схемах аутентификации HTTP, разработанных Microsoft. Возможные механизмы аутентификации включают NTLM и Kerberos. Если обе стороны не знают, какой протокол может использовать другая сторона, можно использовать SPNEGO. В настоящее время HttpCLient поддерживает только механизм Kerberos. Методы перегрузки схемы аутентификации

Существует перегрузка метода схемы аутентификации.

Выполнение запроса

Только методы RequestBase.execute и RequestBase.executeCallback являются истинным выполнением запроса. Разница между методами execute и executeCallback заключается в том, что первый использует только предоставленный пул соединений для управления HttpClient и является одиночным запросом, а второй добавляет асинхронный многопоточный запрос на основе первого. Возвращаемые значения различаются: метод execute возвращает объект ResponseWrap, а метод executeCallback — объект RequestFuture. ResponseHandler может быть настроен для возврата желаемого типа значения.

Методы перегрузки объекта следующие:

Пример:

HttpKit.get("https://0oky.com").execute().getString();

// Многопоточный запрос
List<RequestFuture<String>> taskWraps = new ArrayList<>();
RequestFuture<String> task;
RequestBase request = null;

for (int i = 0; i < 1000; i++) {
    request = HttpKit.get("https://0oky.com");
    task = request.executeCallback(executorService, new MyResponseHandler());
    taskWraps.add(task);
}

for (RequestFuture<String> taskWrap : taskWraps) {
    taskWrap.get(); // Синхронное получение результата запроса
}

Объект ResponseWrap

Метод RequestBase.execute вернёт этот объект. Этот объект содержит обработку результатов ответа и проверку того, был ли адрес перенаправлен. Результаты обработки используют объект BufferedHttpEntity для кэширования, поэтому результаты ответа можно повторно считывать. (По умолчанию httpClient не поддерживает повторное чтение, при повторном чтении будет выдана ошибка.) Основные методы обработки результатов включают getByteArray(), getBufferedReader(), getString(), transferTo(), getJson() и getJsonList().