OkHttp：Android HTTP客户端入门指南

什么是OkHttp？

OkHttp是一个为Android应用和Java虚拟机打造的HTTP客户端！它的设计理念是高效、简洁且强大（这三点真的很难同时做到）。如果你正在开发Android应用，或者任何需要网络请求的Java程序，OkHttp绝对值得你花时间学习。

为什么我们需要OkHttp？直接用HttpURLConnection不行吗？当然可以！但OkHttp提供了更多便利：

• 支持HTTP/2，允许所有对同一主机的请求共享一个socket
• 连接池减少请求延迟
• 透明的GZIP压缩减少下载数据量
• 响应缓存避免重复请求

最重要的是——它处理了很多网络疑难杂症，比如那些讨厌的握手失败、慢速服务器连接等等。

开始使用OkHttp

添加依赖

首先，我们需要在项目中添加OkHttp依赖。对于Gradle项目：

dependencies { implementation 'com.squareup.okhttp3:okhttp:4.10.0' }

对于Maven项目：

<dependency> <groupId>com.squareup.okhttp3</groupId> <artifactId>okhttp</artifactId> <version>4.10.0</version> </dependency>

注意版本号可能会变化，建议查看OkHttp官方仓库获取最新版本。

创建OkHttpClient实例

OkHttpClient是所有请求的核心，它处理连接池、配置等。最佳实践是在应用中创建一个单例：

java OkHttpClient client = new OkHttpClient();

这个默认配置对大多数应用来说已经足够好了！但如果你需要自定义，可以使用Builder模式：

java OkHttpClient client = new OkHttpClient.Builder() .connectTimeout(10, TimeUnit.SECONDS) .readTimeout(30, TimeUnit.SECONDS) .build();

发送GET请求

GET请求是最常见的HTTP请求类型，用于从服务器获取数据。使用OkHttp发送GET请求非常简单：

```java // 创建请求对象 Request request = new Request.Builder() .url("https://api.example.com/data") .build();

// 执行请求 try (Response response = client.newCall(request).execute()) { if (!response.isSuccessful()) throw new IOException("请求失败: " + response);

} catch (IOException e) { e.printStackTrace(); } ```

注意这里使用了try-with-resources语句来自动关闭响应体（这是个好习惯！）。

异步GET请求

上面的例子在当前线程执行请求，可能导致UI冻结（如果在主线程调用）。OkHttp提供了异步API：

```java Request request = new Request.Builder() .url("https://api.example.com/data") .build();

client.newCall(request).enqueue(new Callback() { @Override public void onFailure(Call call, IOException e) { e.printStackTrace(); }

}); ```

这种方式不会阻塞调用线程，适合在Android应用中使用。但要注意，回调方法运行在OkHttp的工作线程中，如果需要更新UI，要切换到主线程。

发送POST请求

POST请求用于向服务器提交数据。OkHttp让POST请求变得简单：

```java // 创建请求体 RequestBody formBody = new FormBody.Builder() .add("username", "user123") .add("password", "password123") .build();

// 创建请求 Request request = new Request.Builder() .url("https://api.example.com/login") .post(formBody) .build();

// 执行请求 try (Response response = client.newCall(request).execute()) { // 处理响应 String responseData = response.body().string(); System.out.println(responseData); } catch (IOException e) { e.printStackTrace(); } ```

发送JSON数据

很多现代API使用JSON交换数据。用OkHttp发送JSON数据：

```java MediaType JSON = MediaType.parse("application/json; charset=utf-8"); String jsonBody = "{\"name\":\"John\",\"email\":\"john@example.com\"}";

RequestBody requestBody = RequestBody.create(jsonBody, JSON); Request request = new Request.Builder() .url("https://api.example.com/users") .post(requestBody) .build();

try (Response response = client.newCall(request).execute()) { // 处理响应 } ```

在实际项目中，你可能会使用Gson或Jackson等库来构建JSON字符串，而不是手动拼接。

处理响应头

HTTP响应头包含了很多有用信息，OkHttp可以轻松访问：

```java Response response = client.newCall(request).execute();

// 获取特定头部 String contentType = response.header("Content-Type");

// 获取所有同名头部 List cookies = response.headers("Set-Cookie");

// 遍历所有头部 Headers headers = response.headers(); for (int i = 0; i < headers.size(); i++) { System.out.println(headers.name(i) + ": " + headers.value(i)); } ```

添加请求头

有时我们需要在请求中添加头部，比如授权token：

java Request request = new Request.Builder() .url("https://api.example.com/protected-resource") .header("Authorization", "Bearer YOUR_TOKEN_HERE") .build();

如果需要添加多个同名头部：

java Request request = new Request.Builder() .url("https://api.example.com/resource") .addHeader("Cookie", "cookie1=value1") .addHeader("Cookie", "cookie2=value2") .build();

文件上传

