Java 中使用 OkHttp3 的网络请求教程与实战

解释：

• Request.Builder()：构建请求的起始点。
• .url()：设置目标 URL。
• .build()：构建最终的 Request 对象。
• newCall(request).execute()：创建一个调用并同步执行，返回 Response。
• response.body().string()：将响应体转换为字符串，这是最常用的读取方式之一。

2.2 POST 请求：提交数据

POST 请求用于向服务器提交数据，常用于表单提交、创建资源等场景。

2.2.1 表单数据（application/x-www-form-urlencoded）

import okhttp3.FormBody;
import okhttp3.RequestBody;

public class PostFormExample {
    public static void main(String[] args) throws Exception {
        // 1. 构建表单数据体
        RequestBody formBody = new FormBody.Builder()
                .add("username", "john_doe")
                .add("email", "[email protected]")
                .build();
        // 2. 创建 POST 请求，将表单数据体附加到请求中
        Request request = new Request.Builder()
                .url("https://httpbin.org/post")
                .post(formBody)
                .build();
        // 3. 执行请求
        try (Response response = OkHttpConfig.getClient().newCall(request).execute()) {
            if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
            String responseBody = response.body().string();
            System.out.println("Response: " + responseBody);
        }
    }
}

2.2.2 JSON 数据（application/json）

import okhttp3.MediaType;
import okhttp3.RequestBody;

public class PostJsonExample {
    public static void main(String[] args) throws Exception {
        // 1. 定义 JSON 媒体类型
        MediaType JSON = MediaType.get("application/json; charset=utf-8");
        // 2. 构建 JSON 字符串作为请求体
        String json = "{\"name\": \"Alice\", \"age\": 30}";
        // 3. 创建 RequestBody
        RequestBody body = RequestBody.create(json, JSON);
        // 4. 创建 POST 请求，附带请求体
        Request request = new Request.Builder()
                .url("https://httpbin.org/post")
                .post(body)
                .build();
        // 5. 执行请求
        try (Response response = OkHttpConfig.getClient().newCall(request).execute()) {
            if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
            String responseBody = response.body().string();
            System.out.println("Response: " + responseBody);
        }
    }
}

2.2.3 上传文件（multipart/form-data）

import okhttp3.MultipartBody;
import java.io.File;

public class UploadFileExample {
    public static void main(String[] args) throws Exception {
        // 1. 创建 MultipartBody.Builder 来构建多部分表单
        MultipartBody.Builder multipartBuilder = new MultipartBody.Builder()
                .setType(MultipartBody.FORM); // 指定为 form-data
        // 2. 添加文件部分：需要提供文件路径和文件名（可选）
        File file = new File("path/to/your/file.txt");
        multipartBuilder.addFormDataPart("file", file.getName(),
                RequestBody.create(MediaType.parse("text/plain"), file));
        // 3. 添加其他表单字段（可选）
        multipartBuilder.addFormDataPart("description", "This is a test file.");
        // 4. 构建完整的 RequestBody
        RequestBody requestBody = multipartBuilder.build();
        // 5. 创建 POST 请求，使用 multipart/form-data
        Request request = new Request.Builder()
                .url("https://httpbin.org/post")
                .post(requestBody)
                .build();
        // 6. 执行请求
        try (Response response = OkHttpConfig.getClient().newCall(request).execute()) {
            if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
            String responseBody = response.body().string();
            System.out.println("Response: " + responseBody);
        }
    }
}

三、进阶技巧：异步请求与回调

3.1 同步 vs 异步请求

• 同步请求：调用 execute() 会阻塞当前线程，直到请求完成。适合在简单脚本或非主线程中使用。
• 异步请求：调用 enqueue()，将请求放入队列，由后台线程处理。不会阻塞主线程，是 UI 应用和高并发服务的首选。

3.2 异步请求示例（Callback）

import okhttp3.Callback;
import okhttp3.Response;

public class AsyncRequestExample {
    public static void main(String[] args) {
        Request request = new Request.Builder()
                .url("https://jsonplaceholder.typicode.com/posts/1")
                .build();
        // 1. 使用 enqueue 方法发送异步请求，传入 Callback
        OkHttpConfig.getClient().newCall(request).enqueue(new Callback() {
            @Override
            public void onFailure(Call call, IOException e) {
                // 请求失败时的回调，例如网络错误、超时等
                System.err.println("Request failed: " + e.getMessage());
                e.printStackTrace();
            }

            @Override
            public void onResponse(Call call, Response response) throws IOException {
                // 请求成功时的回调，此时 response 已经可用
                if (!response.isSuccessful()) {
                    System.err.println("Unexpected code " + response);
                    return;
                }
                // 读取响应体内容
                String responseBody = response.body().string();
                System.out.println("Async Response: " + responseBody);
                // 重要：必须关闭 response.body()，否则可能造成资源泄漏！
                // 因为这里是在回调里，所以不能用 try-with-resources，需要手动关闭。
                // 但请注意，在实际项目中，应确保此逻辑的健壮性。
                response.close();
            }
        });
        // 2. 注意：主线程不会等待异步请求完成，会立即继续执行后续代码。
        // 这里为了演示，可以加一个 sleep，让程序运行一段时间。
        try {
            Thread.sleep(5000);
        } catch (InterruptedException e) {
            e.printStackTrace();
        }
    }
}

四、高级功能：拦截器（Interceptors）

4.1 什么是拦截器？

拦截器是 OkHttp3 中一个极其强大的特性。它允许你在请求发出前或响应返回后，对请求或响应进行修改、记录日志、添加认证头等操作。它的工作原理类似于一个'中间件'或'过滤器'。

4.2 应用场景：日志记录与调试

