代理

Ktor HTTP 用戶端允許您在多平台專案中配置代理設定。 支援兩種代理類型：HTTP 和 SOCKS。

支援的引擎

下表顯示了針對特定引擎支援的代理類型：

引擎	HTTP 代理	SOCKS 代理
Apache	✅	✖️
Java	✅	✖️
Jetty	✖️	✖️
CIO	✅	✖️
Android	✅	✅
OkHttp	✅	✅
JavaScript	✖️	✖️
Darwin	✅	✖️
Curl	✅	✅

請注意，目前 Darwin 引擎的 HTTP 代理不支援 HTTPS 請求。

新增相依性

要在用戶端中配置代理，您不需要新增特定的相依性。所需的相依性為：

• ktor-client-core；
• 一個引擎相依性。

配置代理

要配置代理設定，請在用戶端配置區塊內呼叫 engine 函數，然後使用 proxy 屬性。 此屬性接受一個 ProxyConfig 實例，該實例可以使用 ProxyBuilder 工廠建立。

val client = HttpClient() {
    engine {
        proxy = // Create proxy configuration
    }
}

HTTP 代理

以下範例展示如何使用 ProxyBuilder 配置 HTTP 代理：

val client = HttpClient() {
    engine {
        proxy = ProxyBuilder.http("http://sample-proxy-server:3128/")
    }
}

在 JVM 上，ProxyConfig 會映射到 Proxy 類別，因此您可以如下配置代理：

val client = HttpClient() {
    engine {
        proxy = Proxy(Proxy.Type.HTTP, InetSocketAddress("sample-proxy-server", 3128))
    }
}

SOCKS 代理

以下範例展示如何使用 ProxyBuilder 配置 SOCKS 代理：

val client = HttpClient() {
    engine {
        proxy = ProxyBuilder.socks(host = "sample-proxy-server", port = 1080)
    }
}

與 HTTP 代理類似，在 JVM 上您可以使用 Proxy 來配置代理設定：

val client = HttpClient() {
    engine {
        proxy = Proxy(Proxy.Type.SOCKS, InetSocketAddress("sample-proxy-server", 1080))
    }
}

代理驗證與授權

代理驗證與授權是引擎特定的，應手動處理。 例如，要使用基本驗證將 Ktor 用戶端驗證到 HTTP 代理伺服器，請如下方式將 Proxy-Authorization 標頭附加到每個請求中：

val client = HttpClient() {
    defaultRequest {
        val credentials = Base64.getEncoder().encodeToString("jetbrains:foobar".toByteArray())
        header(HttpHeaders.ProxyAuthorization, "Basic $credentials")
    }
}

要在 JVM 上將 Ktor 用戶端驗證到 SOCKS 代理，您可以使用 java.net.socks.username 和 java.net.socks.password 系統屬性。