1. 项目背景与模块划分

1.1 Retrofit核心概念

Retrofit是Square公司推出的类型安全HTTP客户端，专为Android/Java平台设计。其核心思想是将REST API声明为Java接口，通过注解描述请求方法、路径、参数、Header等元数据，运行时动态生成实现。

• 注解驱动：使用@GET、@POST、@Path、@Query等声明请求，无需手写HttpURLConnection。
• 动态代理：Retrofit.create(YourService.class)生成接口代理对象，拦截方法调用并构建OkHttp请求。
• CallAdapter：将Call<T>转换为其他异步模型（如RxJava Observable、Kotlin协程suspend）。
• Converter：序列化/反序列化请求体和响应体，常用Gson、Moshi、Jackson等。

1.2 接口分离原则

网络层模块设计中，应遵循接口隔离原则（ISP）和依赖倒置原则（DIP）：

• 每个API接口只暴露明确的功能边界，不可出现一个大而全的AllApiService。
• 上层（ViewModel / UseCase）仅依赖抽象接口，不依赖Retrofit具体实现。
• 网络层的接口定义文件，与数据模型、依赖注入模块严格分层。

1.3 项目目录结构设计

推荐的多层分包结构如下（以Android Kotlin/Gradle项目为例）：

com.example.app/
├── data/
│   ├── network/                # 网络层
│   │   ├── api/                # Retrofit接口定义（UserApi.kt, ProductApi.kt等）
│   │   ├── model/              # 请求/响应DTO（Data Transfer Object）
│   │   ├── interceptor/        # OkHttp拦截器（日志、认证、缓存）
│   │   ├── converter/          # 自定义Converter（如需）
│   │   └── NetworkModule.kt    # 依赖注入提供Retrofit、OkHttp实例
│   ├── repository/             # Repository实现，调用API并做数据转换
│   └── database/               # 本地持久化（Room等）
├── domain/
│   ├── model/                  # 领域层实体（不依赖网络DTO）
│   └── repository/             # Repository接口（抽象依赖）
└── ui/
    └── viewmodel/              # ViewModel通过Repository接口获取数据

1.4 依赖配置示例（Gradle）

在模块级build.gradle.kts中添加：

dependencies {
    implementation("com.squareup.retrofit2:retrofit:2.9.0")
    implementation("com.squareup.retrofit2:converter-gson:2.9.0")
    implementation("com.squareup.okhttp3:logging-interceptor:4.12.0")
    // 可选：RxJava适配器
    implementation("com.squareup.retrofit2:adapter-rxjava3:2.9.0")
}

建议将Retrofit.Builder和OkHttpClient的创建封装在NetworkModule内（使用Hilt/Dagger或手动单例），避免重复实例化。