# 网络层组件说明

本目录包含网络请求相关的所有组件，按照架构设计文档统一管理。

## 📁 目录结构

```
common/network/
├── NetworkManager.kt              # 网络管理器（基础设施）
├── ApiManager.kt                  # API 管理器（业务封装）
├── ApiCommonResult.kt             # 统一响应格式（定义在 ApiResponseParser.kt 中）
├── ApiResponseParser.kt           # 响应解析器
├── ApiBaseRemoteDataSource.kt     # 远程数据源基类
├── ApiBaseRepository.kt           # Repository 基类
├── adapter/                       # Retrofit 适配器模块
│   └── ApiResponseCallAdapterFactory.kt  # CallAdapter 工厂（让接口直接返回 ApiResponse<T>）
├── response/                      # 响应封装模块（参考 Sandwich 设计）
│   ├── ApiResponse.kt             # 响应封装类（Success/Error/Exception）
│   └── ApiResponseExtensions.kt   # 扩展函数（所有扩展函数，包含 zip/zip3/recoverWith/requireNotNull 等）
├── operator/                      # 全局处理模块
│   ├── ApiResponseOperator.kt     # Operator 接口
│   ├── GlobalApiOperator.kt       # 全局响应处理器（支持多个 Operator 链式调用）
│   └── RetryOperator.kt           # 重试机制（支持 Duration 和 Long 两种版本）
├── interceptor/
│   ├── HeaderInterceptor.kt       # 请求头拦截器
│   └── TokenRefreshInterceptor.kt # Token 刷新拦截器（自动处理 401/402）
└── exception/
    ├── ApiException.kt            # 自定义异常类
    └── ExceptionHandle.kt         # 统一异常处理
```

---

## 1. NetworkManager（网络管理器）

**文件**: `NetworkManager.kt`

**作用**: 
- 管理 Retrofit 和 OkHttpClient 实例（单例模式）
- 构建网络客户端（添加拦截器、配置超时等）
- 提供网络基础设施能力

**职责**:
- ✅ 管理 Retrofit 实例（单例，避免重复创建）
- ✅ 管理 OkHttpClient 实例（单例）
- ✅ 添加日志拦截器
- ✅ 添加 HeaderInterceptor（请求头）
- ✅ 配置超时时间

**使用场景**:
- **业务层不需要直接使用**，通过 `ApiManager` 间接使用
- **自动初始化** - `NetworkManager` 由 `ApiManager` 自动初始化，无需手动调用
- **能力层 SDK** 可以直接使用（如果需要独立的网络客户端）

**注意**: 
- ✅ **业务层不需要手动初始化** - `ApiManager.create<>()` 会自动初始化 `NetworkManager`
- ✅ **完全自动化** - 所有配置都自动处理，无需手动操作

---

## 2. ApiManager（API 管理器）

**文件**: `ApiManager.kt`

**作用**: 
- 业务层的统一入口，简化 API 接口的创建
- 自动处理配置（从 ServerConfigManager 读取）
- 自动初始化 NetworkManager

**职责**:
- ✅ 完全懒加载（第一次调用 `create()` 时自动初始化）
- ✅ 自动从 ServerConfigManager 读取服务器地址
- ✅ 自动检测调试模式
- ✅ 自动初始化 NetworkManager
- ✅ 创建 API 接口实例（工厂方法）
- ✅ 管理 Token Provider（可选，通常由 AuthManager 自动设置）

**使用场景**:
- **业务层使用**（Repository、DataSource）
- 业务层的首选方式（最简单）
- **无需手动初始化** - 完全懒加载，第一次使用时自动初始化

**使用示例**:
```kotlin
// 创建 API 接口（完全懒加载，第一次使用时自动初始化）
// 无需手动调用 initialize()，create() 会自动初始化
val authApi = ApiManager.create<AuthApi>()

// 使用接口（如果使用 CallAdapter，直接返回 ApiResponse<T>）
val response: ApiResponse<LoginResponse> = authApi.login(LoginRequest(...))
response.onSuccess { data -> /* 处理成功 */ }
        .onError { code, message -> /* 处理业务错误 */ }
        .onException { exception -> /* 处理异常 */ }

// 设置 Token（可选，通常由 AuthManager 自动设置）
// 如果需要手动设置，可以调用：
// ApiManager.setTokenProvider { TokenStore.getAccessToken() }
```

