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/PATCHrequests. - 支持 Kotlin 协程
- 支持响应式(RxJava、Spring Reactor)
- 支持函数式
- 支持熔断器(Resilience4j)
- 支持异步请求的取消
- 支持 Request、Response 的拦截器
- 提供常用的拦截器
- 支持自定义线程池
- 支持整合 Retrofit、Feign 框架
- 支持 Websocket 的实现、自动重连等
- core 模块只依赖 OkHttp，不依赖其他第三方库
okhttp-extension.png
一. General
1.1 Basic
无需任何配置(零配置)即可直接使用，仅限于 Get 请求。
代码语言：javascript复制 "https://baidu.com".httpGet().use {
println(it)
}或者需要依赖协程，也仅限于 Get 请求。
代码语言：javascript复制 "https://baidu.com".asyncGet()
.await()
.use {
println(it)
}1.2 Config
配置 OkHttp 相关的参数以及拦截器，例如：
代码语言：javascript复制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
代码语言：javascript复制 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() 方法，例如：
代码语言：javascript复制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 的拦截器。
代码语言：javascript复制// 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 用法
代码语言：javascript复制 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 请求如下：
代码语言：javascript复制 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 字符串
代码语言：javascript复制 httpClient.post{
url {
url = "/response-body"
}
body("application/json") {
json {
"key1" to "value1"
"key2" to "value2"
"key3" to "value3"
}
}
}.use {
println(it)
}支持单个/多个文件的上传
代码语言：javascript复制 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
代码语言：javascript复制 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
代码语言：javascript复制 httpClient.delete{
url {
url = "/users/tony"
}
}.use {
println(it)
}2.1.5 head
代码语言：javascript复制 httpClient.head{
url {
url = "/response-headers"
}
header {
"key1" to "value1"
"key2" to "value2"
"key3" to "value3"
}
}.use {
println(it)
}2.1.6 patch
代码语言：javascript复制 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 的。例如：
代码语言：javascript复制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 就可以直接使用了，例如：
代码语言：javascript复制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 命令的拦截器，便于后端同学调试排查问题。
以下面的代码为例：
代码语言：javascript复制 httpClient.get{
url {
url = "/response-headers-queries"
"param1" to "value1"
"param2" to "value2"
}
header {
"key1" to "value1"
"key2" to "value2"
}
}.use {
println(it)
}添加了 CurlLoggingInterceptor 之后，打印结果如下：
代码语言：javascript复制curl:
╔══════════════════════════════════════════════════════════════════════════════════════════════════
║ curl -X GET -H "key1: value1" -H "key2: value2" "http://localhost:8080/response-headers-queries?param1=value1¶m2=value2"
╚══════════════════════════════════════════════════════════════════════════════════════════════════CurlLoggingInterceptor 默认使用 println 函数打印，可以使用相应的日志框架进行替换。
3.2 SigningInterceptor
请求签名的拦截器，支持对 query 参数进行签名。
代码语言：javascript复制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
例如，最基本的使用
代码语言：javascript复制 "https://baidu.com".asyncGet()
.await()
.use {
println(it)
}亦或者
代码语言：javascript复制 httpClient.asyncGet{
url{
url = "/response-headers-queries"
"param1" to "value1"
"param2" to "value2"
}
header {
"key1" to "value1"
"key2" to "value2"
}
}.await().use {
println(it)
}以及
代码语言：javascript复制 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)
}asyncGetasyncPostasyncPutasyncDeleteasyncHeadasyncPatch 函数在coroutines模块中，都是 HttpClient 的扩展函数，会返回Deferred<Response>对象。
同样，他们也是基于 DSL 的。
4.2 Flow
coroutines模块也提供了 flowGetflowPostflowPutflowDeleteflowHeadflowPatch 函数，也是 HttpClient 的扩展函数，会返回Flow<Response>对象。
例如：
代码语言：javascript复制 httpClient.flowGet{
url{
url = "/response-headers-queries"
"param1" to "value1"
"param2" to "value2"
}
header {
"key1" to "value1"
"key2" to "value2"
}
}.collect {
println(it)
}或者
代码语言：javascript复制 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 连接状态变化的监听、支持设置重连的次数和间隔。
例如：
代码语言：javascript复制 // 支持重试的 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
}
