当前位置：首页 > news >正文

OkHttpClient 详解（Android/Java 最常用 HTTP 客户端）

news 2026/5/27 12:26:39

OkHttp是 Square 公司开发的高效、轻量、稳定的 HTTP/HTTPs 客户端，是 Android 开发、Java 后端最主流的网络请求库，替代了原生的 HttpURLConnection。

它的核心优势：

支持 HTTP/2、连接池、GZIP 自动压缩、缓存
同步 / 异步请求、拦截器（日志、请求头统一处理）
超时、重连、错误处理完善
安卓项目几乎必用，也是 Retrofit 的底层依赖

一、快速集成（Gradle）

1. Android / Java 项目依赖

最新稳定版（以官方为准）：

gradle

// OkHttp 核心 implementation 'com.squareup.okhttp3:okhttp:4.12.0' // 可选：日志拦截器（查看请求/响应日志） implementation 'com.squareup.okhttp3:logging-interceptor:4.12.0'

2. 权限（Android 必备）

在AndroidManifest.xml添加：

xml

<uses-permission android:name="android.permission.INTERNET" />

二、基础使用（最常用 4 种请求）

1. 创建全局 OkHttp 实例（推荐单例）

OkHttp 官方强烈建议全局单例，避免重复创建连接池导致性能问题：

java

运行

import okhttp3.OkHttpClient; import java.util.concurrent.TimeUnit; public class HttpUtil { // 全局单例 OkHttpClient public static final OkHttpClient OK_HTTP_CLIENT = new OkHttpClient.Builder() .connectTimeout(10, TimeUnit.SECONDS) // 连接超时 .readTimeout(10, TimeUnit.SECONDS) // 读取超时 .writeTimeout(10, TimeUnit.SECONDS) // 写入超时 // .addInterceptor(new LogInterceptor()) // 自定义拦截器 .build(); }

2. GET 请求（异步 → 安卓推荐）

java

运行

// 1. 构建 Request Request request = new Request.Builder() .url("https://api.github.com/users/octocat") .get() // GET 请求（默认可不写） .addHeader("token", "xxx") // 请求头 .build(); // 2. 异步请求（不阻塞主线程） HttpUtil.OK_HTTP_CLIENT.newCall(request).enqueue(new Callback() { @Override public void onFailure(Call call, IOException e) { // 请求失败：网络错误、超时等 e.printStackTrace(); } @Override public void onResponse(Call call, Response response) throws IOException { // 请求成功 if (response.isSuccessful()) { String result = response.body().string(); // 处理结果 } response.close(); // 必须关闭 } });

3. POST 请求（表单提交）

java

运行

// 构建表单参数 RequestBody formBody = new FormBody.Builder() .add("username", "test") .add("password", "123456") .build(); // 构建请求 Request request = new Request.Builder() .url("https://xxx.com/login") .post(formBody) .build(); // 执行请求（同上异步）

4. POST 请求（JSON 提交）

java

运行

// JSON 字符串 String json = "{\"name\":\"okhttp\",\"age\":18}"; // 构建请求体 RequestBody requestBody = RequestBody.create( json, MediaType.parse("application/json; charset=utf-8") ); Request request = new Request.Builder() .url("https://xxx.com/api") .post(requestBody) .build();

三、高级功能

1. 日志拦截器（调试神器）

添加依赖后直接使用，可打印完整请求 / 响应：

java

运行

HttpLoggingInterceptor logging = new HttpLoggingInterceptor(); logging.setLevel(HttpLoggingInterceptor.Level.BODY); // 打印全部信息 OkHttpClient client = new OkHttpClient.Builder() .addInterceptor(logging) .build();

2. 拦截器统一处理（请求头、Token）

java

运行

public class HeaderInterceptor implements Interceptor { @Override public Response intercept(Chain chain) throws IOException { Request original = chain.request(); // 所有请求统一添加请求头 Request newRequest = original.newBuilder() .header("Content-Type", "application/json") .header("Authorization", "Bearer " + getToken()) .method(original.method(), original.body()) .build(); return chain.proceed(newRequest); } }

3. 文件上传

java

运行

// 文件 File file = new File("path/test.jpg"); // 构建多部分请求体 RequestBody requestBody = new MultipartBody.Builder() .setType(MultipartBody.FORM) .addFormDataPart("file", file.getName(), RequestBody.create(file, MediaType.parse("image/jpeg"))) .build(); Request request = new Request.Builder() .url("https://xxx.com/upload") .post(requestBody) .build();

四、注意事项（必看）

response.body().string()只能调用一次内部是流，读取后会关闭，多次调用会抛异常。
Android 不能在主线程做同步请求同步execute()会触发NetworkOnMainThreadException，必须用异步enqueue()。
必须关闭 Response否则会造成资源泄漏，建议try-finally关闭。
单例使用不要每次请求都new OkHttpClient()。