KotlinでOkHttpを使ってカスタムHTTPクライアントを作成する方法を徹底解説

KotlinでOkHttpを使用してカスタムHTTPクライアントを作成する方法を学ぶことは、ネットワーク通信を必要とするアプリケーション開発において非常に重要です。OkHttpは、効率的で信頼性の高いHTTP通信を提供するオープンソースライブラリで、KotlinやAndroid開発者にとって必須のツールです。本記事では、OkHttpの基本的なセットアップ方法から、リクエストのカスタマイズ、エラーハンドリング、セキュア通信の設定まで、ステップバイステップで解説します。OkHttpを使いこなすことで、柔軟で効率的なネットワーク通信をアプリに実装できるようになります。

OkHttpとは何か？
1. OkHttpの主な特徴
2. OkHttpの利用シーン
OkHttpのセットアップ方法
基本的なHTTPリクエストの作成
リクエストにヘッダーやパラメータを追加する方法
タイムアウトやリトライの設定
インターセプターを使ったカスタマイズ
SSL認証とセキュアな通信
エラーハンドリングとデバッグ
まとめ

OkHttpとは何か？

OkHttpは、Square社が開発したオープンソースのHTTPクライアントライブラリです。KotlinやJavaでのネットワーク通信に特化しており、Android開発でも広く使用されています。シンプルかつ強力なAPIで、非同期通信やHTTP/2、接続プール、Gzip圧縮、キャッシュ機能などの多くの機能をサポートしています。

OkHttpの主な特徴

HTTP/2対応：複数のリクエストを同時に送信し、ネットワーク効率を向上させます。
接続プール：再利用可能な接続を管理し、接続待ち時間を削減します。
自動リトライ：一時的なネットワーク障害が発生した場合、自動的にリクエストを再試行します。
インターセプター：リクエストやレスポンスをカスタマイズするための強力なツールです。
同期・非同期リクエスト：柔軟に同期・非同期処理を選択できます。

OkHttpの利用シーン

REST APIと通信するアプリケーション
大量のネットワークリクエストが必要なサービス
安定した接続管理が求められるAndroidアプリ

OkHttpはその性能の高さと柔軟性から、現代のKotlinおよびAndroid開発において欠かせないHTTPクライアントライブラリです。

OkHttpのセットアップ方法

KotlinプロジェクトでOkHttpを使用するためのセットアップ方法について説明します。Gradleを用いてOkHttpライブラリを依存関係に追加し、環境を整えましょう。

Gradle依存関係の追加

まず、プロジェクトのbuild.gradleファイルにOkHttpライブラリを追加します。最新バージョンを使用することを推奨します。

build.gradle.kts（Kotlin DSL）:

dependencies {
    implementation("com.squareup.okhttp3:okhttp:4.9.3")
}

build.gradle（Groovy DSL）:

dependencies {
    implementation 'com.squareup.okhttp3:okhttp:4.9.3'
}

OkHttpのインスタンス作成

依存関係を追加したら、OkHttpクライアントをインスタンス化します。

import okhttp3.OkHttpClient

val client = OkHttpClient()

AndroidManifestのパーミッション設定

Androidアプリでインターネットにアクセスする場合、AndroidManifest.xmlに以下のパーミッションを追加する必要があります。

<uses-permission android:name="android.permission.INTERNET"/>

確認手順

依存関係の同期後、コード内でOkHttpを使用して簡単なリクエストを送信し、正しくセットアップできているか確認しましょう。

OkHttpのセットアップが完了したら、基本的なHTTPリクエストの作成に進みます。

基本的なHTTPリクエストの作成

OkHttpを使用して、基本的なHTTPリクエスト（GETおよびPOST）を作成する方法を紹介します。これにより、APIからデータを取得したり、サーバーにデータを送信したりできるようになります。

GETリクエストの作成

以下は、OkHttpを使ったシンプルなGETリクエストの例です。

import okhttp3.*

val client = OkHttpClient()

