Java HttpClient: современные HTTP-запросы

java.net.http.HttpClient, стандартизированный в Java 11, является современным HTTP API и предпочтительным выбором для нового кода. Он заменяет многословный HttpURLConnection неизменяемым дизайном на основе строителя: HTTP/2 по умолчанию, нативные синхронные и асинхронные вызовы, а также подключаемая обработка тел запросов и ответов. Три типа выполняют основную работу — HttpClient, HttpRequest и HttpResponse.

В этой главе рассматривается создание и повторное использование клиента, построение запросов с телами и заголовками, синхронный и асинхронный режимы отправки, то, как BodyHandler преобразует ответ в нужный тип, а также типичные ошибки начинающих. Если вы новичок в работе с сетью на Java, начните с введения в сетевое программирование; об асинхронном строительном блоке, используемом здесь, читайте в CompletableFuture.

Три основных типа

HttpClient client = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_2)       // HTTP/2, falling back to 1.1
        .connectTimeout(Duration.ofSeconds(10))
        .followRedirects(HttpClient.Redirect.NORMAL)
        .build();

Один экземпляр HttpClient является потокобезопасным и многократно используемым — создайте его один раз и используйте во всём приложении; не создавайте новый клиент для каждого запроса. Через него вы отправляете объекты HttpRequest и получаете объекты HttpResponse.

Построение запроса

HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://example.com/api"))
        .header("Accept", "application/json")
        .timeout(Duration.ofSeconds(5))
        .POST(HttpRequest.BodyPublishers.ofString("{\"x\":1}"))
        .build();

Метод HTTP-глагола (GET(), POST(...), PUT(...), DELETE()) выбирается в строителе. BodyPublisher предоставляет тело запроса — ofString, ofByteArray, ofFile или noBody(). Запросы неизменяемы после построения и могут быть повторно использованы.

Отправка: синхронная и асинхронная

// Blocking
HttpResponse<String> resp =
        client.send(request, HttpResponse.BodyHandlers.ofString());

// Non-blocking — returns a CompletableFuture
CompletableFuture<HttpResponse<String>> future =
        client.sendAsync(request, HttpResponse.BodyHandlers.ofString());

BodyHandler определяет, как материализуется тело ответа: ofString(), ofByteArray(), ofFile(path), ofLines() (это Stream<String>) или discarding(). sendAsync возвращает CompletableFuture, поэтому вы можете выстраивать цепочки .thenApply, .thenAccept и .exceptionally без блокировки потока.

Чтение ответа

HttpResponse<T> — это простой типизированный объект-значение. Наиболее часто используемые методы:

statusCode() — HTTP-статус в виде int (например, 200, 404). Метода isSuccessful() нет; проверяйте код самостоятельно.
body() — тело, уже преобразованное в T переданным BodyHandler.
headers() — объект HttpHeaders. Используйте firstValue("Content-Type") (возвращает Optional<String>) или allValues("Set-Cookie") для повторяющихся заголовков.
uri() — итоговый URI, который может отличаться от URI запроса после перенаправления.

Имена заголовков сопоставляются без учёта регистра, поэтому firstValue("content-type") и firstValue("Content-Type") возвращают одно и то же значение.

Практический пример: синхронный GET, синхронный POST и асинхронный запрос

Эта программа создаёт петлевую конечную точку, которая сообщает полученный HTTP-метод, а затем обращается к ней тремя способами через один общий HttpClient: синхронный GET, синхронный POST с телом и асинхронный GET через CompletableFuture.

java— editable, runs on the server

import com.sun.net.httpserver.HttpServer;
import java.io.OutputStream;
import java.net.InetSocketAddress;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.concurrent.CompletableFuture;

public class HttpClientDemo {
  public static void main(String[] args) throws Exception {
    HttpServer server = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
    server.createContext("/api", ex -> {
      byte[] body = ("handled " + ex.getRequestMethod()).getBytes(StandardCharsets.UTF_8);
      ex.sendResponseHeaders(200, body.length);
      try (OutputStream os = ex.getResponseBody()) { os.write(body); }
    });
    server.start();
    int port = server.getAddress().getPort();
    URI uri = URI.create("http://127.0.0.1:" + port + "/api");

// ONE client, reused for every request
    HttpClient client = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(2))
        .build();

// 1. Synchronous GET
    HttpRequest get = HttpRequest.newBuilder(uri).GET().build();
    HttpResponse<String> r1 = client.send(get, HttpResponse.BodyHandlers.ofString());
    System.out.println("sync GET  -> " + r1.statusCode() + " / " + r1.body());

// 2. Synchronous POST with a request body
    HttpRequest post = HttpRequest.newBuilder(uri)
        .header("Content-Type", "text/plain")
        .POST(HttpRequest.BodyPublishers.ofString("payload"))
        .build();
    HttpResponse<String> r2 = client.send(post, HttpResponse.BodyHandlers.ofString());
    System.out.println("sync POST -> " + r2.statusCode() + " / " + r2.body());

// 3. Asynchronous GET returning a CompletableFuture
    CompletableFuture<String> future = client
        .sendAsync(get, HttpResponse.BodyHandlers.ofString())
        .thenApply(HttpResponse::body)
        .thenApply(b -> "async GET -> " + b);
    System.out.println(future.get());   // join the async result

server.stop(0);
  }
}

