okhttp-extension 是針對 okhttp 3 增強的網絡框架。使用 Kotlin 特性編寫，提供便捷的 DSL 方式創建網絡請求，支持協程、響應式編程等等。

其 core 模塊只依賴 OkHttp，不會引入第三方庫。

okhttp-extension 可以整合 Retrofit、Feign 框架，還提供了很多常用的攔截器。另外，okhttp-extension 也給開發者提供一種新的選擇。

github地址：https://github.com/fengzhizi715/okhttp-extension

Features:

支持 DSL 創建 HTTP GET/POST/PUT/HEAD/DELETE/PATCH requests.
支持 Kotlin 協程
支持響應式(RxJava、Spring Reactor)
支持函數式
支持熔斷器(Resilience4j)
支持異步請求的取消
支持 Request、Response 的攔截器
提供常用的攔截器
支持自定義線程池
支持整合 Retrofit、Feign 框架
支持 Websocket 的實現、自動重連等
core 模塊只依賴 OkHttp，不依賴其他第三方庫

一. General

1.1 Basic

無需任何配置(零配置)即可直接使用，僅限於 Get 請求。

    "https://baidu.com".httpGet().use {
        println(it)
    }

或者需要依賴協程，也僅限於 Get 請求。

   "https://baidu.com".asyncGet()
       .await()
       .use {
           println(it)
       }

1.2 Config

配置 OkHttp 相關的參數以及攔截器，例如：

const val DEFAULT_CONN_TIMEOUT = 30

val loggingInterceptor by lazy {
    LogManager.logProxy(object : LogProxy {  // 必須要實現 LogProxy ，否則無法打印網絡請求的 request 、response
        override fun e(tag: String, msg: String) {
        }

        override fun w(tag: String, msg: String) {
        }

        override fun i(tag: String, msg: String) {
            println("$tag:$msg")
        }

        override fun d(tag: String, msg: String) {
            println("$tag:$msg")
        }
    })

    LoggingInterceptor.Builder()
        .loggable(true) // TODO: 發佈到生產環境需要改成false
        .request()
        .requestTag("Request")
        .response()
        .responseTag("Response")
//        .hideVerticalLine()// 隱藏豎線邊框
        .build()
}

val httpClient: HttpClient by lazy {
    HttpClientBuilder()
        .baseUrl("http://localhost:8080")
        .allTimeouts(DEFAULT_CONN_TIMEOUT.toLong(), TimeUnit.SECONDS)
        .addInterceptor(loggingInterceptor)
        .addInterceptor(CurlLoggingInterceptor())
        .serializer(GsonSerializer())
        .jsonConverter(GlobalRequestJSONConverter::class)
        .build()
}

配置完之後，就可以直接使用 httpClient

    httpClient.get{

        url {
            url = "/response-headers-queries"

            "param1" to "value1"
            "param2" to "value2"
        }

        header {
            "key1" to "value1"
            "key2" to "value2"
        }
    }.use {
        println(it)
    }

這裏的 url 需要和 baseUrl 組成完整的 url。比如：http://localhost:8080/response-headers-queries
當然，也可以使用 customUrl 替代 baseUrl + url 作爲完整的 url

1.3 AOP

針對所有 request、response 做一些類似 AOP 的行爲。

需要在構造 httpClient 時，調用 addRequestProcessor()、addResponseProcessor() 方法，例如：

val httpClientWithAOP by lazy {
    HttpClientBuilder()
        .baseUrl("http://localhost:8080")
        .allTimeouts(DEFAULT_CONN_TIMEOUT.toLong(), TimeUnit.SECONDS)
        .addInterceptor(loggingInterceptor)
        .serializer(GsonSerializer())
        .jsonConverter(GlobalRequestJSONConverter::class)
        .addRequestProcessor { _, builder ->
            println("request start")
            builder
        }
        .addResponseProcessor {
            println("response start")
        }
        .build()
}