OkHttp也可以轻松处理文件上传：

```java File file = new File("document.pdf"); MediaType mediaType = MediaType.parse("application/pdf");

RequestBody requestBody = RequestBody.create(file, mediaType); Request request = new Request.Builder() .url("https://api.example.com/upload") .post(requestBody) .build(); ```

对于多部分请求（如同时上传文件和表单数据）：

```java File file = new File("image.jpg");

RequestBody requestBody = new MultipartBody.Builder() .setType(MultipartBody.FORM) .addFormDataPart("title", "我的图片标题") .addFormDataPart("image", "image.jpg", RequestBody.create(file, MediaType.parse("image/jpeg"))) .build();

Request request = new Request.Builder() .url("https://api.example.com/upload") .post(requestBody) .build(); ```

拦截器：自定义HTTP行为

OkHttp的拦截器是个强大的机制，可以监控、修改甚至重试请求。例如，添加一个日志拦截器：

```java OkHttpClient client = new OkHttpClient.Builder() .addInterceptor(new Interceptor() { @Override public Response intercept(Chain chain) throws IOException { Request request = chain.request();

```

你也可以使用OkHttp提供的现成的HttpLoggingInterceptor：

```java HttpLoggingInterceptor logging = new HttpLoggingInterceptor(); logging.setLevel(HttpLoggingInterceptor.Level.BASIC);

OkHttpClient client = new OkHttpClient.Builder() .addInterceptor(logging) .build(); ```

取消请求

有时候你需要取消正在进行的请求，比如用户离开了页面：

```java // 保存Call对象的引用 Call call = client.newCall(request); call.enqueue(new Callback() { // 回调方法... });

// 在需要时取消 call.cancel(); ```

使用Retrofit与OkHttp

很多Android开发者会结合使用Retrofit和OkHttp。Retrofit是一个类型安全的HTTP客户端，它在OkHttp的基础上提供了更高级的API：

```java // 配置Retrofit使用我们的OkHttpClient Retrofit retrofit = new Retrofit.Builder() .baseUrl("https://api.example.com/") .client(okHttpClient) // 使用自定义的OkHttpClient .addConverterFactory(GsonConverterFactory.create()) .build();

// 创建API接口 ApiService service = retrofit.create(ApiService.class);

// 使用接口方法 Call call = service.getUser(123); ```

Retrofit与OkHttp完美配合——Retrofit处理API接口定义和数据序列化，而OkHttp负责底层的HTTP交互。

OkHttp的缓存机制

网络请求消耗电量和流量，OkHttp提供了内置的缓存支持：

```java // 创建缓存目录 File cacheDirectory = new File(context.getCacheDir(), "http-cache"); int cacheSize = 10 * 1024 * 1024; // 10 MB Cache cache = new Cache(cacheDirectory, cacheSize);

// 配置OkHttpClient使用缓存 OkHttpClient client = new OkHttpClient.Builder() .cache(cache) .build(); ```

OkHttp会根据HTTP头部的缓存控制指令自动管理缓存。你也可以添加拦截器实现自定义缓存策略。

常见错误与解决方案

使用OkHttp时可能遇到一些常见问题：

1. NetworkOnMainThreadException：在Android主线程执行网络操作。 解决：使用异步API或在工作线程中执行请求。
2. SSLHandshakeException：SSL握手失败。 解决：检查服务器证书，可能需要配置自定义的TrustManager。
3. SocketTimeoutException：连接或读取超时。 解决：增加超时时间或检查网络状况。

NetworkOnMainThreadException：在Android主线程执行网络操作。 解决：使用异步API或在工作线程中执行请求。

SSLHandshakeException：SSL握手失败。 解决：检查服务器证书，可能需要配置自定义的TrustManager。

SocketTimeoutException：连接或读取超时。 解决：增加超时时间或检查网络状况。

java OkHttpClient client = new OkHttpClient.Builder() .connectTimeout(30, TimeUnit.SECONDS) .readTimeout(30, TimeUnit.SECONDS) .writeTimeout(30, TimeUnit.SECONDS) .build();

总结

OkHttp是一个强大而优雅的HTTP客户端，它简化了Android和Java应用中的网络请求处理。它提供的连接池管理、透明的GZIP压缩、响应缓存等功能，使得网络操作更加高效。

通过本文介绍的基础用法，你应该已经可以处理大多数HTTP请求场景了。随着你对OkHttp的深入使用，你会发现它灵活的拦截器机制能够满足各种高级需求。

记住，网络操作总是有风险的——连接可能会失败，服务器可能会返回错误。良好的错误处理和重试机制是构建可靠网络应用的关键。OkHttp为你处理了很多复杂情况，但编写健壮的网络代码仍然需要周全的考虑。

希望这篇入门教程对你有所帮助！网络请求是现代应用的核心部分，掌握OkHttp将让你的开发工作更加顺畅。