**与 NetworkManager 的区别**:
| 对比项 | NetworkManager | ApiManager |
|--------|---------------|------------|
| 层级 | 基础设施层 | 业务封装层 |
| 职责 | 构建网络客户端 | 简化业务使用 |
| 配置 | 需要手动配置 | 自动读取配置（懒加载） |
| 初始化 | 可选手动初始化 | 完全懒加载（第一次使用时自动初始化） |
| 使用者 | 能力层 SDK | 业务层（Repository） |

**核心特性**:
- ✅ **完全懒加载** - 无需手动调用 `initialize()`，第一次使用 `create()` 时自动初始化
- ✅ **自动配置** - 自动从 `ServerConfigManager` 读取服务器地址和配置
- ✅ **简洁易用** - 业务层只需要调用 `ApiManager.create<Api>()` 即可

---

## 3. ApiCommonResult（统一响应格式）

**文件**: `ApiResponseParser.kt`（定义在此文件中）

**作用**: 
- 定义统一的 API 响应格式（对应后端 `CommonResult<T>`）
- 所有接口都使用此格式包装

**结构**:
```kotlin
data class ApiCommonResult<T>(
    val code: Int,        // 业务状态码（0 表示成功）
    val msg: String?,     // 错误消息
    val data: T?          // 业务数据
)
```

**使用场景**:
- 所有 API 接口都使用 CallAdapter，直接返回 `ApiResponse<T>`
- 由 `ApiResponseParser` 自动解析和转换

**示例**:
```kotlin
// API 接口定义（推荐方式，直接返回 ApiResponse<T>）
interface AuthApi {
    @POST("member/auth/login")
    suspend fun login(@Body request: LoginRequest): ApiResponse<LoginResponse>
}

// 使用（无需手动解析）
val response: ApiResponse<LoginResponse> = authApi.login(request)
response.onSuccess { data -> /* 处理成功 */ }
        .onError { code, message -> /* 处理业务错误 */ }
        .onException { exception -> /* 处理异常 */ }
```

**注意**: 
- ✅ `ApiResponseCallAdapterFactory` 已自动注册到 `NetworkManager`
- ✅ 接口直接返回 `ApiResponse<T>`，无需手动解析
- ✅ 类型安全，编译时检查

---

## 4. ApiResponseParser（响应解析器）

**文件**: `ApiResponseParser.kt`

**作用**: 
- 解析 Retrofit 的 `Response<ApiCommonResult<T>>`
- 提取业务数据，转换为 `ApiResponse<T>`
- 统一处理 HTTP 错误码和业务错误码

**职责**:
- ✅ 检查 HTTP 状态码（200-299）
- ✅ 检查业务状态码（code == 0）
- ✅ 提取 `data` 字段
- ✅ 转换为 `ApiResponse<T>`（Success/Error/Exception）

**使用场景**:
- **不直接使用**，由 `ApiBaseRemoteDataSource.executeRequestResponse()` 内部调用

**处理流程**:
```
Response<ApiCommonResult<T>>
    ↓
检查 HTTP 状态码
    ↓
检查业务状态码 (code == 0)
    ↓
提取 data 字段
    ↓
ApiResponse<T>（Success/Error/Exception）
```

---

## 5. ApiBaseRemoteDataSource（远程数据源基类）

**文件**: `ApiBaseRemoteDataSource.kt`

**作用**: 
- 封装通用的网络请求逻辑
- 提供 `executeRequestResponse()` 方法，简化网络请求代码
- 统一处理异常、线程切换、全局处理和自动重试

**职责**:
- ✅ 自动切换到 IO 线程（`withContext(Dispatchers.IO)`）
- ✅ 调用 `ApiResponseParser.parseResponse()` 解析响应
- ✅ 使用 `GlobalApiOperator` 应用全局处理
- ✅ 支持自动重试（可选）
- ✅ 使用 `ExceptionHandle` 统一处理异常
- ✅ 统一日志记录