這樣在進行 request、response 時，會分別打印"request start"和"response start"。

因爲在創建 request 之前，會處理所有的 RequestProcessor；在響應 response 之前，也會用內部的 ResponseProcessingInterceptor 攔截器來處理 ResponseProcessor。

RequestProcessor、ResponseProcessor 分別可以認爲是 request、response 的攔截器。

// a request interceptor
typealias RequestProcessor = (HttpClient, Request.Builder) -> Request.Builder

// a response interceptor
typealias ResponseProcessor = (Response) -> Unit

我們可以多次調用 addRequestProcessor() 、addResponseProcessor() 方法。

二. DSL

DSL 是okhttp-extension框架的特色。包含使用 DSL 創建各種 HTTP Request 和使用 DSL 結合聲明式編程。

2.1 HTTP Request

使用 DSL 支持創建GET/POST/PUT/HEAD/DELETE/PATCH

2.1.1 get

最基本的 get 用法

    httpClient.get{

        url {
            url = "/response-headers-queries"

            "param1" to "value1"
            "param2" to "value2"
        }

        header {
            "key1" to "value1"
            "key2" to "value2"
        }
    }.use {
        println(it)
    }

這裏的 url 需要和 baseUrl 組成完整的 url。比如：http://localhost:8080/response-headers-queries
當然，也可以使用 customUrl 替代 baseUrl + url 作爲完整的 url

2.1.2 post

基本的 post 請求如下：

    httpClient.post{

        url {
            url = "/response-body"
        }

        header {
            "key1" to "value1"
            "key2" to "value2"
        }

        body {
            form {
                "form1" to "value1"
                "form2" to "value2"
            }
        }
    }.use {
        println(it)
    }

支持 request body 爲 json 字符串

    httpClient.post{

        url {
            url = "/response-body"
        }

        body("application/json") {
            json {
                "key1" to "value1"
                "key2" to "value2"
                "key3" to "value3"
            }
        }
    }.use {
        println(it)
    }

支持單個/多個文件的上傳

    val file = File("/Users/tony/Downloads/xxx.png")

    httpClient.post{

        url {
            url = "/upload"
        }

        multipartBody {
            +part("file", file.name) {
                file(file)
            }
        }
    }.use {
        println(it)
    }

更多 post 相關的方法，歡迎使用者自行探索。

2.1.3 put

    httpClient.put{

        url {
            url = "/response-body"
        }

        header {
            "key1" to "value1"
            "key2" to "value2"
        }

        body("application/json") {
            string("content")
        }
    }.use {
        println(it)
    }

2.1.4 delete

    httpClient.delete{

        url {
            url = "/users/tony"
        }
    }.use {
        println(it)
    }

2.1.5 head

    httpClient.head{

        url {
            url = "/response-headers"
        }

        header {
            "key1" to "value1"
            "key2" to "value2"
            "key3" to "value3"
        }
    }.use {
        println(it)
    }

2.1.6 patch

    httpClient.patch{

        url {
            url = "/response-body"
        }

        header {
            "key1" to "value1"
            "key2" to "value2"
        }

        body("application/json") {
            string("content")
        }
    }.use {
        println(it)
    }

2.2 Declarative

像使用 Retrofit、Feign 一樣，在配置完 httpClient 之後，需要定義一個 ApiService 它用於聲明所調用的全部接口。ApiService 所包含的方法也是基於 DSL 的。例如：

class ApiService(client: HttpClient) : AbstractHttpService(client) {

    fun testGet(name: String) = get<Response> {
        url = "/sayHi/$name"
    }

    fun testGetWithPath(path: Map<String, String>) = get<Response> {
        url = "/sayHi/{name}"
        pathParams = Params.from(path)
    }

    fun testGetWithHeader(headers: Map<String, String>) = get<Response> {
        url = "/response-headers"
        headersParams = Params.from(headers)
    }

