unirest-java-4

Unirest-Java 4.x リファレンス（v4.10.0）

このスキルでは、Java 11 以降向けの Unirest-Java 4.x HTTP クライアントライブラリを扱います。標準搭載の java.net.http.HttpClient（3.x の Apache HttpClient を置き換えるもの）を使用し、デフォルトでは HTTP/2 を使用します。

対応範囲

✅ 得意なこと

1. Fluent API を使った HTTP リクエストの作成（GET、POST、PUT、DELETE、PATCH）
2. GSON または Jackson による JSON／オブジェクトのマッピング（モジュールを明示的に宣言する必要があります）
3. CompletableFuture を使った非同期リクエスト（java.net.http.HttpClient に組み込まれています）
4. 進捗状況の監視に対応したファイルのアップロード
5. Unirest.sse(url) による Server-Sent Events（SSE）の受信
6. Unirest.webSocket(url) による WebSocket 接続
7. HTTP クライアントのモックテスト
8. 退避方法を設定できるレスポンスキャッシュ
9. プロキシ設定（シンプル、システム、ProxySelector）
10. デフォルトで HTTP/2 を使用（config.version() で設定可能）
11. config.executor() によるカスタムエグゼキューターのサポート
12. config.authenticator() による Java Authenticator のサポート

⚠️ 要件

1. Java 11 以降（java.net.http.HttpClient を使用）
2. オブジェクトのマッピングには JSON モジュール（unirest-modules-gson または unirest-modules-jackson）を宣言する必要があります
3. BOM を使った Maven／Gradle の依存関係管理

❌ 対応範囲外（代替手段あり）

1. リクエストごとのプロキシ → グローバルな Unirest.config().proxy() を使用します（4.x で削除）
2. カスタム HostnameVerifier → システムプロパティ disableHostNameVerification() を使用します
3. ソケットタイムアウト（接続タイムアウトとは独立） → 代わりに requestTimeout() を使用します
4. コネクションプールの調整（concurrency(total, perRoute)） → 非対応です（java.net.http が管理します）
5. ソケットエラー発生時の自動再試行 → 429／529 に限り retryAfter() を使用します
6. シャットダウンフック → 不要です（管理が必要なバックグラウンドスレッドはありません）
7. Apache HttpClient との統合 → Apache 固有の機能が必要な場合は 3.x を使用します

このスキルを使用する場面

ユーザーが次のことを必要としている場合に、このスキルを使用します。

• Java で REST API に HTTP リクエストを送信する
• HTTP 経由でファイルをアップロードまたはダウンロードする
• Server-Sent Event ストリームを受信する
• ユニットテストで HTTP 呼び出しをモックする
• HTTP リクエストのプロキシを設定する
• HTTP レスポンスをキャッシュする
• Unirest 3.x から 4.x に移行する

クイックスタート

Maven の依存関係（Unirest 4.10.0）：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.konghq</groupId>
            <artifactId>unirest-java-bom</artifactId>
            <version>4.10.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>com.konghq</groupId>
        <artifactId>unirest-java-core</artifactId>
    </dependency>
    
    <dependency>
        <groupId>com.konghq</groupId>
        <artifactId>unirest-modules-gson</artifactId>
    </dependency>
</dependencies>

最小限の GET リクエスト：

String body = Unirest.get("https://api.example.com/users")
    .asString()
    .getBody();

JSON を使った最小限の POST：

HttpResponse<JsonNode> response = Unirest.post("https://api.example.com/users")
    .header("Content-Type", "application/json")
    .body(new User("Alice", "[email protected]"))
    .asJson();

重要：インストール

Unirest 4 はモジュール式です。次を宣言する必要があります。

1. unirest-java-core — HTTP クライアントエンジン
2. JSON モジュール — unirest-modules-gson または unirest-modules-jackson（オブジェクトのマッピング／JSON の解析に必要）

⚠️ JSON モジュールがない場合、asObject()、asJson()、JSON Patch の呼び出しは実行時に失敗します。

インストールの詳細は、references/configuration.md を参照してください。

重要：設定

すべての設定は Unirest.config() で行います。

Unirest.config()
    .connectTimeout(5000)
    .setDefaultHeader("Accept", "application/json")
    .setDefaultBasicAuth("user", "pass")
    .followRedirects(true)
    .verifySsl(true)
    .enableCookieManagement(true)
    .proxy("proxy.com", 8080, "user", "pass");