**使用场景**:
- **RemoteDataSource 继承使用**（如 `AuthRemoteDataSource`）

**使用示例**:
```kotlin
class AuthRemoteDataSource : ApiBaseRemoteDataSource() {
    private val authApi = ApiManager.create<AuthApi>()
    
    suspend fun login(request: LoginRequest): ApiResponse<LoginResponse> {
        // 使用 executeRequestResponse，自动处理异常、线程切换、响应解析、全局处理
        return executeRequestResponse(
            request = { authApi.login(request) },
            enableRetry = true,
            retryTimes = 3
        ).onSuccess { data ->
            ILog.d("Auth", "登录成功")
        }.onError { code, message ->
            ILog.w("Auth", "登录失败: $code - $message")
        }.onException { exception ->
            ILog.e("Auth", "登录异常: ${exception.message}")
        }
    }
    
    // 如果需要 Result<T>，使用 toResult() 转换
    suspend fun loginAsResult(request: LoginRequest): Result<LoginResponse> {
        return executeRequestResponse(
            request = { authApi.login(request) }
        ).toResult()
    }
}
```

---

## 6. ApiBaseRepository（Repository 基类）

**文件**: `ApiBaseRepository.kt`

**作用**: 
- Repository 模式的基类
- 提供通用的错误处理和数据转换方法
- 预留扩展点（子类可重写）

**职责**:
- ✅ 统一错误处理（`handleError()`）
- ✅ 数据转换（`transform()`，Data Model → Domain Model）
- ✅ 日志记录

**使用场景**:
- **Repository 继承使用**（如 `AuthRepository`）

**使用示例**:
```kotlin
class AuthRepository(
    private val remoteDataSource: AuthRemoteDataSource
) : ApiBaseRepository() {
    
    suspend fun login(mobile: String, password: String): Result<LoginResponse> {
        val request = LoginRequest(mobile, password)
        return remoteDataSource.login(request)
    }
}
```

---

## 7. HeaderInterceptor（请求头拦截器）

**文件**: `interceptor/HeaderInterceptor.kt`

**作用**: 
- 统一为所有请求添加公共请求头
- 自动添加 Token（如果提供）

**职责**:
- ✅ 添加 `Content-Type: application/json`
- ✅ 添加 `Accept: application/json`
- ✅ 添加 `Authorization: Bearer {token}`（可选）

**使用场景**:
- **不直接使用**，由 `NetworkManager` 自动添加
- 所有通过 `NetworkManager` 创建的请求都会自动使用

**添加的请求头**:
```
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}  // 如果提供了 tokenProvider
```

---

## 8. ApiException（自定义异常类）

**文件**: `exception/ApiException.kt`

**作用**: 
- 定义统一的异常类型
- 区分不同类型的错误（网络、HTTP、业务、解析）

**异常类型**:
- `NetworkException`: 网络连接异常（无网络、超时、DNS 失败等）
- `HttpException`: HTTP 状态码异常（404、500 等）
- `BusinessException`: 业务异常（业务状态码错误，如登录失败）
- `ParseException`: 数据解析异常（JSON 解析失败等）
- `UnknownApiException`: 未知异常（兜底）

**使用场景**:
- 由 `ExceptionHandle` 自动转换
- 业务层可以通过 `when` 判断异常类型

**使用示例**:
```kotlin
result.onFailure { throwable ->
    when (val apiException = ExceptionHandle.handle(throwable)) {
        is NetworkException -> { /* 网络问题 */ }
        is BusinessException -> { /* 业务错误 */ }
        is HttpException -> { /* HTTP 错误 */ }
    }
}
```

---

## 9. ExceptionHandle（统一异常处理）

**文件**: `exception/ExceptionHandle.kt`

**作用**: 
- 统一异常处理类
- 将各种异常转换为 `ApiException`
- 提供用户友好的错误消息

**职责**:
- ✅ 转换异常类型（`Throwable` → `ApiException`）
- ✅ 统一错误消息格式
- ✅ 记录日志

**处理流程**:
```
Throwable（各种异常）
    ↓
ExceptionHandle.handle()
    ↓
ApiException（统一异常类型）
    ↓
业务层处理
```

