1. 项目初始化与依赖配置
1.1 章节原理与目标
本章是整门课程的基石。在开始编写同步逻辑之前，必须正确配置 Android 项目的构建环境。我们将完成三项核心任务：
- 添加 Gradle 依赖：将 Retrofit、WorkManager 及其必要的编译/运行时库引入项目。
- 配置网络权限：在
AndroidManifest.xml中声明互联网访问权限，确保应用能够进行网络请求。 - 选择并验证版本：确定当前稳定的 Retrofit 和 WorkManager 版本，并确保它们与 Android SDK 版本兼容。
完成本章后，你将拥有一个可以直接运行后续章节所有代码的基准项目。
1.2 核心依赖关系与框架图
下图展示了 Android 应用、Retrofit、WorkManager 以及网络/数据库组件之间的基础架构关系。这是后续所有章节的顶层设计视图。
1.3 版本选择与兼容性说明
在正式添加依赖之前，需要明确版本策略。下表列出了本课程使用的推荐版本及其兼容性依据。
| 库名称 | 推荐版本 | 最低兼容 API 级别 | 选择理由 |
|---|---|---|---|
| Retrofit | 2.9.0 | 21 (Android 5.0) | 稳定、广泛使用，对 Kotlin 协程和 RxJava 均有良好支持。 |
| OkHttp | 4.12.0 | 21 | Retrofit 默认底层 HTTP 客户端，必需依赖。 |
| WorkManager | 2.9.0 | 21 | 官方推荐的长期运行后台任务方案，兼容性强。 |
| Gson (转换器) | 2.10.1 | — | 用于 Retrofit 的 JSON 序列化/反序列化。 |
版本兼容性提示：建议始终保持 Retrofit 和 OkHttp 的主版本号一致。如果项目使用 Kotlin，请确保 Kotlin 版本不低于 1.8.0，以避免与 Retrofit 2.9.0 的注解处理冲突。
1.4 添加 Gradle 依赖
在项目级 build.gradle.kts (Kotlin DSL) 或 build.gradle (Groovy DSL) 中配置仓库后，在 app/build.gradle.kts 的 dependencies 块中添加如下内容。
app/build.gradle.kts (Kotlin DSL)
dependencies {
// Retrofit 核心库
implementation("com.squareup.retrofit2:retrofit:2.9.0")
// Retrofit Gson 转换器
implementation("com.squareup.retrofit2:converter-gson:2.9.0")
// OkHttp (Retrofit 自动包含, 但建议显式声明以控制版本)
implementation("com.squareup.okhttp3:okhttp:4.12.0")
// OkHttp 日志拦截器 (调试阶段非常实用)
implementation("com.squareup.okhttp3:logging-interceptor:4.12.0")
// WorkManager
implementation("androidx.work:work-runtime-ktx:2.9.0")
// 可选: 用于 WorkManager 的测试
// androidTestImplementation("androidx.work:work-testing:2.9.0")
}
Groovy DSL 用户：只需将圆括号
() 替换为引号 ""，并去掉 implementation 后的尾随空格。例如：implementation 'com.squareup.retrofit2:retrofit:2.9.0'。
1.5 配置网络权限
Android 应用默认不允许进行网络请求。除非你在 AndroidManifest.xml 中显式声明网络访问权限。打开 app/src/main/AndroidManifest.xml，在 <manifest> 标签内（<application> 标签上方）添加以下权限声明。
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
网络安全配置（Android 9+）
如果目标 API 级别为 28 或更高，并且你访问的是非加密的 HTTP 端点，请在 AndroidManifest.xml 的 <application> 标签中增加：android:usesCleartextTraffic="true"。生产环境强烈建议仅使用 HTTPS。
1.6 调试与验证
完成上述步骤后，请执行以下验证流程：
- 同步项目：在 Android Studio 中点击
File > Sync Project with Gradle Files或直接点击工具栏的“大象”图标。 - 检查依赖树：在 Terminal 中执行
./gradlew app:dependencies，确认 Retrofit、OkHttp、WorkManager 均已出现在依赖树中。 - 编译测试：尝试编译项目 (
Build > Make Project)，确保无编译错误。
常见错误 & 解决方案
- Duplicate class 冲突：若出现
Duplicate class com.google.gson...错误，请检查是否同时依赖了converter-gson和gson的不同版本。统一使用 Retrofit 推荐的版本。 - WorkManager 运行时崩溃：确保
compileSdk不低于 34，且 AppCompat 版本对应。低版本 AppCompat 可能导致初始化失败。
1.7 性能与稳定性优化建议
- 统一 OkHttp 版本：如果你的项目还引入了 Firebase、Glide 等其他库，它们可能也依赖 OkHttp。请确保所有 OkHttp 版本一致，避免因版本冲突导致运行时诡异问题。
- 使用 BOM 管理版本：对于大型项目，考虑使用 OkHttp 和 Retrofit 的 BOM（Bill of Materials）来统一管理版本，减少手动维护工作量。
- 启用 HttpLoggingInterceptor：在调试阶段，务必注入日志拦截器以便追踪请求/响应。生产环境请移除或设置级别为
NONE。