unirest-java-3

Unirest-Java 3.x リファレンス（v3.14.5）

このスキルでは、Java 8 以降向けの Unirest-Java 3.x HTTP クライアントライブラリを扱います。HTTP エンジンとして Apache HttpClient 4 を使用し、デフォルトの JSON パーサーとして GSON が含まれています。

機能の範囲

✅ 得意なこと

1. Fluent API を使った HTTP リクエスト（GET、POST、PUT、DELETE、PATCH）の作成
2. 組み込みの GSON による JSON／オブジェクトのマッピング（追加の依存関係は不要）
3. CompletableFuture による非同期リクエスト（Apache HttpAsyncClient 経由）
4. 進捗状況を監視できるファイルアップロード
5. HTTP クライアントのモックテスト
6. 破棄方法を設定できるレスポンスキャッシュ
7. プロキシ設定（シンプル、システム、リクエストごと）
8. ロギングや認証のためのリクエスト／レスポンスインターセプター
9. コネクションプールの調整（concurrency(total, perRoute)）
10. 接続タイムアウトとは独立したソケットタイムアウトの制御
11. ソケットエラー時の自動リトライ（automaticRetries()）
12. バックグラウンドスレッド管理のためのシャットダウンフック
13. カスタム HostnameVerifier のサポート

⚠️ 要件

1. Java 8 以降
2. Apache HttpClient 4（推移的依存関係）
3. Maven／Gradle による依存関係管理

❌ 対象外（代替手段）

1. HTTP/2 → Unirest 4.x を使用（デフォルトで HTTP/2 を使用）
2. Unirest 経由の WebSocket → Apache HttpClient WebSocket または専用ライブラリを使用
3. Server-Sent Events（SSE）→ Unirest 4.x またはカスタム実装を使用
4. カスタム Executor のサポート → 3.x では利用できません
5. Java Authenticator との連携 → Apache 固有の認証方式を使用
6. ProxySelector のサポート → リクエストごとのプロキシまたはシステムプロパティを使用

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

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

• Java 8 以降のプロジェクトで REST API に HTTP リクエストを送信する
• HTTP エンジンとして Apache HttpClient を使用する
• 追加の依存関係なしで組み込みの GSON を利用する
• コネクションプールを調整する（concurrency()）
• ソケットタイムアウトを個別に制御する
• ソケットエラー時の自動リトライを使用する
• リクエストごとのプロキシを設定する
• カスタム HostnameVerifier を使用する

クイックスタート

Maven の依存関係（Unirest 3.14.5）：

<dependency>
    <groupId>com.konghq</groupId>
    <artifactId>unirest-java</artifactId>
    <version>3.14.5</version>
</dependency>

✅ JSON モジュールの宣言は不要です — GSON はデフォルトで含まれています。

最小限の 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 3.x は、デフォルトで GSON を含む単一の依存関係です。

<dependency>
    <groupId>com.konghq</groupId>
    <artifactId>unirest-java</artifactId>
    <version>3.14.5</version>
</dependency>

✅ JSON モジュールを別途宣言する必要はありません — JsonObjectMapper（GSON ベース）が含まれています。

重要：設定

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

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

主な設定オプション：

メソッド	影響	デフォルト
connectTimeout(int)	接続タイムアウト（ms）	10000
socketTimeout(int)	ソケット／読み取りタイムアウト（ms）	60000
concurrency(int, int)	接続の最大合計数、ルートごとの最大数	200/20
followRedirects(boolean)	HTTP リダイレクトに従う	true
verifySsl(boolean)	SSL 検証を強制する	true
enableCookieManagement(boolean)	Cookie を受け入れて保存する	true
automaticRetries(boolean)	ソケットエラー時に自動リトライする（最大 4 回）	true
retryAfter(boolean)	Retry-After ヘッダーがある場合に 429／529 で自動リトライする	false
defaultBaseUrl(String)	すべてのリクエストに適用するデフォルトのベース URL	なし
addShutdownHook(boolean)	JVM シャットダウンフックを登録する	false
useSystemProperties(boolean)	プロキシなどにシステムプロパティを使用する	true

複数の設定：

// 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());
    });

リクエストごとのプロキシ（3.x のみ）：