主な設定オプション：

メソッド	影響	デフォルト
connectTimeout(int)	接続タイムアウト（ms）	10000
requestTimeout(int)	リクエストタイムアウト	infinite
followRedirects(boolean)	HTTP リダイレクトに従う	true
verifySsl(boolean)	SSL 検証を必須にする	true
enableCookieManagement(boolean)	Cookie を受け入れて保存する	true
retryAfter(boolean)	429／529 発生時に自動再試行する	false
defaultBaseUrl(String)	すべてのリクエストのデフォルトのベース URL	none

複数の設定：

// Primary instance (same as static Unirest)
UnirestInstance unirest = Unirest.primaryInstance();

// Spawn a new independent instance
UnirestInstance custom = Unirest.spawnInstance();
custom.config().connectTimeout(3000);

⚠️ 新しいインスタンスを作成した場合、そのシャットダウンはご自身の責任で行ってください。

設定表全体、インターセプター、オブジェクトマッパー、メトリクスについては、references/configuration.md を参照してください。

重要：リクエストの送信

基本的なリクエストの種類：

Unirest.get("http://localhost/users").asString();
Unirest.post("http://localhost/users").body(json).asJson();
Unirest.put("http://localhost/users/1").body(user).asEmpty();
Unirest.delete("http://localhost/users/1").asEmpty();

ルートパラメーター：

Unirest.get("http://localhost/users/{id}")
    .routeParam("id", "42")
    .asString();
// Results in http://localhost/users/42

クエリパラメーター：

Unirest.get("http://localhost/search")
    .queryString("q", "unirest")
    .queryString("page", 1)
    .asString();

ヘッダーと認証：

Unirest.get("http://localhost/protected")
    .header("X-Custom", "value")
    .basicAuth("user", "pass")
    .asString();

フォームデータ：

Unirest.post("http://localhost/form")
    .field("name", "Alice")
    .field("age", 30)
    .asEmpty();

ファイルのアップロード：

Unirest.post("http://localhost/upload")
    .field("file", new File("/path/to/file.zip"))
    .asEmpty();

非同期リクエスト：

CompletableFuture<HttpResponse<JsonNode>> future = Unirest.get("http://localhost/data")
    .asJsonAsync(response -> {
        System.out.println(response.getBody());
    });

JSON Patch（RFC-6902）：

Unirest.jsonPatch("http://localhost/resource")
    .add("/fruits/-", "Apple")
    .remove("/bugs")
    .replace("/name", "Updated")
    .asJson();

アップロードの進捗状況、ページ分割されたリクエスト、クライアント証明書などについては、references/requests.md を参照してください。

重要：レスポンスの処理

レスポンスの種類：

// String
String body = Unirest.get(url).asString().getBody();

// Object mapping
Book book = Unirest.get(url).asObject(Book.class).getBody();

// Generic types
List<Book> books = Unirest.get(url)
    .asObject(new GenericType<List<Book>>(){}).getBody();

// JSON
JsonNode json = Unirest.get(url).asJson().getBody();

// File
File file = Unirest.get(url).asFile("/tmp/download.zip").getBody();

// Empty (status/headers only)
HttpResponse resp = Unirest.delete(url).asEmpty();

エラー処理：

Unirest.get("http://localhost/data")
    .asJson()
    .ifSuccess(response -> handleSuccess(response))
    .ifFailure(response -> {
        log.error("Status: " + response.getStatus());
        response.getParsingError().ifPresent(e -> {
            log.error("Parse error: " + e.getMessage());
        });
    });

解析エラー：

response.getParsingError().ifPresent(ex -> {
    String originalBody = ex.getOriginalBody();
    String message = ex.getMessage();
});

エラーオブジェクトのマッピング：

HttpResponse<Book> book = Unirest.get(url).asObject(Book.class);
Error err = book.mapError(Error.class);

ダウンロードの進行状況、大きなレスポンス、ボディのマッピングなどについては、references/responses.md を参照してください。

重要：Server-Sent Events（SSE）

非同期 SSE の利用：

var future = Unirest.sse("https://stream.example.com/events")
    .connect(event -> {
        var data = event.asObject(MyEvent.class);
        System.out.println("Event: " + data.getTitle());
    });