fun runGetRequest(url: String) {
    val request = Request.Builder()
        .url(url)
        .build()

    client.newCall(request).enqueue(object : Callback {
        override fun onFailure(call: Call, e: IOException) {
            println("GETリクエスト失敗: ${e.message}")
        }

        override fun onResponse(call: Call, response: Response) {
            response.use {
                if (!response.isSuccessful) {
                    println("予期しないレスポンス: ${response}")
                } else {
                    println(response.body?.string())
                }
            }
        }
    })
}

// 使用例
runGetRequest("https://jsonplaceholder.typicode.com/posts/1")

POSTリクエストの作成

サーバーにデータを送信するためのPOSTリクエストの例です。リクエストボディにはJSONデータを使用します。

import okhttp3.*
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.RequestBody.Companion.toRequestBody

val client = OkHttpClient()

fun runPostRequest(url: String, json: String) {
    val mediaType = "application/json; charset=utf-8".toMediaType()
    val requestBody = json.toRequestBody(mediaType)

    val request = Request.Builder()
        .url(url)
        .post(requestBody)
        .build()

    client.newCall(request).enqueue(object : Callback {
        override fun onFailure(call: Call, e: IOException) {
            println("POSTリクエスト失敗: ${e.message}")
        }

        override fun onResponse(call: Call, response: Response) {
            response.use {
                if (!response.isSuccessful) {
                    println("予期しないレスポンス: ${response}")
                } else {
                    println(response.body?.string())
                }
            }
        }
    })
}

// 使用例
val jsonData = """{"title": "foo", "body": "bar", "userId": 1}"""
runPostRequest("https://jsonplaceholder.typicode.com/posts", jsonData)

同期リクエストの作成

同期リクエストはメインスレッドをブロックするため、Androidでは非推奨ですが、簡単な例を示します。

val request = Request.Builder()
    .url("https://jsonplaceholder.typicode.com/posts/1")
    .build()

val response = client.newCall(request).execute()
println(response.body?.string())

まとめ

OkHttpを使えば、シンプルなコードでGETやPOSTリクエストが簡単に作成できます。非同期処理を活用することで、UIのブロックを防ぎ、スムーズなユーザー体験を提供できます。次は、リクエストにヘッダーやパラメータを追加する方法を見ていきましょう。

リクエストにヘッダーやパラメータを追加する方法

OkHttpを使用してHTTPリクエストにヘッダーやクエリパラメータを追加する方法を解説します。これにより、API認証や動的なデータ取得が可能になります。

リクエストにヘッダーを追加する

ヘッダーは、リクエストのメタデータとして利用されます。例えば、認証トークンやコンテンツタイプを指定する場合に使用します。

import okhttp3.*

val client = OkHttpClient()

fun runRequestWithHeaders(url: String) {
    val request = Request.Builder()
        .url(url)
        .addHeader("Authorization", "Bearer YOUR_TOKEN")
        .addHeader("Content-Type", "application/json")
        .build()

    client.newCall(request).enqueue(object : Callback {
        override fun onFailure(call: Call, e: IOException) {
            println("リクエスト失敗: ${e.message}")
        }

        override fun onResponse(call: Call, response: Response) {
            response.use {
                if (!response.isSuccessful) {
                    println("予期しないレスポンス: ${response}")
                } else {
                    println(response.body?.string())
                }
            }
        }
    })
}

// 使用例
runRequestWithHeaders("https://jsonplaceholder.typicode.com/posts/1")

クエリパラメータを追加する

URLにクエリパラメータを追加してリクエストを送信する方法です。OkHttpではURLをビルドすることで簡単に実現できます。

import okhttp3.*

val client = OkHttpClient()