Unirest.get("http://localhost/data")
    .proxy("proxy.com", 8080)
    .asString();

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 (GSON included by default)
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 を参照してください。

重要：モック

静的モック：

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

インスタンスモック（3.x では両方のクライアントが必要です）：

UnirestInstance unirest = Unirest.spawnInstance();
MockClient mock = MockClient.register(unirest);
// In 3.x, the mock implements both Client and AsyncClient

ボディのマッチング：

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().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 を参照してください。

重要：プロキシ

シンプルなプロキシ：

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

リクエストごとのプロキシ（3.x のみ）：

Unirest.get("http://localhost/data")
    .proxy("proxy.com", 8080)
    .asString();

システムプロパティ（3.x ではデフォルトで true）：

System.setProperty("http.proxyHost", "localhost");
System.setProperty("http.proxyPort", "7777");
// useSystemProperties defaults to true in 3.x

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

よくある問題の解決方法

エラー	原因	解決方法
NoClassDefFoundError: kong/unirest/Unirest	パッケージが間違っています	import kong.unirest.* を使用してください（kong.unirest.core.* ではありません）
asObject() が null のボディを返す	レスポンスの解析に失敗しました	詳細を確認するには、response.getParsingError() を確認してください
ConnectException: Connection timed out	サーバーに到達できないか、タイムアウトが短すぎます	connectTimeout を延長するか、ネットワークを確認してください
SocketTimeoutException	読み取りタイムアウトを超過しました	socketTimeout を延長してください（デフォルトは 60000ms）
SSLHandshakeException	SSL 検証に失敗しました	開発環境に限り verifySsl(false) を使用し、本番環境では証明書を修正してください
プロキシが動作しない	システムプロパティが無効になっている可能性があります	useSystemProperties(true) を確認してください（3.x ではデフォルトで true）
接続数が多すぎる	接続プールが枯渇しています	concurrency(total, perRoute) の値を増やしてください
自動リトライが動作しない	無効になっているか、適用対象外です	automaticRetries(true) を確認してください（デフォルトは true）

注意点

1. Java 8 以上で十分です — 3.x は Java 8 で動作します（Java 11 以上が必要な 4.x とは異なります）
2. GSON はデフォルトで含まれています — 独立した JSON モジュールを宣言する必要はありません（4.x とは異なります）
3. パッケージは kong.unirest です — kong.unirest.core ではありません（こちらは 4.x のパッケージです）
4. Maven の依存関係は 1 つです — unirest-java:3.14.5 です（BOM、core、module を使用する 4.x とは異なります）
5. Apache HttpClient エンジンを使用します — Apache HttpClient 4 を使用します（java.net.http.HttpClient ではありません）
6. ソケットタイムアウトは個別に設定されます — socketTimeout() は connectTimeout() とは別に読み取りタイムアウトを制御します
7. 接続プールの調整 — concurrency(total, perRoute) を使って Apache の接続プールを調整できます
8. 自動リトライはデフォルトで有効です — automaticRetries(true) はソケットエラーを最大 4 回リトライします
9. リクエストごとのプロキシに対応しています — request.proxy(host, port) が動作します（4.x では削除されています）
10. HostnameVerifier に対応しています — hostnameVerifier(verifier) でカスタム SSL ホスト名検証を設定できます
11. シャットダウンフックを利用できます — addShutdownHook(true) は JVM のシャットダウンフックを登録します
12. システムプロキシのプロパティはデフォルトで有効です — useSystemProperties のデフォルト値は true です（4.x とは異なります）
13. Unirest は WebSocket に対応していません — Apache HttpClient WebSocket または専用ライブラリを使用してください
14. SSE に対応していません — 3.x には Unirest.sse() がありません
15. モックの登録には両方のクライアントが必要です — MockClient は Client と AsyncClient の両方を実装しています

参考資料

リクエスト

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

レスポンス

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

設定

• configuration.md — 設定オプションの全テーブル、グローバルインターセプター、複数の設定、オブジェクトマッパー、メトリクス、Apache 固有のオプション

モック

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

キャッシュ

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

プロキシ

• proxies.md — シンプルなプロキシ、システムプロパティ、リクエストごとのプロキシ