    fun testGetWithHeaderAndQuery(headers: Map<String, String>, queries: Map<String,String>) = get<Response> {
        url = "/response-headers-queries"
        headersParams = Params.from(headers)
        queriesParams = Params.from(queries)
    }

    fun testPost(body: Params) = post<Response> {
        url = "/response-body"
        bodyParams = body
    }

    fun testPostWithModel(model: RequestModel) = post<Response>{
        url = "/response-body"
        bodyModel = model
    }

    fun testPostWithJsonModel(model: RequestModel) = jsonPost<Response>{
        url = "/response-body-with-model"
        jsonModel = model
    }

    fun testPostWithResponseMapper(model: RequestModel) = jsonPost<ResponseData>{
        url = "/response-body-with-model"
        jsonModel = model
        responseMapper = ResponseDataMapper::class
    }
}

定義好 ApiService 就可以直接使用了，例如：

val apiService by lazy {
    ApiService(httpClient)
}

val requestModel = RequestModel()
apiService.testPostWithModel(requestModel).sync()

當然也支持異步，會返回CompletableFuture對象，例如：

val apiService by lazy {
    ApiService(httpClient)
}

val requestModel = RequestModel()
apiService.testPostWithModel(requestModel).async()

藉助於 Kotlin 擴展函數的特性，也支持返回 RxJava 的 Observable 對象等、Reactor 的 Flux/Mono 對象、Kotlin Coroutines 的 Flow 對象等等。

三. Interceptors

okhttp-extension框架帶有很多常用的攔截器

3.1 CurlLoggingInterceptor

將網絡請求轉換成 curl 命令的攔截器，便於後端同學調試排查問題。

以下面的代碼爲例：

    httpClient.get{

        url {
            url = "/response-headers-queries"

            "param1" to "value1"
            "param2" to "value2"
        }

        header {
            "key1" to "value1"
            "key2" to "value2"
        }
    }.use {
        println(it)
    }

添加了 CurlLoggingInterceptor 之後，打印結果如下：

curl:
╔══════════════════════════════════════════════════════════════════════════════════════════════════
║ curl -X GET -H "key1: value1" -H "key2: value2" "http://localhost:8080/response-headers-queries?param1=value1&param2=value2"
╚══════════════════════════════════════════════════════════════════════════════════════════════════

CurlLoggingInterceptor 默認使用 println 函數打印，可以使用相應的日誌框架進行替換。

3.2 SigningInterceptor

請求籤名的攔截器，支持對 query 參數進行簽名。

const val TIME_STAMP = "timestamp"
const val NONCE = "nonce"
const val SIGN = "sign"

private val extraMap:MutableMap<String,String> = mutableMapOf<String,String>().apply {
    this[TIME_STAMP] = System.currentTimeMillis().toString()
    this[NONCE]  = UUID.randomUUID().toString()
}

private val signingInterceptor = SigningInterceptor(SIGN, extraMap, signer = {
    val paramMap = TreeMap<String, String>()
    val url = this.url

    for (name in url.queryParameterNames) {
        val value = url.queryParameterValues(name)[0]?:""
        paramMap[name] = value
    }

    //增加公共參數
    paramMap[TIME_STAMP] = extraMap[TIME_STAMP].toString()
    paramMap[NONCE]  = extraMap[NONCE].toString()

    //所有參數自然排序後拼接
    var paramsStr = join("",paramMap.entries
        .filter { it.key!= SIGN }
        .map { entry -> String.format("%s", entry.value) })

    //生成簽名
    sha256HMAC(updateAppSecret,paramsStr)
})

3.3 TraceIdInterceptor

需要實現TraceIdProvider接口

interface TraceIdProvider {

    fun getTraceId():String
}

TraceIdInterceptor 會將 traceId 放入 http header 中。

3.4 OAuth2Interceptor

需要實現OAuth2Provider接口

interface OAuth2Provider {

    fun getOauthToken():String

    /**
     * 刷新token
     * @return String?
     */
    fun refreshToken(): String?
}