同期 SSE の利用：

Unirest.sse("https://stream.example.com/events")
    .connect()
    .map(event -> event.asObject(MyEvent.class))
    .forEach(data -> System.out.println("Event: " + data.getTitle()));

⚠️ SSE 接続は持続します。本番システムでは非同期モードを使用してください。 ⚠️ オブジェクトのマッピングには、ObjectMapper の設定が必要です。

詳細については、references/sse.md を参照してください。

重要：キャッシュ

基本的なキャッシュ：

Unirest.config().cacheResponses(true);

オプションを指定した高度なキャッシュ：

Unirest.config().cacheResponses(Cache.builder()
    .depth(100)                      // Max entries
    .maxAge(5, TimeUnit.MINUTES));   // Entry TTL

カスタムキャッシュ（例：Guava）：

Unirest.config().cacheResponses(
    Cache.builder().backingCache(new MyGuavaCache()));

カスタムキャッシュの実装の詳細については、references/caching.md を参照してください。

重要：モック

静的モック：

MockClient mock = MockClient.register();

mock.expect(HttpMethod.GET, "http://api.example.com/users")
    .thenReturn("{\"name\":\"Alice\"}")
    .withStatus(200);

String body = Unirest.get("http://api.example.com/users")
    .asString().getBody();
// body == "{\"name\":\"Alice\"}"

mock.verifyAll(); // Verify all expects were called

インスタンスモック：

UnirestInstance unirest = Unirest.spawnInstance();
MockClient mock = MockClient.register(unirest);

ボディの照合：

mock.expect(HttpMethod.POST, "http://api.example.com/users")
    .body(FieldMatcher.of("name", "Alice", "role", "admin"))
    .thenReturn()
    .withStatus(201);

回数を指定した検証：

var expect = mock.expect(HttpMethod.GET, "http://api.example.com/users").thenReturn();
expect.verify();              // At least once
expect.verify(Times.never()); // Never called

POJO のレスポンス、複数の expect などについては、references/mocking.md を参照してください。

重要：プロキシ

シンプルなプロキシ：

Unirest.config().proxy("proxy.com", 8080, "user", "pass");

システムプロパティ：

System.setProperty("http.proxyHost", "localhost");
System.setProperty("http.proxyPort", "7777");
Unirest.config().useSystemProperties(true);

複数のプロキシ（ProxySelector）：

Unirest.config()
    .proxy(new ProxySelector() {
        @Override
        public List<Proxy> select(URI uri) {
            if (uri.getHost().equals("internal.com")) {
                return List.of(new Proxy(HTTP,
                    InetSocketAddress.createUnresolved("internal-proxy.com", 8080)));
            }
            return List.of(new Proxy(HTTP,
                InetSocketAddress.createUnresolved("default-proxy.com", 8080)));
        }
        @Override
        public void connectFailed(URI uri, SocketAddress sa, IOException ioe) {}
    });

認証設定や詳細については、references/proxies.md を参照してください。

重要：WebSocket

WebSocket への接続：

Unirest.webSocket("ws://localhost/socket")
    .connect(ws -> {
        ws.sendText("Hello!");
        ws.onMessage(message -> {
            System.out.println("Received: " + message);
        });
    });

POJO マッピングを使用する WebSocket：

Unirest.webSocket("ws://localhost/events")
    .connect(ws -> {
        ws.onMessage(event -> {
            MyEvent data = event.asObject(MyEvent.class);
            processEvent(data);
        });
    });

⚠️ WebSocket は 4.x 専用の機能です。3.x では利用できません。

詳細については、references/websocket.md を参照してください。

すぐに解決する方法

エラー	原因	解決方法
NoClassDefFoundError: JsonObject	JSON モジュールがありません	unirest-modules-gson または unirest-modules-jackson の依存関係を追加します
java.lang.NoClassDefFoundError: kong/unirest/Unirest	4.x でパッケージが誤っています	インポートを kong.unirest.* から kong.unirest.core.* に変更します
asObject() が null のボディを返す	レスポンスの解析に失敗しました	詳細を確認するには response.getParsingError() を確認します
ConnectException: Connection timed out	サーバーに到達できないか、タイムアウトが短すぎます	connectTimeout を延長するか、ネットワークを確認します
SSLHandshakeException	SSL 検証に失敗しました	開発環境でのみ verifySsl(false) を使用し、本番環境では証明書を修正します
Host header override not allowed	Java 11 以降の HttpClient の制限です	システムプロパティ jdk.httpclient.allowRestrictedHeaders=host を設定します
4.x でプロキシが機能しない	4.x ではシステムプロパティがデフォルトで無効です	useSystemProperties(true) を明示的に呼び出します

