1. 为什么我要自己封装一层 OkHttp做过几个线上项目之后我对“网络层”这件事的看法会变得很务实它不该是每次开新项目都要重新纠结一遍的东西也不该是随手在 Activity 里 new 一个 OkHttpClient 就完事的临时方案。OkHttp 极简封装这个事说白了就是把 OkHttp 这头性能猛兽关进一个规整的笼子里对外只留几个干净利落的入口对内把连接复用、超时、日志、错误归一化这些脏活累活一次性处理掉。而AndroidKTX的思路则是用 Kotlin 的扩展函数、顶层函数、DSL 这些语法糖把这层封装做得足够薄、足够顺手让调用方写起来像在写伪代码。我先说清楚这篇东西适合谁看。如果你刚开始接触 Android 网络请求只会照着教程抄 Retrofit 的注解那这篇能帮你理解底下到底发生了什么如果你已经用过 OkHttp 但每次都在重复写 Callback、重复解析错误码、重复处理线程切换那这篇正好对上你的痛点如果你是那种“网络层必须自己掌控”的老手也可以看看我在参数取舍和异常归一化上的处理方式挑能用的拿走。核心关键词就三个OkHttp 封装、Kotlin 扩展、请求归一化全文都围绕它们展开。它解决的问题其实很具体。原生 OkHttp 用起来是这样的构造 Request、拿到 Call、enqueue 一个 Callback、在 onFailure 和 onResponse 里分别处理、自己判断 response.isSuccessful、自己读 body.string()、自己切主线程、自己关 ResponseBody。一个接口这么写还行十个接口就是十份几乎一样的样板代码而且每一份都可能在某处漏掉 close()埋下连接泄漏的隐患。封装的目标就是把这些重复动作收敛成一次让业务代码只关心“我要什么数据”和“拿到数据后干什么”。我选择“极简”而不是“大而全”是有取舍的。市面上有些封装库功能很全拦截器链、缓存策略、重试机制、上传下载进度全都包了但代价是学习成本高、出问题时排查链路长。我的判断是网络层的封装应该薄到你能一眼看穿它在干什么超出这个厚度的功能要么用 OkHttp 原生拦截器解决要么用 Retrofit 这类成熟方案不要自己再造一遍。这篇分享的就是这条“薄封装”路线的完整落地过程。2. 整体设计与思路拆解2.1 分层结构三层各管一件事我把整个网络层拆成三层每层职责单一边界清晰。最底层是Client 单例层全局只维护一个 OkHttpClient 实例负责连接池、超时、拦截器的统一配置中间是请求构建层用 Kotlin 的扩展函数把 URL、方法、参数、请求体这些要素组装成 Request最上层是回调归一化层把 OkHttp 原始的 Callback 包装成一个统一的 Result 类型成功和失败都走同一条出口。这么分层的好处是改动成本低。比如某天要加一个统一的请求头我只动 Client 层的拦截器要改错误码的映射规则我只动归一化层业务方完全无感。反过来如果所有逻辑揉在一个工具类里改一处就可能牵连一片这在多人协作的项目里是灾难。为什么坚持单例 Client因为 OkHttp 的连接池、线程池、DNS 缓存都是绑定在 OkHttpClient 实例上的。每次请求 new 一个 Client等于每次请求都新建一套连接池连接复用彻底失效还会额外占用线程资源。官方文档也明确建议共享实例。这一点很多人知道但实际项目里还是能看到在工具方法里 new OkHttpClient 的写法属于典型的“知道但没做到”。2.2 为什么用扩展函数而不是继承或工具类Kotlin 的扩展函数在这里是天然契合的。传统 Java 写法要么搞一个HttpUtils.request(url, callback)的静态工具类要么继承 OkHttpClient 做子类。前者的问题是参数列表会越来越长后者的问题是继承破坏了 OkHttpClient 的不可变性设计而且子类能改的东西太多容易失控。扩展函数的写法是这样的给OkHttpClient加一个get、post之类的扩展调用时就是client.get(url) { ... }读起来像 OkHttp 原生 API 的自然延伸但内部已经帮你把 Request 构建、enqueue、线程切换都做完了。它不改变原有类型不引入继承层级还能享受 IDE 的自动补全。这就是AndroidKTX风格的精髓不发明新概念只是让原有 API 更好用。还有一个细节扩展函数可以配合 lambda 的尾随写法把回调放在括号外面视觉上更接近“配置块”的感觉。比如client.post(url) { body(name, value) }.enqueue { result - ... }这种链式加尾随 lambda 的组合可读性比一堆具名参数强得多。2.3 回调归一化的核心一个 Result 类型收口原生 OkHttp 的 Callback 有两个方法onFailure 和 onResponse而且 onResponse 里还得自己判断 isSuccessful。这意味着每个调用点都要写两套分支还要处理“HTTP 200 但业务码是错误”这种二级判断。我的做法是定义一个密封类 Result只有 Success 和 Failure 两个子类Failure 里再细分网络异常、HTTP 错误、解析错误、业务错误。sealed class NetResultout T { data class SuccessT(val data: T) : NetResultT() data class Failure(val type: ErrorType, val code: Int -1, val message: String?) : NetResultNothing() } enum class ErrorType { NETWORK, HTTP, PARSE, BUSINESS, UNKNOWN }这样调用方只需要一个 when 表达式就能覆盖所有情况编译器还会强制你处理分支不会漏掉。为什么用密封类而不是普通的数据类加布尔标志因为密封类的 when 是穷尽的新增一个错误类型时所有没处理的地方会直接编译报错这是编译期就能发现的遗漏比运行时才暴露强太多。2.4 线程模型的约定OkHttp 的 enqueue 本身就在后台线程执行回调但 Android 开发里更新 UI 必须在主线程。我的封装里统一在回调出口切回主线程调用方拿到的 Result 一定是在主线程上不需要自己再 post 一次。这个约定必须写死在封装里不能留给调用方去记否则总有人忘记然后在后台线程里改 UI 导致崩溃。这里有个容易忽略的点切主线程用的是 Handler(Looper.getMainLooper())而不是 Kotlin 协程的 Dispatchers.Main。原因是这层封装要保持对协程的无依赖方便那些还没上协程的项目直接用。如果项目已经全面协程化那更推荐用 suspendCancellableCoroutine 把回调桥接成挂起函数这个我在后面会单独讲。3. 核心细节解析与实操要点3.1 Client 单例的初始化参数怎么定OkHttpClient 的构建参数不少但真正需要根据项目调的其实就几个。我把常用的列出来附上我的取值和理由。参数我的取值选择理由connectTimeout10s移动网络下建连偶尔慢5s 太激进容易误判失败readTimeout15s读超时要覆盖服务端处理时间太短会误杀慢接口writeTimeout15s上传场景需要和读超时对齐便于记忆retryOnConnectionFailuretrue默认开启对弱网下的偶发失败有兜底作用connectionPool默认即可OkHttp 默认 5 个空闲连接、5 分钟保活够用超时时间的设定不是拍脑袋。connectTimeout 太短弱网下 TCP 握手还没完成就超时了用户看到的是“网络错误”但其实是自己设太严太长又会让真正的失败迟迟不返回用户干等。10 秒是我在多个项目里试出来的平衡点。readTimeout 要大于服务端最慢接口的 P99 耗时这个得跟后端确认不能自己猜。初始化代码用懒加载单例避免在 Application 启动时同步构建拖慢冷启动object HttpClient { val instance: OkHttpClient by lazy { OkHttpClient.Builder() .connectTimeout(10, TimeUnit.SECONDS) .readTimeout(15, TimeUnit.SECONDS) .writeTimeout(15, TimeUnit.SECONDS) .retryOnConnectionFailure(true) .addInterceptor(HeaderInterceptor()) .addInterceptor(LogInterceptor()) .build() } }注意日志拦截器只在 Debug 构建里加Release 包里带上日志拦截器不仅有性能开销还可能把敏感信息打进日志。用 BuildConfig.DEBUG 判断别图省事全局加。3.2 请求构建层的扩展函数设计请求构建的核心是把“方法 URL 参数 请求体”这四要素用最少的代码表达出来。我设计了几个扩展函数覆盖最常见的 GET 和 POST 场景。GET 带查询参数是最常见的。原生写法要自己拼 URL 或者用 HttpUrl.Builder封装后应该是这样fun OkHttpClient.get(url: String, params: MapString, String emptyMap()): Request { val httpUrl url.toHttpUrlOrNull()?.newBuilder()?.apply { params.forEach { (k, v) - addQueryParameter(k, v) } }?.build() ?: throw IllegalArgumentException(invalid url: $url) return Request.Builder().url(httpUrl).get().build() }这里用toHttpUrlOrNull而不是字符串拼接是因为字符串拼接遇到中文、空格、特殊字符时容易出问题HttpUrl 会自动做百分号编码省心且正确。参数用 Map 传顺序无关调用方不用关心拼接顺序。POST 表单和 JSON 是两大主力。表单用 FormBodyJSON 用 RequestBody.create 配合 MediaType。我把 MediaType 抽成常量避免每次手写字符串写错private val MEDIA_JSON application/json; charsetutf-8.toMediaType() fun OkHttpClient.postJson(url: String, json: String): Request Request.Builder() .url(url) .post(json.toRequestBody(MEDIA_JSON)) .build() fun OkHttpClient.postForm(url: String, params: MapString, String): Request { val form FormBody.Builder().apply { params.forEach { (k, v) - add(k, v) } }.build() return Request.Builder().url(url).post(form).build() }提示JSON 的 charset 一定要写 utf-8不写的话某些服务端会按 ISO-8859-1 解析中文直接乱码。这个坑我踩过一次排查了半天才发现是 MediaType 少了 charset。3.3 回调归一化层的实现细节归一化层要做三件事把 Response 转成 Result、把异常分类、把线程切回主线程。先看整体骨架fun T Request.enqueue( parser: (String) - T, callback: (NetResultT) - Unit ) { HttpClient.instance.newCall(this).enqueue(object : Callback { override fun onFailure(call: Call, e: IOException) { postToMain { callback(NetResult.Failure(ErrorType.NETWORK, message e.message)) } } override fun onResponse(call: Call, response: Response) { response.use { resp - if (!resp.isSuccessful) { postToMain { callback(NetResult.Failure(ErrorType.HTTP, resp.code, resp.message)) } return } val body resp.body?.string() if (body.isNullOrEmpty()) { postToMain { callback(NetResult.Failure(ErrorType.PARSE, message empty body)) } return } try { val data parser(body) postToMain { callback(NetResult.Success(data)) } } catch (e: Exception) { postToMain { callback(NetResult.Failure(ErrorType.PARSE, message e.message)) } } } } }) }几个关键点值得展开。第一response.use { }是必须的ResponseBody 是流不关闭会泄漏连接OkHttp 的连接池会被占满后续请求全部排队等待。这是封装层最容易漏的地方因为原生写法里很多人也漏。第二parser 用函数式参数传入让调用方决定怎么解析封装层不绑定具体的 JSON 库Gson、Moshi、kotlinx.serialization 都能接。第三所有回调都经过 postToMain保证线程一致。postToMain 的实现很简单但要注意复用 Handler 实例不要每次 newprivate val mainHandler Handler(Looper.getMainLooper()) private fun postToMain(block: () - Unit) { if (Looper.myLooper() Looper.getMainLooper()) block() else mainHandler.post(block) }判断当前是否已在主线程是的话直接执行省一次 post 的调度开销。这个优化在回调频繁的场景下能减少主线程消息队列的压力。3.4 拦截器请求头和日志的统一处理请求头拦截器负责给每个请求加上公共头比如版本号、设备标识、语言。这些信息每个接口都要带放在拦截器里一次配置业务方不用管class HeaderInterceptor : Interceptor { override fun intercept(chain: Interceptor.Chain): Response { val origin chain.request() val newRequest origin.newBuilder() .header(X-App-Version, BuildConfig.VERSION_NAME) .header(X-Platform, android) .build() return chain.proceed(newRequest) } }日志拦截器负责打印请求和响应方便调试。但要注意两点一是响应体只能读一次日志拦截器读了之后后续的解析就拿不到内容了所以要用response.peekBody(Long.MAX_VALUE)来“偷看”而不消耗流二是大文件下载时不要打印完整 body会撑爆日志。class LogInterceptor : Interceptor { override fun intercept(chain: Interceptor.Chain): Response { val request chain.request() val response chain.proceed(request) val bodyString response.peekBody(1024 * 1024).string() Log.d(HTTP, ${request.method} ${request.url} - ${response.code} $bodyString) return response } }注意peekBody 的参数是最大读取字节数设成 1MB 是为了防止超大响应把内存撑爆。真正的大文件响应日志里只留状态码和长度就够了。4. 实操过程与核心环节实现4.1 从零搭一个可运行的请求链路光看代码片段不够我把完整的落地步骤走一遍你可以照着搭。第一步在模块的 build.gradle 里加 OkHttp 依赖版本选当前稳定版即可注意 OkHttp 4.x 之后是 Kotlin 写的和 Kotlin 项目天然兼容。第二步建一个 HttpClient 单例对象把 Client 的构建和拦截器配置放进去。第三步写扩展函数文件把 get、postJson、postForm 这些方法集中放方便查找。第四步写归一化层的 enqueue 扩展和 NetResult 定义。第五步在业务里调用验证。业务调用的样子应该是这样的我拿一个获取用户信息的接口举例client.get(https://api.example.com/user/info, mapOf(uid to 1001)) .enqueue( parser { body - Gson().fromJson(body, UserInfo::class.java) } ) { result - when (result) { is NetResult.Success - renderUser(result.data) is NetResult.Failure - showError(result.type, result.message) } }对比原生写法省掉了 Request 构建、Callback 实现、isSuccessful 判断、body 读取、线程切换、异常捕获这一整套业务代码只剩“发请求”和“处理结果”两件事。这就是封装的价值所在把不变的部分固化把变化的部分留给业务。4.2 参数计算超时与重试的量化依据超时时间不能凭感觉我给一个可操作的估算方法。先让后端提供核心接口的响应时间分布拿到 P50 和 P99 两个值。readTimeout 取 P99 的 1.5 倍左右留出网络抖动和偶发慢查询的余量。比如某接口 P99 是 800ms那 readTimeout 设 1.2s 到 1.5s 就够没必要设 15s。但要注意这是针对单个接口的精细设置全局默认值还是要保守一些因为不同接口差异大全局设太紧会误杀慢接口。connectTimeout 的估算依据是 TCP 三次握手加 TLS 握手的耗时。移动网络下这个值波动很大弱网时可能到 3 到 5 秒。设 10 秒是给极端情况留余量正常网络下根本用不到这么久因为握手成功就返回了超时值只是上限。重试这块OkHttp 的 retryOnConnectionFailure 只对连接层面的失败重试比如路由切换、连接被重置它不会重试 HTTP 5xx 错误。业务层的重试要自己做而且要想清楚哪些请求能重试。GET 这类幂等请求重试是安全的POST 创建订单这种非幂等请求重试可能导致重复下单必须谨慎。我的建议是默认不重试需要重试的接口显式声明。4.3 协程桥接给已经协程化的项目如果项目已经全面用协程回调式的封装用起来会别扭。这时候加一个 suspend 扩展把回调桥接成挂起函数代码会更线性suspend fun T Request.await(parser: (String) - T): NetResultT suspendCancellableCoroutine { cont - enqueue(parser) { result - if (cont.isActive) cont.resume(result) } cont.invokeOnCancellation { // 这里可以取消对应的 Call需要把 Call 引用传出来 } }调用方就变成val result request.await(parser)配合 try-catch 或者 when 处理。这里有个细节suspendCancellableCoroutine 支持取消但要让取消真正生效得把 Call 对象暴露出来在 invokeOnCancellation 里调 call.cancel()。否则协程取消了底层请求还在跑白白浪费流量。这个点很多桥接代码都漏了属于“看起来能用但不够严谨”的典型。4.4 上传和下载的极简处理上传文件用 MultipartBody封装一个扩展把文件路径和表单字段一起传fun OkHttpClient.upload( url: String, file: File, fields: MapString, String emptyMap() ): Request { val builder MultipartBody.Builder().setType(MultipartBody.FORM) fields.forEach { (k, v) - builder.addFormDataPart(k, v) } builder.addFormDataPart( file, file.name, file.asRequestBody(application/octet-stream.toMediaType()) ) return Request.Builder().url(url).post(builder.build()).build() }下载则要注意流式写入不能把整个文件读进内存。用 response.body?.byteStream() 配合文件输出流边读边写同时可以算进度。这里的关键是缓冲区大小8KB 是常见取值太小系统调用频繁太大内存占用高8KB 在两者之间比较平衡。提示上传大文件时writeTimeout 要相应调大否则传到一半超时了。可以针对上传请求单独构建一个 Client或者用 Request 级别的超时设置OkHttp 支持 per-call timeout。5. 常见问题与排查技巧实录5.1 连接泄漏最隐蔽也最致命连接泄漏的表现是应用跑一段时间后所有网络请求都变慢甚至超时但重启应用又恢复正常。根因几乎都是 ResponseBody 没关闭。OkHttp 的连接池有上限默认 5 个空闲连接泄漏的连接一直占着不释放新请求只能排队等等到超时。排查方法在 Debug 包里给 Client 加一个 EventListener监听 callEnd 和 connectionReleased 事件对比 callStart 和 callEnd 的数量如果 callEnd 明显少于 callStart就是有 Call 没走完。另一个办法是看 OkHttp 的 connectionPool 状态反射拿到的连接数持续增长就是泄漏信号。预防手段就是封装层统一用response.use { }业务方拿不到原始 Response从源头上杜绝漏关。这也是我坚持归一化层不暴露 Response 的原因之一。5.2 主线程卡顿回调里做了重活封装层切主线程是好事但也带来一个副作用调用方容易在回调里直接做耗时操作比如解析大 JSON、写数据库因为“反正已经在主线程了顺手就做了”。结果就是主线程卡顿甚至 ANR。我的处理原则是封装层只负责切线程不负责防呆。但我会在文档和示例里明确写清楚回调里只做 UI 更新重活要么在 parser 里做parser 在后台线程执行要么自己切到 IO 线程。parser 在后台执行这个设计很关键它让 JSON 解析这种 CPU 密集操作天然避开了主线程。5.3 错误分类不准网络异常和 HTTP 错误混淆新手常犯的错误是把所有失败都当成“网络错误”提示给用户。实际上 onFailure 才是网络层异常连不上、超时、DNS 失败onResponse 里 isSuccessful 为 false 是 HTTP 层错误4xx、5xx两者对用户的提示应该不同。前者提示“网络不给力请检查网络”后者要根据状态码区分401 提示登录失效500 提示服务异常。我在 NetResult 里用 ErrorType 明确区分就是为了让调用方能给出精准提示。这个分类看着简单但实际项目里能把错误提示做准的并不多很多 App 不管什么错都弹“网络错误”用户体验很差。5.4 常见问题速查表现象可能原因排查方向请求一直超时连接泄漏或线程池耗尽检查 ResponseBody 是否关闭中文乱码MediaType 缺 charset补上 charsetutf-8回调不执行在主线程同步调用 enqueue 后又阻塞等待不要在回调里做同步等待日志里 body 为空日志拦截器消耗了流改用 peekBody上传大文件失败writeTimeout 太短单独调大上传超时取消后请求还在跑协程桥接没调 call.cancel在 invokeOnCancellation 里取消5.5 几个我踩过的坑第一个坑是拦截器顺序。多个拦截器时addInterceptor 的顺序决定了执行顺序请求头拦截器要放在日志拦截器前面否则日志里看不到加的头。应用拦截器和网络拦截器的区别也要搞清楚前者只走一次后者可能因为重定向走多次日志一般用应用拦截器。第二个坑是 HTTPS 证书校验。有些测试环境用自签证书直接请求会抛 SSLHandshakeException。生产环境绝对不能信任所有证书但测试环境可以配一个只信任特定证书的 TrustManager且这个配置要严格隔离在 Debug 构建里。第三个坑是并发请求的线程安全。Gson 实例是线程安全的可以全局复用一个但如果你用的是某些非线程安全的解析器每次请求 new 一个更稳妥。这个细节在封装 parser 时要考虑进去别让调用方踩坑。6. 这套封装后续还能怎么长这套极简封装落地之后我在几个项目里用了大半年稳定性没问题代码量比原生写法少了大概六成。它不是一个功能完备的网络框架而是一个“够用且看得懂”的底座。往上长的话有几个方向可以按需扩展。一是缓存策略。OkHttp 原生支持 Cache配一个 Cache 实例加上 Cache-Control 头就能实现 HTTP 缓存不需要自己写。二是请求重试。可以加一个重试拦截器但只对幂等请求生效且要限制重试次数避免雪崩。三是统一的 loading 和错误弹窗。这个不建议塞进网络层网络层保持纯粹UI 层的反馈交给调用方或者一个独立的 UI 状态管理模块。我个人在实际操作中的体会是网络层的封装最忌讳“过度设计”。一开始就想把所有场景都覆盖结果封装越来越厚最后没人看得懂出问题也不敢改。反而是这种薄薄一层、职责清晰的封装用起来最踏实改起来最放心。每次想加功能之前先问自己一句这个功能是网络层该管的还是业务层该管的想清楚这个封装就不会跑偏。