**使用场景**:
- **不直接使用**，由 `ApiBaseRemoteDataSource` 和 `ApiResponseParser` 内部调用
- 业务层需要时可以手动调用

**异常转换规则**:
- `SocketTimeoutException` → `NetworkException`
- `UnknownHostException` → `NetworkException`
- `RetrofitHttpException` → `HttpException`
- 其他异常 → `UnknownApiException`

---

## 📊 调用关系图

```
业务层（ViewModel/Repository）
    ↓
Repository（如 AuthRepository）
    ↓
RemoteDataSource（如 AuthRemoteDataSource）
    ├── ApiManager.create<AuthApi>()  ← 创建 API 接口
    └── executeRequestResponse()
        ├── ApiResponseParser.parseResponse()  ← 解析响应为 ApiResponse
        ├── GlobalApiOperator.apply()  ← 应用全局处理
        └── ExceptionHandle.handle()  ← 处理异常
        
NetworkManager
    ├── HeaderInterceptor  ← 添加请求头
    └── TokenRefreshInterceptor  ← Token 刷新拦截器
```

---

## 🎯 使用建议

### 业务层使用（推荐）

```kotlin
// 1. 创建 RemoteDataSource（继承 ApiBaseRemoteDataSource）
class AuthRemoteDataSource : ApiBaseRemoteDataSource() {
    private val authApi = ApiManager.create<AuthApi>()
    
    suspend fun login(request: LoginRequest): ApiResponse<LoginResponse> {
        return executeRequestResponse(
            request = { authApi.login(request) },
            enableRetry = true,
            retryTimes = 3
        ).onSuccess { data ->
            ILog.d("Auth", "登录成功")
        }.onError { code, message ->
            ILog.w("Auth", "登录失败: $code - $message")
        }.onException { exception ->
            ILog.e("Auth", "登录异常: ${exception.message}")
        }
    }
}

// 2. 创建 Repository（继承 ApiBaseRepository）
class AuthRepository(
    private val remoteDataSource: AuthRemoteDataSource
) : ApiBaseRepository() {
    suspend fun login(request: LoginRequest): ApiResponse<LoginResponse> {
        return remoteDataSource.login(request)
    }
    
    // 如果需要 Result<T>，使用 toResult() 转换
    suspend fun loginAsResult(request: LoginRequest): Result<LoginResponse> {
        return remoteDataSource.login(request).toResult()
    }
}
```

### 全局处理配置（可选）

```kotlin
// 在 AppInitializer 中配置
GlobalApiOperator.globalErrorHandler = { error ->
    // 全局错误处理（例如 Toast 提示）
    Toast.makeText(context, error.message, Toast.LENGTH_SHORT).show()
}

GlobalApiOperator.globalExceptionHandler = { exception ->
    // 全局异常处理（例如日志记录）
    ILog.e("Global", "API 异常: ${exception.exception.message}")
}
```

### 关键点

1. **ApiManager**: 业务层统一入口，最简单
2. **NetworkManager**: 基础设施，业务层不需要直接使用
3. **ApiBaseRemoteDataSource**: RemoteDataSource 继承使用，减少重复代码
4. **ApiResponse**: 统一的响应封装，清晰表达三种状态
5. **GlobalApiOperator**: 全局处理，减少重复代码
6. **ExceptionHandle**: 自动使用，统一异常处理
7. **HeaderInterceptor**: 自动使用，统一请求头
8. **TokenRefreshInterceptor**: 自动使用，Token 刷新

---

## 🔄 数据流