OAuth2Interceptor 會將 token 放入 http header 中，如果 token 過期，會調用 refreshToken() 方法進行刷新 token。

3.5 JWTInterceptor

需要實現JWTProvider接口

interface JWTProvider {

    fun getJWTToken():String

    /**
     * 刷新token
     * @return String?
     */
    fun refreshToken(): String?
}

JWTInterceptor 會將 token 放入 http header 中，如果 token 過期，會調用 refreshToken() 方法進行刷新 token。

3.6 LoggingInterceptor

可以使用我開發的okhttp-logging-interceptor將 http request、response 的數據格式化的輸出。

四. Coroutines

Coroutines 是 Kotlin 的特性，我們使用okhttp-extension也可以很好地利用 Coroutines。

4.1 Coroutines

例如，最基本的使用

   "https://baidu.com".asyncGet()
       .await()
       .use {
           println(it)
       }

亦或者

        httpClient.asyncGet{

            url{
                url = "/response-headers-queries"

                "param1" to "value1"
                "param2" to "value2"
            }

            header {
                "key1" to "value1"
                "key2" to "value2"
            }
        }.await().use {
            println(it)
        }

以及

        httpClient.asyncPost{

            url {
                url = "/response-body"
            }

            header {
                "key1" to "value1"
                "key2" to "value2"
            }

            body("application/json") {
                json {
                    "key1" to "value1"
                    "key2" to "value2"
                    "key3" to "value3"
                }
            }
        }.await().use{
            println(it)
        }

asyncGet\asyncPost\asyncPut\asyncDelete\asyncHead\asyncPatch 函數在coroutines模塊中，都是 HttpClient 的擴展函數，會返回Deferred<Response>對象。

同樣，他們也是基於 DSL 的。

4.2 Flow

coroutines模塊也提供了 flowGet\flowPost\flowPut\flowDelete\flowHead\flowPatch 函數，也是 HttpClient 的擴展函數，會返回Flow<Response>對象。

例如：

        httpClient.flowGet{

            url{
                url = "/response-headers-queries"

                "param1" to "value1"
                "param2" to "value2"
            }

            header {
                "key1" to "value1"
                "key2" to "value2"
            }
        }.collect {
            println(it)
        }

或者

        httpClient.flowPost{

            url {
                url = "/response-body"
            }

            header {
                "key1" to "value1"
                "key2" to "value2"
            }

            body("application/json") {
                json {
                    "key1" to "value1"
                    "key2" to "value2"
                    "key3" to "value3"
                }
            }
        }.collect{
            println(it)
        }

五. WebSocket

OkHttp 本身支持 WebSocket ，因此okhttp-extension對 WebSocket 做了一些增強，包括重連、連接狀態的監聽等。

5.1 Reconnect

在實際的應用場景中，WebSocket 的斷線是經常發生的。例如：網絡發生切換、服務器負載過高無法響應等都可能是 WebSocket 的斷線的原因。

客戶端一旦感知到長連接不可用，就應該發起重連。okhttp-extension的 ReconnectWebSocketWrapper 類是基於 OkHttp 的 WebSocket 實現的包裝類，具有自動重新連接的功能。

在使用該包裝類時，可以傳入自己實現的 WebSocketListener 來監聽 WebSocket 各個狀態以及對消息的接收，該類也支持對 WebSocket 連接狀態變化的監聽、支持設置重連的次數和間隔。