fun runRequestWithQueryParams(baseUrl: String, queryParams: Map<String, String>) {
    val urlBuilder = baseUrl.toHttpUrlOrNull()?.newBuilder()
    queryParams.forEach { (key, value) ->
        urlBuilder?.addQueryParameter(key, value)
    }

    val url = urlBuilder?.build().toString()

    val request = Request.Builder()
        .url(url)
        .build()

    client.newCall(request).enqueue(object : Callback {
        override fun onFailure(call: Call, e: IOException) {
            println("リクエスト失敗: ${e.message}")
        }

        override fun onResponse(call: Call, response: Response) {
            response.use {
                if (!response.isSuccessful) {
                    println("予期しないレスポンス: ${response}")
                } else {
                    println(response.body?.string())
                }
            }
        }
    })
}

// 使用例
val params = mapOf("userId" to "1", "postId" to "10")
runRequestWithQueryParams("https://jsonplaceholder.typicode.com/comments", params)

ヘッダーとパラメータを同時に追加する

ヘッダーとクエリパラメータを組み合わせたリクエストも可能です。

fun runCustomRequest(url: String, headers: Map<String, String>, params: Map<String, String>) {
    val urlBuilder = url.toHttpUrlOrNull()?.newBuilder()
    params.forEach { (key, value) ->
        urlBuilder?.addQueryParameter(key, value)
    }

    val requestBuilder = Request.Builder().url(urlBuilder?.build().toString())
    headers.forEach { (key, value) ->
        requestBuilder.addHeader(key, value)
    }

    val request = requestBuilder.build()

    client.newCall(request).enqueue(object : Callback {
        override fun onFailure(call: Call, e: IOException) {
            println("リクエスト失敗: ${e.message}")
        }

        override fun onResponse(call: Call, response: Response) {
            response.use {
                if (!response.isSuccessful) {
                    println("予期しないレスポンス: ${response}")
                } else {
                    println(response.body?.string())
                }
            }
        }
    })
}

// 使用例
val headers = mapOf("Authorization" to "Bearer YOUR_TOKEN", "Accept" to "application/json")
val params = mapOf("userId" to "1")
runCustomRequest("https://jsonplaceholder.typicode.com/posts", headers, params)

まとめ

OkHttpを使うことで、簡単にリクエストにヘッダーやクエリパラメータを追加できます。API認証や動的なデータ取得を行う際に、これらの方法を活用することで柔軟なHTTP通信が実現できます。次は、タイムアウトやリトライの設定について解説します。

タイムアウトやリトライの設定

OkHttpを使用する際、タイムアウトやリトライの設定は、安定したネットワーク通信を行うために重要です。ネットワーク環境によっては、リクエストが遅延したり失敗したりするため、適切なタイムアウトとリトライの設定が必要です。

タイムアウトの設定方法

OkHttpでは、以下の3つのタイムアウトを設定できます。

接続タイムアウト（Connect Timeout）：サーバーへの接続にかかる最大時間
読み取りタイムアウト（Read Timeout）：サーバーからのデータ読み取りにかかる最大時間
書き込みタイムアウト（Write Timeout）：サーバーへのデータ送信にかかる最大時間

以下は、各タイムアウトを設定する例です。

import okhttp3.*
import java.util.concurrent.TimeUnit

val client = OkHttpClient.Builder()
    .connectTimeout(10, TimeUnit.SECONDS) // 接続タイムアウトを10秒に設定
    .readTimeout(30, TimeUnit.SECONDS)    // 読み取りタイムアウトを30秒に設定
    .writeTimeout(15, TimeUnit.SECONDS)   // 書き込みタイムアウトを15秒に設定
    .build()

fun runRequestWithTimeout(url: String) {
    val request = Request.Builder()
        .url(url)
        .build()

    client.newCall(request).enqueue(object : Callback {
        override fun onFailure(call: Call, e: IOException) {
            println("リクエスト失敗: ${e.message}")
        }

        override fun onResponse(call: Call, response: Response) {
            response.use {
                if (!response.isSuccessful) {
                    println("予期しないレスポンス: ${response}")
                } else {
                    println(response.body?.string())
                }
            }
        }
    })
}

// 使用例
runRequestWithTimeout("https://jsonplaceholder.typicode.com/posts/1")