Что можно извлечь из этого примера:

Один HttpClient обслужил все три запроса. Клиент неизменяем и потокобезопасен, поэтому правильный подход — создать один раз и использовать везде; создание нового клиента на каждый вызов расточительно для пулов соединений и сессий HTTP/2. Обратите внимание, что disconnect() нигде не вызывается — клиент управляет соединениями самостоятельно.
HTTP-глагол задаётся в строителе: .GET() для чтения и .POST(BodyPublishers.ofString("payload")) для записи. Сервер вернул использованный метод (handled GET, handled POST), подтверждая, что publisher и передал тело, и установил глагол.
HttpResponse — это типизированный объект с методами statusCode() и body(). Поскольку был передан BodyHandlers.ofString(), тело вернулось уже декодированным как String — замените его на ofByteArray, ofFile или ofLines, и тот же вызов вернёт байты, сохранённый файл или поток строк.
Асинхронный вызов вернул CompletableFuture и выстроил цепочку через .thenApply без блокировки потока вплоть до future.get(). Это ключевое архитектурное преимущество перед HttpURLConnection: параллелизм встроен, поэтому сотни одновременных запросов не требуют сотен заблокированных потоков.
Весь поток — клиент, запрос, синхронная и асинхронная отправки, типизированные ответы — обошёлся без ручной работы с потоками и без ловушки потока ошибок. По сравнению с HttpURLConnection HttpClient короче, безопаснее и функциональнее, поэтому он является выбором по умолчанию на Java 11+.

Типичные ошибки

Коды 4xx и 5xx не являются исключениями. В отличие от некоторых библиотек, HttpClient нормально возвращает ответ для любого полученного статуса; исключение IOException выбрасывается только при транспортных сбоях (отказ соединения, таймаут, DNS). Всегда проверяйте statusCode() — тело ответа с ошибкой по-прежнему доступно для чтения.
Создайте один клиент и используйте его совместно. HttpClient неизменяем, потокобезопасен и владеет собственным пулом соединений. Создание нового клиента на каждый запрос уничтожает повторное использование соединений и сессии HTTP/2. Метода close() нет вплоть до Java 21 (а в Java 21+ он реализует AutoCloseable, однако долгоживущий общий клиент редко нуждается в закрытии).
connectTimeout и timeout — это разные вещи. HttpClient.connectTimeout(...) ограничивает время установки TCP-соединения; HttpRequest.timeout(...) ограничивает весь цикл запроса/ответа. Запрос, достигший таймаута, завершает future исключительно с HttpTimeoutException.
GET не может содержать тело. Вызов GET() с BodyPublisher не соответствует принципам API — используйте POST, PUT или обобщённый method(name, publisher) для глаголов, отправляющих данные.
URI.create требует абсолютного, корректно сформированного URI. Пробелы и другие небезопасные символы не кодируются автоматически; закодируйте параметры запроса перед построением URI.

Практика

В высоконагруженном сервисе разработчик пишет 'HttpClient.newHttpClient()' внутри метода, обрабатывающего каждый входящий запрос, создавая тем самым новый клиент на каждый вызов. Ревьюеры указывают на проблему. В чём она?

'HttpClient' неизменяем и потокобезопасен, владеет пулом соединений; нужно создать его один раз и использовать повторно, поскольку новый клиент на каждый запрос уничтожает повторное использование соединений и сессии HTTP/2'HttpClient.newHttpClient()' выбрасывает исключение при повторном вызове в пределах одной JVM, поэтому второй запрос завершится ошибкойНовый клиент на каждый запрос обязателен, поскольку 'HttpClient' не является потокобезопасным и не может быть общимЭто нормальная и даже рекомендуемая практика, так как каждый клиент должен быть закрыт методом 'disconnect()' после одного запроса