例如：

    // 支持重試的 WebSocket 客戶端
    ws = httpClient.websocket("http://127.0.0.1:9876/ws",listener = object : WebSocketListener() {

        override fun onOpen(webSocket: WebSocket, response: Response) {
            logger.info("connection opened...")

            websocket = webSocket

            disposable = Observable.interval(0, 15000,TimeUnit.MILLISECONDS) // 每隔 15 秒發一次業務上的心跳
                .subscribe({
                    heartbeat()
                }, {

                })
        }

        override fun onMessage(webSocket: WebSocket, text: String) {
            logger.info("received instruction: $text")
        }

        override fun onMessage(webSocket: WebSocket, bytes: ByteString) {
        }

        override fun onClosing(webSocket: WebSocket, code: Int, reason: String) {
            logger.info("connection closing: $code, $reason")

            websocket = null

            disposable?.takeIf { !it.isDisposed }?.let {
                it.dispose()
            }
        }

        override fun onClosed(webSocket: WebSocket, code: Int, reason: String) {
            logger.error("connection closed: $code, $reason")

            websocket = null

            disposable?.takeIf { !it.isDisposed }?.let {
                it.dispose()
            }
        }

        override fun onFailure(webSocket: WebSocket, t: Throwable, response: Response?) {
            logger.error("websocket connection error")

            websocket = null

            disposable?.takeIf { !it.isDisposed }?.let {
                it.dispose()
            }
        }
    },wsConfig = WSConfig())

5.2 onConnectStatusChangeListener

ReconnectWebSocketWrapper 支持對 WebSocket 連接狀態的監聽，只要實現onConnectStatusChangeListener即可。

    ws?.onConnectStatusChangeListener = {
        logger.info("${it.name}")
        status = it
    }

未完待續。
另外，如果你對 Kotlin 比較感興趣，歡迎去我的新書《Kotlin 進階實戰》去看看，剛剛在 10 月出版，書中融入了我多年使用 Kotlin 的實踐思考與經驗積累。

基於 Kotlin + OkHttp 實現易用且功能強大的網絡框架（一）一. General 二. DSL 三. Interceptors 四. Coroutines 五. WebSocket

Features:

一. General

1.1 Basic

1.2 Config

1.3 AOP

二. DSL

2.1 HTTP Request

2.1.1 get

2.1.2 post

2.1.3 put

2.1.4 delete

2.1.5 head

2.1.6 patch

2.2 Declarative

三. Interceptors

3.1 CurlLoggingInterceptor

3.2 SigningInterceptor

3.3 TraceIdInterceptor

3.4 OAuth2Interceptor

3.5 JWTInterceptor

3.6 LoggingInterceptor

四. Coroutines

4.1 Coroutines

4.2 Flow

五. WebSocket

5.1 Reconnect

5.2 onConnectStatusChangeListener

OpenCV + Kotlin 實現 USB 攝像頭(相機)實時畫面、拍照一. 業務背景二. 原先的實現方式以及痛點三. 使用 OpenCV 進行重構四. 總結

Java 多線程模式 —— Guarded Suspension 模式 Guarded Suspension 模式的介紹 Guarded Suspension 模式的使用總結

《Kotlin 進階實戰》及勘誤表本書的內容致謝勘誤

使用 Kotlin Compose Desktop 實現了一個簡易的"手機助手"

基於 Laplacian 實現簡單的圖像模糊檢測業務背景 Laplacian 算子圖像模糊檢測算法總結

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結

基於 Kotlin + OkHttp 實現易用且功能強大的網絡框架（一） 一. General 二. DSL 三. Interceptors 四. Coroutines 五. WebSocket

Features:

一. General

1.1 Basic

1.2 Config

1.3 AOP

二. DSL

2.1 HTTP Request

2.1.1 get

2.1.2 post

2.1.3 put

2.1.4 delete

2.1.5 head

2.1.6 patch

2.2 Declarative

三. Interceptors

3.1 CurlLoggingInterceptor

3.2 SigningInterceptor

3.3 TraceIdInterceptor

3.4 OAuth2Interceptor

3.5 JWTInterceptor

3.6 LoggingInterceptor

四. Coroutines

4.1 Coroutines

4.2 Flow

五. WebSocket

5.1 Reconnect

5.2 onConnectStatusChangeListener

基於 Kotlin + OkHttp 實現易用且功能強大的網絡框架（一）一. General 二. DSL 三. Interceptors 四. Coroutines 五. WebSocket