リトライの設定方法

OkHttpはデフォルトで自動リトライを行いますが、リトライのカスタマイズも可能です。

自動リトライを無効にする場合：

val client = OkHttpClient.Builder()
    .retryOnConnectionFailure(false) // 自動リトライを無効化
    .build()

リトライ回数や条件をカスタマイズするには、カスタムインターセプターを使用します。

class RetryInterceptor(private val maxRetries: Int) : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        var attempt = 0
        var response: Response
        val request = chain.request()

        do {
            attempt++
            response = try {
                chain.proceed(request)
            } catch (e: IOException) {
                if (attempt >= maxRetries) {
                    throw e
                } else {
                    println("リトライ中: $attempt 回目")
                    continue
                }
            }
        } while (!response.isSuccessful && attempt < maxRetries)

        return response
    }
}

// OkHttpクライアントにインターセプターを追加
val client = OkHttpClient.Builder()
    .addInterceptor(RetryInterceptor(maxRetries = 3))
    .build()

タイムアウトとリトライの実用例

以下は、タイムアウトとカスタムリトライを組み合わせたクライアントの例です。

val client = OkHttpClient.Builder()
    .connectTimeout(10, TimeUnit.SECONDS)
    .readTimeout(30, TimeUnit.SECONDS)
    .writeTimeout(15, TimeUnit.SECONDS)
    .addInterceptor(RetryInterceptor(maxRetries = 3))
    .build()

まとめ

タイムアウトとリトライの適切な設定により、ネットワーク環境の不安定さを考慮した柔軟なHTTPクライアントを構築できます。次は、リクエストやレスポンスをカスタマイズするインターセプターについて解説します。

インターセプターを使ったカスタマイズ

OkHttpのインターセプターは、リクエストやレスポンスをカスタマイズするための強力な機能です。リクエストの前処理やレスポンスの後処理、ログの記録、認証トークンの付与など、さまざまな用途で活用できます。

インターセプターとは？

インターセプターは、リクエストやレスポンスの処理の途中に介入し、内容を変更したり、追加処理を行ったりする仕組みです。OkHttpには以下の2種類のインターセプターがあります：

Application Interceptor（アプリケーションインターセプター）

リクエストやレスポンスのカスタマイズに使用します。
リトライの処理やログ記録などに適しています。

Network Interceptor（ネットワークインターセプター）

ネットワークを経由するリクエストやレスポンスに適用されます。
キャッシュやネットワーク関連の処理に使用します。

リクエストに共通ヘッダーを追加するインターセプター

全てのリクエストに共通のヘッダー（例：認証トークン）を追加するインターセプターの例です。

class AuthInterceptor(private val token: String) : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val newRequest = chain.request().newBuilder()
            .addHeader("Authorization", "Bearer $token")
            .build()
        return chain.proceed(newRequest)
    }
}

// OkHttpクライアントにインターセプターを追加
val client = OkHttpClient.Builder()
    .addInterceptor(AuthInterceptor("your_auth_token"))
    .build()

リクエストとレスポンスのログを記録するインターセプター

リクエストとレスポンスの詳細をログに出力するインターセプターです。

class LoggingInterceptor : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val request = chain.request()
        println("リクエスト: ${request.method} ${request.url}")

        val response = chain.proceed(request)
        println("レスポンス: ${response.code} ${response.message}")

        return response
    }
}

// OkHttpクライアントにインターセプターを追加
val client = OkHttpClient.Builder()
    .addInterceptor(LoggingInterceptor())
    .build()

ネットワークインターセプターの使用例

ネットワークインターセプターを使用して、レスポンスのキャッシュを制御する例です。

class CacheControlInterceptor : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val response = chain.proceed(chain.request())
        return response.newBuilder()
            .header("Cache-Control", "max-age=60") // 60秒間キャッシュする
            .build()
    }
}

// OkHttpクライアントにネットワークインターセプターを追加
val client = OkHttpClient.Builder()
    .addNetworkInterceptor(CacheControlInterceptor())
    .build()