```
1. 业务层调用
   ViewModel.login() 
   
2. Repository 处理
   AuthRepository.login()
   
3. RemoteDataSource 执行网络请求
   AuthRemoteDataSource.login()
   └── executeRequestResponse()
       └── ApiManager.create<AuthApi>().login()
       
4. NetworkManager 构建请求
   NetworkManager.getRetrofit()
   ├── HeaderInterceptor（添加请求头）
   └── TokenRefreshInterceptor（Token 刷新）
   
5. 服务器返回
   Response<ApiCommonResult<LoginResponse>>
   
6. ApiResponseParser 解析
   ApiResponseParser.parseResponse()
   └── 检查 HTTP 状态码
   └── 检查业务状态码
   └── 提取 data
   └── 转换为 ApiResponse<T>
   
7. 全局处理
   GlobalApiOperator.apply()
   └── 应用全局错误处理
   └── 应用全局异常处理
   
8. 异常处理
   ExceptionHandle.handle()
   └── 转换为 ApiException
   
9. 返回结果
   ApiResponse<LoginResponse>
   
10. 业务层处理
    response.onSuccess { ... }
          .onError { code, message -> ... }
          .onException { exception -> ... }
```

---

## 📝 总结

| 类名 | 职责 | 使用者 | 使用频率 |
|------|------|--------|---------|
| **ApiManager** | 业务层入口，简化使用 | 业务层 | ⭐⭐⭐⭐⭐ |
| **NetworkManager** | 网络基础设施 | ApiManager、能力层 | ⭐⭐⭐ |
| **ApiBaseRemoteDataSource** | 封装网络请求逻辑 | RemoteDataSource | ⭐⭐⭐⭐ |
| **ApiResponseParser** | 解析响应为 ApiResponse | ApiBaseRemoteDataSource | ⭐⭐⭐⭐ |
| **ApiResponse** | 响应封装（Success/Error/Exception） | 业务层 | ⭐⭐⭐⭐⭐ |
| **GlobalApiOperator** | 全局响应处理器 | ApiBaseRemoteDataSource | ⭐⭐⭐⭐ |
| **ExceptionHandle** | 统一异常处理 | 自动使用 | ⭐⭐⭐⭐ |
| **HeaderInterceptor** | 添加请求头 | NetworkManager | ⭐⭐⭐⭐ |
| **TokenRefreshInterceptor** | Token 刷新拦截器 | NetworkManager | ⭐⭐⭐⭐ |
| **ApiException** | 自定义异常 | ExceptionHandle | ⭐⭐⭐⭐ |
| **ApiBaseRepository** | Repository 基类 | Repository | ⭐⭐⭐ |

**核心原则**: 
- 业务层只需关心 `ApiManager.create<>()` 和 `executeRequestResponse()`
- 其他组件自动工作，业务层无需关心细节
- 响应封装清晰（Success/Error/Exception），代码更简洁

---

## 🆕 ApiResponse 使用指南（参考 Sandwich 设计）

### 9. ApiResponseCallAdapterFactory（Retrofit 适配器）

**文件**: `adapter/ApiResponseCallAdapterFactory.kt`

**作用**: 
- 让 Retrofit 接口直接返回 `ApiResponse<T>`，无需手动解析
- 自动将 `Response<ApiCommonResult<T>>` 转换为 `ApiResponse<T>`

**特点**:
- ✅ 已自动注册到 `NetworkManager`，无需手动配置
- ✅ 接口定义更简洁，直接返回 `ApiResponse<T>`
- ✅ 类型更安全，编译时检查

**使用示例**:
```kotlin
// 接口定义（推荐方式，直接返回 ApiResponse<T>）
interface AuthApi {
    @POST("member/auth/login")
    suspend fun login(@Body request: LoginRequest): ApiResponse<LoginResponse>
}

// 使用（无需手动解析）
val response: ApiResponse<LoginResponse> = authApi.login(request)
response.onSuccess { data -> /* 处理成功 */ }
        .onError { code, message -> /* 处理业务错误 */ }
        .onException { exception -> /* 处理异常 */ }
```

---

### 10. ApiResponse（响应封装）

**文件**: `response/ApiResponse.kt`

**作用**: 
- 统一封装三种响应状态：Success（成功）、Error（业务错误）、Exception（网络异常）
- 参考 Sandwich 设计，提供更清晰的响应处理方式

**三种状态**:
- `Success<T>`: HTTP 200 且业务状态码 = 0，成功返回数据
- `Error<T>`: HTTP 200 但业务状态码 != 0，业务层面的错误
- `Exception<T>`: HTTP 非 200 或网络异常，网络层面的错误