import okhttp3.Interceptor;
import okhttp3.Request;
import okhttp3.Response;

public class LoggingInterceptor implements Interceptor {
    @Override
    public Response intercept(Chain chain) throws IOException {
        // 1. 获取原始请求
        Request request = chain.request();
        // 2. 记录请求信息（时间、方法、URL、Headers）
        long startTime = System.currentTimeMillis();
        System.out.println("Sending request to: " + request.url());
        System.out.println("Method: " + request.method());
        System.out.println("Headers: " + request.headers());
        // 3. 继续执行请求（关键步骤）
        Response response = chain.proceed(request);
        // 4. 记录响应信息（状态码、耗时、响应体大小）
        long endTime = System.currentTimeMillis();
        System.out.println("Received response in " + (endTime - startTime) + "ms");
        System.out.println("Status Code: " + response.code());
        System.out.println("Response Body Size: " + response.body().contentLength() + " bytes");
        // 5. 返回修改后的响应（通常不需要修改，直接返回原响应）
        return response;
    }
}

4.3 将拦截器应用到客户端

// 1. 为 OkHttpClient 添加拦截器（注意：拦截器分为两种：Application Interceptor & Network Interceptor）
// 这里我们使用 Application Interceptor，它会在请求发出前和响应返回后各执行一次。
OkHttpClient client = new OkHttpClient.Builder()
        .addInterceptor(new LoggingInterceptor())
        .build();
// 2. 使用这个带有拦截器的 client 进行请求，日志就会自动打印出来。

4.4 应用场景：添加认证头（Token）

import okhttp3.Interceptor;
import okhttp3.Request;
import okhttp3.Response;

public class AuthInterceptor implements Interceptor {
    private final String token;

    public AuthInterceptor(String token) {
        this.token = token;
    }

    @Override
    public Response intercept(Chain chain) throws IOException {
        // 1. 获取原始请求
        Request originalRequest = chain.request();
        // 2. 创建一个新的请求，添加 Authorization Header
        Request authenticatedRequest = originalRequest.newBuilder()
                .header("Authorization", "Bearer " + token)
                .build();
        // 3. 继续执行带有认证头的请求
        return chain.proceed(authenticatedRequest);
    }
}

// 应用该拦截器，确保所有请求都携带 Token
OkHttpClient client = new OkHttpClient.Builder()
        .addInterceptor(new AuthInterceptor("your-jwt-token-here"))
        .build();

五、综合案例：一个完整的用户登录与信息查询应用

下面是一个整合了多种技术的完整示例，模拟一个用户登录后查询个人信息的流程。

import okhttp3.*;
import java.io.IOException;
import java.util.concurrent.TimeUnit;

public class UserLoginApp {
    private static final OkHttpClient client = new OkHttpClient.Builder()
            .connectTimeout(10, TimeUnit.SECONDS) // 连接超时 10 秒
            .readTimeout(30, TimeUnit.SECONDS) // 读取超时 30 秒
            .writeTimeout(30, TimeUnit.SECONDS) // 写入超时 30 秒
            .addInterceptor(new LoggingInterceptor())
            .addInterceptor(new AuthInterceptor("initial-token"))
            .build();

    public static void main(String[] args) {
        // 1. 用户登录，获取 token
        String loginToken = loginUser("admin", "password123");
        if (loginToken == null) {
            System.err.println("Login failed!");
            return;
        }
        // 2. 使用获取到的 token，查询用户信息（此时 AuthInterceptor 会自动添加 token）
        getUserInfo(loginToken);
    }

    private static String loginUser(String username, String password) {
        RequestBody formBody = new FormBody.Builder()
                .add("username", username)
                .add("password", password)
                .build();
        Request request = new Request.Builder()
                .url("https://api.example.com/login")
                .post(formBody)
                .build();
        try (Response response = client.newCall(request).execute()) {
            if (!response.isSuccessful()) {
                System.err.println("Login failed: " + response.code());
                return null;
            }
            // 假设响应体包含一个名为"token"的 JSON 字段，这里简化处理，仅返回字符串形式的 token
            // 实际项目中应使用 JSON 解析库（如 Jackson）来解析响应体。
            String responseBody = response.body().string();
            System.out.println("Login success, token: " + responseBody);
            return responseBody;
        } catch (IOException e) {
            e.printStackTrace();
            return null;
        }
    }

    private static void getUserInfo(String token) {
        // 由于我们已经在 client 中添加了 AuthInterceptor，所以这里无需再手动添加 token
        Request request = new Request.Builder()
                .url("https://api.example.com/user/profile")
                .get()
                .build();
        // 使用异步请求，避免阻塞主线程
        client.newCall(request).enqueue(new Callback() {
            @Override
            public void onFailure(Call call, IOException e) {
                System.err.println("Failed to fetch user info: " + e.getMessage());
            }

            @Override
            public void onResponse(Call call, Response response) throws IOException {
                if (!response.isSuccessful()) {
                    System.err.println("Unexpected code: " + response.code());
                    return;
                }
                String responseBody = response.body().string();
                System.out.println("User Info: " + responseBody);
                response.close();
            }
        });
        // 主线程继续执行，不等待异步请求完成。
        System.out.println("Fetching user info... (async)");
    }
}

总结：如何选择与使用？

OkHttp3 的强大之处在于它的灵活性和可扩展性。通过合理地组合这些组件，你可以构建出健壮、高效、易于维护的网络层。希望这篇详尽的教程能成为你学习和使用 OkHttp3 的坚实基石！

最后提醒：始终记得在使用 Response.body() 后调用 close() 方法，以释放底层的网络资源，防止内存泄漏。在异步回调中，这一点尤为重要。