複数のインターセプターを組み合わせる

複数のインターセプターを同時に追加することができます。

val client = OkHttpClient.Builder()
    .addInterceptor(AuthInterceptor("your_auth_token"))
    .addInterceptor(LoggingInterceptor())
    .addNetworkInterceptor(CacheControlInterceptor())
    .build()

まとめ

インターセプターを使用することで、リクエストやレスポンスを柔軟にカスタマイズできます。共通ヘッダーの付与、ログ記録、キャッシュ制御など、さまざまな場面で活用可能です。次は、SSL認証とセキュアな通信の設定について解説します。

SSL認証とセキュアな通信

ネットワーク通信においてセキュリティは非常に重要です。OkHttpはHTTPS通信をサポートしており、SSL証明書の検証やカスタム証明書を使用することで、セキュアな通信を実現できます。本記事では、OkHttpを使ったSSL認証とセキュアな通信の設定方法を解説します。

HTTPSリクエストの基本

OkHttpはデフォルトでHTTPSリクエストをサポートしています。特別な設定をしなくても、HTTPSを使用したリクエストを行うことができます。

val client = OkHttpClient()

fun runSecureGetRequest(url: String) {
    val request = Request.Builder()
        .url(url)
        .build()

    client.newCall(request).enqueue(object : Callback {
        override fun onFailure(call: Call, e: IOException) {
            println("リクエスト失敗: ${e.message}")
        }

        override fun onResponse(call: Call, response: Response) {
            response.use {
                println(response.body?.string())
            }
        }
    })
}

// 使用例
runSecureGetRequest("https://jsonplaceholder.typicode.com/posts/1")

カスタムSSL証明書の設定

自己署名証明書を使用する場合、OkHttpにカスタムSSL証明書を設定する必要があります。以下の例では、カスタムトラストマネージャーを設定しています。

import okhttp3.*
import java.io.InputStream
import java.security.KeyStore
import javax.net.ssl.*

fun getCustomSslClient(certInputStream: InputStream): OkHttpClient {
    // 証明書をロード
    val keyStore = KeyStore.getInstance(KeyStore.getDefaultType()).apply {
        load(null, null)
        setCertificateEntry("custom", CertificateFactory.getInstance("X.509").generateCertificate(certInputStream))
    }

    // トラストマネージャーを作成
    val trustManagerFactory = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm()).apply {
        init(keyStore)
    }

    val sslContext = SSLContext.getInstance("TLS").apply {
        init(null, trustManagerFactory.trustManagers, null)
    }

    return OkHttpClient.Builder()
        .sslSocketFactory(sslContext.socketFactory, trustManagerFactory.trustManagers[0] as X509TrustManager)
        .build()
}

ホスト名の検証を無効化する（非推奨）

開発やテスト環境でのみ、ホスト名の検証を無効化することができます。本番環境では絶対に使用しないでください。

val client = OkHttpClient.Builder()
    .hostnameVerifier { _, _ -> true } // ホスト名検証を無効化
    .build()

SSLピンニング

SSLピンニングは、特定の証明書または公開鍵に限定して通信することで、中間者攻撃を防ぐ方法です。

val client = OkHttpClient.Builder()
    .certificatePinner(
        CertificatePinner.Builder()
            .add("yourdomain.com", "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=")
            .build()
    )
    .build()

まとめ

OkHttpを使用すると、HTTPSリクエストによるセキュアな通信が簡単に実現できます。カスタムSSL証明書やSSLピンニングを活用することで、さらに高いセキュリティを確保できます。次は、エラーハンドリングとデバッグ方法について解説します。

エラーハンドリングとデバッグ

OkHttpを使用したHTTP通信では、エラー処理とデバッグが重要です。適切なエラーハンドリングを実装し、問題を効率よく特定・解決する方法について解説します。

基本的なエラーハンドリング

