2. Gradle依赖配置

2.1 Retrofit版本选择原则

Retrofit遵循语义化版本（SemVer），主版本号变更代表不兼容的API改动。当前稳定主系列为2.x（截至2025年）。选择版本时应关注：

• 最新稳定版：优先使用Maven Central或GitHub Release标注的最新稳定版，避免使用测试版（alpha/beta/rc）。
• Android API级别兼容性：Retrofit 2.x最低支持Android 4.0+（API 14），但当前应用通常已提升minSdk至21以上，无需额外顾虑。
• 依赖传递兼容性：Retrofit核心库直接依赖OkHttp 3.x/4.x，选择Retrofit版本时需确保其声明的最低OkHttp版本与项目其余组件（如WebSocket、性能监控）兼容。
• Release Notes检查：升级前阅读变更日志，重点关注Converter/Adapter适配器签名变化、Deprecated标记和移除的功能。

2.2 Converter依赖与Adapter依赖

Converter负责将HTTP响应体（ResponseBody）反序列化为Java/Kotlin对象，以及将请求体序列化为RequestBody；Adapter负责将Call适配为特定异步类型（如RxJava Observable、Kotlin Coroutines Deferred）。

2.3 OkHttp日志拦截器引入

OkHttp的 HttpLoggingInterceptor 是调试阶段最实用的工具，可打印请求/响应的头信息、体内容、耗时等。生产环境下应当关闭或设置为仅打印头信息，避免敏感数据泄露和性能损耗。

添加依赖：

implementation("com.squareup.okhttp3:logging-interceptor:4.12.0")

在OkHttp Client中配置：

val loggingInterceptor = HttpLoggingInterceptor().apply {
    level = if (BuildConfig.DEBUG) {
        HttpLoggingInterceptor.Level.BODY
    } else {
        HttpLoggingInterceptor.Level.NONE
    }
}

val okHttpClient = OkHttpClient.Builder()
    .addInterceptor(loggingInterceptor)
    .build()

2.4 Gradle配置实战

以下为典型 Android 项目 build.gradle.kts（Kotlin DSL）依赖配置片段：

// 在项目级 gradle.properties 中定义版本变量
// retrofitVersion=2.9.0
// okhttpVersion=4.12.0

dependencies {
    // Retrofit 核心
    implementation("com.squareup.retrofit2:retrofit:${rootProject.ext["retrofitVersion"]}")

    // Converter - 选择一种
    implementation("com.squareup.retrofit2:converter-gson:${rootProject.ext["retrofitVersion"]}")
    // 或 implementation("com.squareup.retrofit2:converter-moshi:${rootProject.ext["retrofitVersion"]}")

    // Adapter - 如果需要 RxJava
    implementation("com.squareup.retrofit2:adapter-rxjava3:${rootProject.ext["retrofitVersion"]}")

    // OkHttp + 日志拦截器
    implementation("com.squareup.okhttp3:okhttp:${rootProject.ext["okhttpVersion"]}")
    implementation("com.squareup.okhttp3:logging-interceptor:${rootProject.ext["okhttpVersion"]}")
}

2.5 常见错误与优化

• 版本不一致导致 NoSuchMethodError：例如 Retrofit 2.9 依赖 OkHttp 4.9+，但项目中还存在 OkHttp 3.12 的传递依赖，运行时抛异常。使用 ./gradlew :app:dependencies 查看依赖树，用 constraints 或 force 统一版本。
• 日志拦截器泄漏敏感数据：生产环境使用了 Level.BODY，导致 、密码等打印到 logcat。建议使用 BuildConfig.DEBUG 控制，或采用自定义拦截器过滤敏感字段。
• Converter & Adapter 重复添加：同时引入了 Gson 和 Moshi 两个 Converter，或同时使用了 suspend 函数和 RxJava Adapter，会造成构建通过但运行时行为混乱。应只保留项目实际使用的组合。
• 忽略 Kotlin 序列化步骤：若选择 Kotlinx Serialization Converter，还需在 Gradle 中添加 Kotlin 序列化插件和运行时库，且实体类需标注 @Serializable。