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，不依赖其他第三方库

okhttp-extension.png

一. 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 + OkHttp 实现易用且功能强大的网络框架（一）

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

热门文章

最新文章

相关课程

相关电子书

相关实验场景

热门

活动广场

任务中心

开发者评测

高校计划

乘风者计划

训练营

阿里云MVP

话题

直播

下载

镜像站

技术资料

插件

基于 Kotlin + OkHttp 实现易用且功能强大的网络框架（一）

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

热门文章

最新文章

相关课程

相关电子书

相关实验场景