OkHttpでリクエストが失敗した場合、例外が発生したり、レスポンスコードがエラーになることがあります。以下は、リクエスト失敗時の基本的なエラーハンドリングの例です。

import okhttp3.*
import java.io.IOException

val client = OkHttpClient()

fun runRequestWithErrorHandling(url: String) {
    val request = Request.Builder()
        .url(url)
        .build()

    client.newCall(request).enqueue(object : Callback {
        override fun onFailure(call: Call, e: IOException) {
            println("リクエスト失敗: ${e.message}")
        }

        override fun onResponse(call: Call, response: Response) {
            response.use {
                if (!response.isSuccessful) {
                    println("エラーコード: ${response.code}")
                    println("エラーメッセージ: ${response.message}")
                } else {
                    println(response.body?.string())
                }
            }
        }
    })
}

// 使用例
runRequestWithErrorHandling("https://jsonplaceholder.typicode.com/posts/invalid")

HTTPステータスコードの分類と処理

HTTPステータスコードによってエラーの種類が異なります。代表的なエラーコードは以下の通りです：

4xxクライアントエラー：リクエストに問題がある（例：404 Not Found, 401 Unauthorized）
5xxサーバーエラー：サーバー側で問題が発生（例：500 Internal Server Error, 503 Service Unavailable）

以下のコードはステータスコードに応じた処理を行う例です。

override fun onResponse(call: Call, response: Response) {
    response.use {
        when (response.code) {
            in 200..299 -> println("成功: ${response.body?.string()}")
            400 -> println("Bad Request")
            401 -> println("Unauthorized: 認証が必要です")
            404 -> println("Not Found: リソースが見つかりません")
            500 -> println("Internal Server Error: サーバーエラーが発生しました")
            else -> println("エラー: ${response.code}")
        }
    }
}

タイムアウトエラーの処理

ネットワーク遅延によるタイムアウトエラーはよく発生します。以下は、タイムアウトエラーを処理する例です。

override fun onFailure(call: Call, e: IOException) {
    if (e is java.net.SocketTimeoutException) {
        println("タイムアウトエラー: ${e.message}")
    } else {
        println("リクエスト失敗: ${e.message}")
    }
}

デバッグログの出力

リクエストとレスポンスの内容をログに記録することで、デバッグが容易になります。OkHttpのLoggingInterceptorを使用してログを出力する方法が一般的です。

LoggingInterceptorの追加方法:

依存関係の追加
build.gradleに以下を追加します。

   implementation 'com.squareup.okhttp3:logging-interceptor:4.9.3'

インターセプターの設定

   import okhttp3.logging.HttpLoggingInterceptor

   val loggingInterceptor = HttpLoggingInterceptor().apply {
       level = HttpLoggingInterceptor.Level.BODY
   }

   val client = OkHttpClient.Builder()
       .addInterceptor(loggingInterceptor)
       .build()

これにより、リクエストとレスポンスの詳細な内容がログに出力されます。

例外処理のポイント

IOException：ネットワーク接続やI/Oエラー
SocketTimeoutException：タイムアウト時の例外
UnknownHostException：DNS解決に失敗した場合

まとめ

適切なエラーハンドリングとデバッグログの活用により、ネットワーク通信の問題を迅速に特定・修正できます。次は、記事全体の内容をまとめます。

まとめ

本記事では、KotlinでOkHttpを使用してカスタムHTTPクライアントを作成する方法について解説しました。OkHttpのセットアップ方法から、基本的なHTTPリクエストの作成、ヘッダーやパラメータの追加、タイムアウトやリトライの設定、インターセプターによるカスタマイズ、SSL認証とセキュアな通信、エラーハンドリングとデバッグ方法までを詳しく説明しました。

OkHttpを使いこなすことで、柔軟で効率的なネットワーク通信を実現でき、KotlinやAndroidアプリの開発において信頼性の高いHTTPクライアントを構築できます。これらの知識を活用し、ネットワーク通信が必要なアプリケーションの開発を効率的に進めましょう。