Files
mingli-utils/src/main/kotlin/com/mingliqiye/utils/http/okhttp/OkHttpUtils.kt
T
minglipro 51eb838a36
Gitea Actions Build / Build (push) Canceled after 0s
docs: 补全 src 全部 Kotlin KDoc 与 Java Javadoc,版本升级至 5.5.1
为所有缺失文档的公开声明补充中文 KDoc/Javadoc(含 exception、json、
springboot、tuple 生成类、MediaType 枚举项及测试),仅插入注释不改代码;
gradle.properties VERSIONS 5.4.4 -> 5.5.1。
2026-11-17 21:07:58 +08:00

323 lines
9.5 KiB
Kotlin

/*
* Copyright 2026 mingliqiye
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
* ProjectName mingli-utils
* ModuleName mingli-utils.main
* CurrentFile OkHttpUtils.kt
* LastUpdate 2026-11-09 19:18:03
* UpdateUser MingLiPro
*/
@file:JvmName("OkHttpUtils")
package com.mingliqiye.utils.http.okhttp
import com.mingliqiye.utils.http.MediaType
import com.mingliqiye.utils.http.okhttp
import com.mingliqiye.utils.json.api.JSONA
import com.mingliqiye.utils.json.api.base.JsonApi
import com.mingliqiye.utils.json.api.base.JsonApi.Companion.parse
import okhttp3.*
import okhttp3.HttpUrl.Companion.toHttpUrl
import okhttp3.RequestBody.Companion.toRequestBody
/**
* 将 OkHttp 的 [Response] 响应体解析为指定泛型类型的对象。
*
* 会读取并关闭响应体。未显式传入 [jsonApi] 时使用 [JSONA.jsonApi]。
*
* @param T 目标对象类型,由调用方通过 reified 推断
* @param jsonApi 可选的 [JsonApi] 实例;为 `null` 时使用 [JSONA.jsonApi]
* @return 解析后的对象实例
* @throws NullPointerException 未传入 [jsonApi] 且 [JSONA] 尚未注入实例时抛出
*/
inline fun <reified T> Response.json(jsonApi: JsonApi? = null): T = body.use {
(jsonApi ?: JSONA.jsonApi).parse<T>(it.bytes())
}
/**
* 读取 [Response] 响应体为字符串,并关闭响应体。
*
* 按响应 `Content-Type` 的 `charset` 解码,缺省 UTF-8;读取后响应体被关闭。
*
* @return 响应体内容字符串
*/
fun Response.text() = this.body.string()
/**
* 创建一个 [Request],通过 [calld] 配置 [Request.Builder]。
*
* @param calld 在 [Request.Builder] 上执行的配置块
* @return 构建完成的 [Request]
*/
fun newRequest(calld: Request.Builder.() -> Unit): Request =
Request.Builder().apply(calld).build()
/**
* 使用当前 [OkHttpClient] 创建一个 [Call],请求通过 [calld] 配置。
*
* 调用返回的 [Call] 的 `execute()` 或 `enqueue()` 才会真正发起请求。
*
* @param calld 在 [Request.Builder] 上执行的配置块
* @return 未执行的 [Call]
*/
fun OkHttpClient.newCall(calld: Request.Builder.() -> Unit): Call {
return this.newCall(newRequest(calld))
}
/**
* 使用当前 [OkHttpClient] 同步执行一次请求,请求通过 [calld] 配置。
*
* 注意:在 Android 主线程调用会抛出 `NetworkOnMainThreadException`。
*
* @param calld 在 [Request.Builder] 上执行的配置块
* @return 同步执行得到的 [Response]
* @throws java.io.IOException 网络或 I/O 失败时抛出
*/
fun OkHttpClient.newExecute(calld: Request.Builder.() -> Unit): Response {
return this.newCall(newRequest(calld)).execute()
}
/**
* 在 [Request.Builder] 上设置 URL,并通过 [calld] 配置查询参数。
*
* 示例:
* ```
* Request.Builder().url("https://example.com/api") {
* addQueryParameter("page", "1")
* }
* ```
*
* @param url 基础 URL 字符串
* @param calld 可选的 [HttpUrl.Builder] 配置块(如添加查询参数);为 `null` 时直接使用 [url]
* @return 当前 [Request.Builder],便于链式调用
*/
fun Request.Builder.url(
url: String,
calld: (HttpUrl.Builder.() -> Unit)? = null,
): Request.Builder {
return if (calld != null) {
this.url(url.toHttpUrl().newBuilder().apply { calld() }.build())
} else {
this.url(url.toHttpUrl())
}
}
/**
* 在 [Request.Builder] 上设置请求方法和字节数组请求体。
*
* @param method 请求方法
* @param body 请求体字节数组
* @param mediaType 可选的媒体类型;为 `null` 时不设置 Content-Type
* @param offset 起始偏移量,默认 0
* @param length 读取长度,默认从 [offset] 到 [body] 末尾
* @return 当前 [Request.Builder],便于链式调用
*/
fun Request.Builder.methodBody(
method: Method,
body: ByteArray,
mediaType: MediaType? = null,
offset: Int = 0,
length: Int = body.size - offset,
): Request.Builder {
require(offset >= 0 && length >= 0 && offset + length <= body.size) {
"offset/length 越界: offset=$offset, length=$length, size=${body.size}"
}
return method(method.name, body.toRequestBody(mediaType?.okhttp(), offset, length))
}
/**
* 在 [Request.Builder] 上设置请求方法,并将对象序列化为 JSON 作为请求体。
*
* @param method 请求方法
* @param body 待序列化的对象
* @param jsonApi 可选的 [JsonApi] 实例;为 `null` 时使用 [JSONA.jsonApi]
* @return 当前 [Request.Builder],便于链式调用
*/
fun Request.Builder.methodJsonBody(
method: Method,
body: Any,
jsonApi: JsonApi? = null,
): Request.Builder = methodBody(
method,
(jsonApi ?: JSONA.jsonApi).formatBytes(body),
MediaType.APPLICATION_JSON,
)
/**
* 在 [Request.Builder] 上设置 GET 方法,并将对象序列化为 JSON 作为请求体。
*
* 注意:GET 请求携带请求体在 HTTP 语义中不常见,部分服务端可能忽略或拒绝。
*
* @param body 待序列化的对象
* @param jsonApi 可选的 [JsonApi] 实例;为 `null` 时使用 [JSONA.jsonApi]
* @return 当前 [Request.Builder],便于链式调用
*/
fun Request.Builder.getJsonBody(
body: Any,
jsonApi: JsonApi? = null,
) = methodBody(
Method.GET,
(jsonApi ?: JSONA.jsonApi).formatBytes(body),
MediaType.APPLICATION_JSON,
)
/**
* 在 [Request.Builder] 上设置 POST 方法,并将对象序列化为 JSON 作为请求体。
*
* @param body 待序列化的对象
* @param jsonApi 可选的 [JsonApi] 实例;为 `null` 时使用 [JSONA.jsonApi]
* @return 当前 [Request.Builder],便于链式调用
*/
fun Request.Builder.postJsonBody(
body: Any,
jsonApi: JsonApi? = null,
) = methodBody(
Method.POST,
(jsonApi ?: JSONA.jsonApi).formatBytes(body),
MediaType.APPLICATION_JSON,
)
/**
* 在 [Request.Builder] 上设置 PUT 方法,并将对象序列化为 JSON 作为请求体。
*
* @param body 待序列化的对象
* @param jsonApi 可选的 [JsonApi] 实例;为 `null` 时使用 [JSONA.jsonApi]
* @return 当前 [Request.Builder],便于链式调用
*/
fun Request.Builder.putJsonBody(
body: Any,
jsonApi: JsonApi? = null,
) = methodBody(
Method.PUT,
(jsonApi ?: JSONA.jsonApi).formatBytes(body),
MediaType.APPLICATION_JSON,
)
/**
* 在 [Request.Builder] 上设置 DELETE 方法,并将对象序列化为 JSON 作为请求体。
*
* @param body 待序列化的对象
* @param jsonApi 可选的 [JsonApi] 实例;为 `null` 时使用 [JSONA.jsonApi]
* @return 当前 [Request.Builder],便于链式调用
*/
fun Request.Builder.deleteJsonBody(
body: Any,
jsonApi: JsonApi? = null,
) = methodBody(
Method.DELETE,
(jsonApi ?: JSONA.jsonApi).formatBytes(body),
MediaType.APPLICATION_JSON,
)
/**
* 在 [Request.Builder] 上设置 HEAD 方法,并将对象序列化为 JSON 作为请求体。
*
* 注意:HEAD 请求通常不应携带请求体,部分服务端可能忽略或拒绝。
*
* @param body 待序列化的对象
* @param jsonApi 可选的 [JsonApi] 实例;为 `null` 时使用 [JSONA.jsonApi]
* @return 当前 [Request.Builder],便于链式调用
*/
fun Request.Builder.headJsonBody(
body: Any,
jsonApi: JsonApi? = null,
) = methodBody(
Method.HEAD,
(jsonApi ?: JSONA.jsonApi).formatBytes(body),
MediaType.APPLICATION_JSON,
)
/**
* 在 [Request.Builder] 上设置 OPTIONS 方法,并将对象序列化为 JSON 作为请求体。
*
* @param body 待序列化的对象
* @param jsonApi 可选的 [JsonApi] 实例;为 `null` 时使用 [JSONA.jsonApi]
* @return 当前 [Request.Builder],便于链式调用
*/
fun Request.Builder.optionsJsonBody(
body: Any,
jsonApi: JsonApi? = null,
) = methodBody(
Method.OPTIONS,
(jsonApi ?: JSONA.jsonApi).formatBytes(body),
MediaType.APPLICATION_JSON,
)
/**
* 在 [Request.Builder] 上设置 QUERY 方法,并将对象序列化为 JSON 作为请求体。
*
* QUERY 是 HTTP 扩展方法,需服务端支持。
*
* @param body 待序列化的对象
* @param jsonApi 可选的 [JsonApi] 实例;为 `null` 时使用 [JSONA.jsonApi]
* @return 当前 [Request.Builder],便于链式调用
*/
fun Request.Builder.queryJsonBody(
body: Any,
jsonApi: JsonApi? = null,
) = methodBody(
Method.QUERY,
(jsonApi ?: JSONA.jsonApi).formatBytes(body),
MediaType.APPLICATION_JSON,
)
/**
* HTTP 请求方法枚举,供 [Request.Builder.methodBody] 等扩展使用。
*/
enum class Method {
/** GET 方法。 */
GET,
/** POST 方法。 */
POST,
/** PUT 方法。 */
PUT,
/** DELETE 方法。 */
DELETE,
/** HEAD 方法。 */
HEAD,
/** OPTIONS 方法。 */
OPTIONS,
/** QUERY 方法(HTTP 扩展方法,需服务端支持)。 */
QUERY,
}
/**
* 在 [Request.Builder] 上设置 POST 方法,使用空请求体。
*
* @return 当前 [Request.Builder],便于链式调用
*/
fun Request.Builder.post() = post(RequestBody.EMPTY)
/**
* 在 [Request.Builder] 上设置 PUT 方法,使用空请求体。
*
* @return 当前 [Request.Builder],便于链式调用
*/
fun Request.Builder.put() = put(RequestBody.EMPTY)
/**
* 在 [Request.Builder] 上设置 PATCH 方法,使用空请求体。
*
* @return 当前 [Request.Builder],便于链式调用
*/
fun Request.Builder.patch() = patch(RequestBody.EMPTY)