注意点

1. Java 11 以降が必須です — Unirest 4.x は java.net.http.HttpClient を使用するため、Java 8 では動作しません
2. JSON モジュールの宣言が必要です — 3.x とは異なり、4.x にはデフォルトの JSON パーサーがありません。unirest-modules-gson または unirest-modules-jackson を使用しないと、実行時に JSON の解析が失敗します
3. パッケージ名の変更 — kong.unirest（3.x）→ kong.unirest.core（4.x）、JSON モジュールは kong.unirest.modules.gson/jackson（4.3 以降）
4. デフォルトで HTTP/2 を使用します — 4.x のデフォルトは HttpClient.Version.HTTP_2 です。ダウングレードするには config.version(HttpClient.Version.HTTP_1_1) を使用します
5. リクエストごとのプロキシには対応していません — 3.x では request.proxy(host, port) を使用できました。4.x では Unirest.config().proxy() を使ったグローバルプロキシのみサポートしています
6. socketTimeout はありません — 3.x には独立した socketTimeout() がありました。4.x では requestTimeout() を使用し、リクエストのライフサイクル全体を対象とします
7. 並行処理の調整には対応していません — concurrency(total, perRoute) は Apache 固有の機能でした。java.net.http が内部で接続プールを管理します
8. 自動再試行には対応していません — automaticRetries(true) は Apache 固有の機能でした。4.x で使用できるのは、429／529 レスポンスに対する retryAfter() のみです
9. HostnameVerifier はありません — 3.x には hostnameVerifier(verifier) がありました。4.x では disableHostNameVerification() システムプロパティを使用します（JVM 全体に適用）
10. システムプロキシのプロパティはデフォルトで無効です — 3.x ではデフォルトが true でしたが、4.x では useSystemProperties のデフォルトは false です
11. SSE と WebSocket は 4.x のみです — Unirest.sse() と Unirest.webSocket() は 3.x にはありません
12. モックの登録が簡素化されています — 3.x：MockClient.register() では .httpClient(client).asyncClient(client) が必要でした。4.x：.httpClient(client) のみ必要です
13. 設定を変更するにはリセットが必要です — Unirest を有効化した後にクライアント作成時の設定を変更する場合は、事前に config().reset() を実行する必要があります
14. isRunning() は削除されました — 3.x には Unirest.isRunning() がありました。4.x では削除されています（監視対象となるバックグラウンドスレッドがありません）

参考資料

リクエスト

• requests.md — ルートパラメーター、クエリパラメーター、ヘッダー、認証、ボディの種類、ファイルのアップロード、アップロードの進捗状況、非同期処理、ページ分割されたリクエスト、クライアント証明書

レスポンス

• responses.md — asEmpty/asString/asObject/asJson/asFile、GenericType、解析エラー、エラーオブジェクトのマッピング、ダウンロードの進捗状況、大きなレスポンス、エラー処理

設定

• configuration.md — 設定オプションの全一覧、グローバルインターセプター、複数の設定、オブジェクトマッパー（Jackson/GSON）、メトリクス

モック

• mocking.md — 静的／インスタンスのモック、複数の期待値（スコアリング）、検証、ボディの照合、フォームパラメーター、POJO レスポンス

キャッシュ

• caching.md — 基本／高度なキャッシュ、カスタムキャッシュ実装

サーバー送信イベント

• sse.md — SSE の非同期／同期での利用、オブジェクトマッピングの要件

WebSocket

• websocket.md — WebSocket 接続、メッセージ処理、POJO マッピング

プロキシ

• proxies.md — シンプルなプロキシ、システムプロパティ、Authenticator を使った ProxySelector

アップグレードガイド

• upgrade-guide.md — 3.x から 4.x への移行、パッケージ名の変更、Maven 座標の変更、動作の違い