**设计优势**:
- ✅ **平级结构更直观** - Success/Error/Exception 平级设计，使用时不需要嵌套 `Failure`
- ✅ **代码更简洁** - `when (response) { is Success -> ... is Error -> ... is Exception -> ... }` 直接匹配
- ✅ **IDE 友好** - 类型检查和自动补全更清晰
- ✅ **功能等价** - 与 Sandwich 的嵌套结构（Success/Failure.Error/Failure.Exception）功能完全等价，但使用更简单

**使用示例**:
```kotlin
val response: ApiResponse<LoginResponse> = executeRequestResponse(
    request = { authApi.login(request) },
    enableRetry = true,
    retryTimes = 3
)

response.onSuccess { data ->
    // 处理成功
    ILog.d("Auth", "登录成功: ${data.token}")
}.onError { code, message ->
    // 处理业务错误
    ILog.w("Auth", "登录失败: $code - $message")
}.onException { exception ->
    // 处理异常
    when (exception) {
        is NetworkException -> { /* 网络错误 */ }
        is BusinessException -> { /* 业务错误 */ }
        else -> { /* 其他错误 */ }
    }
}

// 如果需要 Result<T>，使用 toResult() 转换
val result: Result<LoginResponse> = response.toResult()
```

### 11. ApiResponseExtensions（扩展函数）

**文件**: `response/ApiResponseExtensions.kt`

**作用**: 
- 提供链式调用，简化响应处理
- 支持数据转换、默认值恢复等功能

**所有扩展函数**（与 Sandwich 完全对齐）:
- **核心处理**: `onSuccess()`, `onError()`, `onException()` - 响应处理
- **数据转换**: `map()`, `mapSuccess()`, `mapFailure()` - 数据转换
- **数据验证**: `validate()` - 数据验证（支持 lambda 构建错误消息）
- **非空检查**: `requireNotNull()` - 非空检查（支持 suspend 版本和 lambda 版本）
- **失败恢复**: `recover()`, `recoverValue()`, `recoverNull()`, `recoverWith()` - 失败时恢复（`recoverWith()` 支持 suspend 版本）
- **组合响应**: `zip()`, `zip3()` - 组合多个 ApiResponse（支持 suspend 版本）
- **Flow 转换**: `toFlow()`, `toFlowResponse()` - 转换为 Flow
- **suspend 版本**: `suspendOnSuccess()`, `suspendOnError()`, `suspendOnException()`, `suspendRequireNotNull()`, `suspendRecoverWith()`, `suspendZip()`, `suspendZip3()`

**✅ 所有扩展函数都已与 Sandwich 对齐，功能完整！**

**使用示例**:
```kotlin
// 链式调用
apiResponse
    .onSuccess { data -> println("成功: $data") }
    .onError { code, message -> println("错误: $code - $message") }
    .onException { exception -> println("异常: ${exception.message}") }

// 数据转换
val userResponse: ApiResponse<User> = api.getUser()
val nameResponse: ApiResponse<String> = userResponse.map { it.name }

// 失败时返回默认值
val userResponse: ApiResponse<User> = api.getUser()
val userWithDefault: ApiResponse<User> = userResponse.recover { User.default() }

// 组合多个响应
val userResponse: ApiResponse<User> = api.getUser()
val profileResponse: ApiResponse<Profile> = api.getProfile()
val combined: ApiResponse<UserProfile> = userResponse.zip(profileResponse) { user, profile ->
    UserProfile(user, profile)
}

// 非空检查
val profileImageResponse: ApiResponse<String> = userResponse.requireNotNull(
    selector = { it.profileImage },
    errorMessage = "用户头像不能为空"
)

// 失败时恢复（备用响应）
val recovered: ApiResponse<User> = userResponse.recoverWith { failure ->
    when (failure) {
        is ApiResponse.Error -> getCachedUser()
        is ApiResponse.Exception -> getFallbackUser()
    }
}
```

### 12. GlobalApiOperator（全局处理器）

**文件**: `operator/GlobalApiOperator.kt`

**作用**: 
- 统一处理所有 API 响应
- 支持全局错误处理、异常处理等
- 支持多个 Operator 链式调用（日志、Toast、埋点等）

**使用方式**:

**推荐方式：使用 Operator 接口（支持多个 Operator 链式调用）**
```kotlin
// 在 AppInitializer 中配置（可选）
// 自定义 Operator
class LogOperator : ApiResponseOperator<Any> {
    override suspend fun invoke(response: ApiResponse<Any>): ApiResponse<Any> {
        when (response) {
            is ApiResponse.Success -> ILog.d("API", "成功: $response")
            is ApiResponse.Error -> ILog.w("API", "错误: ${response.code} - ${response.message}")
            is ApiResponse.Exception -> ILog.e("API", "异常: ${response.exception.message}")
        }
        return response
    }
}

class ToastOperator : ApiResponseOperator<Any> {
    override suspend fun invoke(response: ApiResponse<Any>): ApiResponse<Any> {
        when (response) {
            is ApiResponse.Error -> Toast.makeText(context, response.message, Toast.LENGTH_SHORT).show()
            is ApiResponse.Exception -> Toast.makeText(context, "网络错误", Toast.LENGTH_SHORT).show()
            else -> { /* 不处理 */ }
        }
        return response
    }
}

// 注册多个 Operator（按注册顺序链式调用）
GlobalApiOperator.addOperator(LogOperator())
GlobalApiOperator.addOperator(ToastOperator())
```

**注意**: 
- Token 刷新已在 `TokenRefreshInterceptor` 中统一处理，`GlobalApiOperator` 不处理 Token 刷新
- 多个 Operator 会按注册顺序链式调用
- 支持 suspend Operator，可以执行异步操作

### 13. RetryOperator（重试机制）

**文件**: `operator/RetryOperator.kt`

**作用**: 
- 自动重试失败的请求
- 支持指数退避策略
- 支持 Long 毫秒和 Duration 两种版本

**使用方式**:

**使用 Duration（推荐，更现代）**
```kotlin
import kotlin.time.Duration.Companion.seconds

val response = retryRequest(
    times = 3,                      // 最多重试 3 次
    initialDelay = 1.seconds,       // 初始延迟 1 秒
    maxDelay = 10.seconds,          // 最大延迟 10 秒
    factor = 2.0,                   // 延迟翻倍（指数退避）
    shouldRetry = { response ->     // 只有网络异常才重试
        response is ApiResponse.Exception
    }
) {
    api.getData()
}
```

### 14. ApiResponseParser（响应解析器）

**文件**: `ApiResponseParser.kt`

**方法**:
- `parseResponse()`: 返回 `ApiResponse<T>`（使用 reified 泛型自动推断类型）
- `parseNullableResponse()`: 返回 `ApiResponse<T?>`（支持可空数据）

**使用示例**:
```kotlin
val response: ApiResponse<LoginResponse> = ApiResponseParser.parseResponse(
    response = retrofitResponse,
    tag = "Auth"
)

response.onSuccess { data -> ... }
        .onError { code, message -> ... }
        .onException { exception -> ... }
```

### 15. ApiBaseRemoteDataSource（远程数据源基类）

**文件**: `ApiBaseRemoteDataSource.kt`

**方法**:
- `executeRequestResponse()`: 返回 `ApiResponse<T>`（支持重试和全局处理）
- `executeNullableRequestResponse()`: 返回 `ApiResponse<T?>`（支持可空数据）

**使用示例**:
```kotlin
class AuthRemoteDataSource : ApiBaseRemoteDataSource() {
    suspend fun login(request: LoginRequest): ApiResponse<LoginResponse> {
        return executeRequestResponse(
            request = { authApi.login(request) },
            enableRetry = true,      // 启用自动重试
            retryTimes = 3           // 重试 3 次
        ).onSuccess { data ->
            ILog.d("Auth", "登录成功")
        }.onError { code, message ->
            ILog.w("Auth", "登录失败: $code - $message")
        }.onException { exception ->
            ILog.e("Auth", "登录异常: ${exception.message}")
        }
    }
    
    // 如果需要 Result<T>，使用 toResult() 转换
    suspend fun loginAsResult(request: LoginRequest): Result<LoginResponse> {
        return executeRequestResponse(
            request = { authApi.login(request) }
        ).toResult()
    }
}
```

