第2章 基础配置与快速集成：Gradle依赖、OkHttp内置、基础GET/POST请求、日志拦截器配置

2.1 本章定位与集成概要

在本章中，我们将完成Retrofit从零到基础可用的快速集成。内容覆盖Gradle依赖声明、OkHttp内置机制、基础GET/POST请求模板以及日志拦截器配置。理解这些配置项是后续网络请求优化、拦截器链扩展以及稳定性提升的基石。

2.2 Gradle依赖：版本选择与核心库

Retrofit依赖分为三个层级：核心库、转换器库和适配器库。快速集成至少需要核心库和Gson/Moshi转换器。

// 在 module 的 build.gradle 中添加以下依赖
dependencies {
    implementation 'com.squareup.retrofit2:retrofit:2.11.0'
    implementation 'com.squareup.retrofit2:converter-gson:2.11.0'
    // 可选：日志拦截器
    implementation 'com.squareup.okhttp3:logging-interceptor:4.12.0'
    // 可选：RxJava适配器
    implementation 'com.squareup.retrofit2:adapter-rxjava3:2.11.0'
}

2.3 OkHttp内置机制与默认行为

Retrofit 内部始终使用 OkHttp 作为网络层，你无需额外声明 OkHttp 依赖。默认 OkHttpClient 会自动管理连接池、超时和重试。但在多数生产场景下，我们都会自定义 OkHttpClient 以覆盖默认参数。

• 默认超时：连接超时10秒，读取超时10秒，写入超时10秒。
• 连接池：最大空闲连接5个，存活时间5分钟。
• 重试：默认不自动重试，需通过拦截器或OkHttp的retryOnConnectionFailure启用。

// 自定义 OkHttpClient 示例
OkHttpClient client = new OkHttpClient.Builder()
    .connectTimeout(30, TimeUnit.SECONDS)
    .readTimeout(30, TimeUnit.SECONDS)
    .addInterceptor(new HttpLoggingInterceptor().setLevel(HttpLoggingInterceptor.Level.BODY))
    .build();

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .client(client)
    .addConverterFactory(GsonConverterFactory.create())
    .build();

2.4 基础GET请求接口定义与执行

定义接口时使用注解声明HTTP方法和路径。GET请求通过@GET标注，路径参数使用{}占位符。

public interface ApiService {
    @GET("users/{id}")
    Call<User> getUser(@Path("id") int userId);

    @GET("posts")
    Call<List<Post>> getPosts(@Query("userId") int userId);
}

// 同步调用（需在子线程）
Call<User> call = apiService.getUser(1);
Response<User> response = call.execute();
User user = response.body();

// 异步调用
call.enqueue(new Callback<User>() {
    @Override
    public void onResponse(Call<User> call, Response<User> response) {
        // UI线程处理结果
    }
    @Override
    public void onFailure(Call<User> call, Throwable t) {
        // 网络异常或解析失败
    }
});

2.5 基础POST请求与@Body注解

POST请求需使用@POST注解，请求体通过@Body传入。Retrofit自动将对象序列化为JSON。

public interface ApiService {
    @POST("users")
    Call<User> createUser(@Body User user);
}

// 构造请求体并发送
User newUser = new User("John", "john@example.com");
Call<User> call = apiService.createUser(newUser);
call.enqueue(new Callback<User>() { ... });

2.6 日志拦截器配置与调试

OkHttp的HttpLoggingInterceptor可以输出完整的请求/响应信息，极大方便调试。

HttpLoggingInterceptor logging = new HttpLoggingInterceptor();
// 设置日志级别：NONE, BASIC, HEADERS, BODY
logging.setLevel(HttpLoggingInterceptor.Level.BODY);

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

// 动态级别示例
HttpLoggingInterceptor logging = new HttpLoggingInterceptor();
if (BuildConfig.DEBUG) {
    logging.setLevel(HttpLoggingInterceptor.Level.BODY);
} else {
    logging.setLevel(HttpLoggingInterceptor.Level.NONE);
}

2.7 集成流程总览（SVG）

下图展示从Gradle依赖到发起一次网络请求的完整流程，包含OkHttp自定义与日志拦截器的介入点。

2.8 常见错误与避坑指南

2.9 性能与稳定性优化要点

• 共用OkHttpClient：整个应用应唯一实例化OkHttpClient，利用连接池和复用减少握手开销。
• 日志拦截器分级：调试用BODY，发布版应移除或设为NONE，避免日志写入I/O阻塞。
• 超时差异化：上传操作可单独提高写入超时，普通GET保持较短超时以快速失败。

2.10 部署验证清单

1. 依赖版本号统一管理，避免多版本冲突。
2. 确认baseUrl以/结尾，且@GET路径不以/开头。
3. 测试GET与POST请求分别在模拟器和真机环境下连通。
4. 检查日志拦截器在release构建中是否已排除。