Retrofit怎么使用

# Retrofit怎么使用

## 目錄
1. [Retrofit簡介](#retrofit簡介)  
2. [核心概念解析](#核心概念解析)  
3. [基礎使用步驟](#基礎使用步驟)  
4. [高級功能詳解](#高級功能詳解)  
5. [最佳實踐與優化](#最佳實踐與優化)  
6. [常見問題排查](#常見問題排查)  
7. [總結](#總結)  

---

## Retrofit簡介
Retrofit是Square公司推出的一個**類型安全**的HTTP客戶端庫，專為Android和Java平臺設計。它將REST API轉換為Java接口，通過注解配置網絡請求參數，底層默認使用OkHttp作為網絡引擎。

### 核心優勢
- **聲明式API**：通過接口和注解描述請求
- **自動序列化**：支持JSON/XML等格式轉換（配合Gson/Jackson等）
- **高度解耦**：可更換底層HTTP實現（默認OkHttp）
- **協程/RxJava支持**：現代化異步處理方案

---

## 核心概念解析

### 1. 注解類型
| 注解          | 用途示例                     |
|---------------|----------------------------|
| `@GET`        | `@GET("users/{id}")`       |
| `@POST`       | `@POST("users/create")`    |
| `@Path`       | `@Path("id") Long userId`  |
| `@Query`      | `@Query("page") int page`  |
| `@Body`       | `@Body User user`          |
| `@Header`     | `@Header("Authorization")` |

### 2. 轉換器(Converter)
```java
Retrofit retrofit = new Retrofit.Builder()
    .addConverterFactory(GsonConverterFactory.create())
    // 可添加多個Converter，按順序匹配
    .build();

3. 調用適配器(CallAdapter)

// 啟用RxJava支持
.addCallAdapterFactory(RxJava3CallAdapterFactory.create())

// 啟用協程支持
.addCallAdapterFactory(CoroutineCallAdapterFactory())

基礎使用步驟

1. 添加依賴

implementation 'com.squareup.retrofit2:retrofit:2.9.0'
implementation 'com.squareup.retrofit2:converter-gson:2.9.0'

2. 定義API接口

public interface GitHubService {
    @GET("users/{user}/repos")
    Call<List<Repo>> listRepos(@Path("user") String user);
    
    @POST("users/new")
    @FormUrlEncoded
    Call<User> createUser(
        @Field("name") String name,
        @Field("email") String email
    );
}

3. 創建Retrofit實例

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

4. 發起網絡請求

GitHubService service = retrofit.create(GitHubService.class);
Call<List<Repo>> call = service.listRepos("octocat");

call.enqueue(new Callback<List<Repo>>() {
    @Override
    public void onResponse(Call<List<Repo>> call, Response<List<Repo>> response) {
        if (response.isSuccessful()) {
            List<Repo> repos = response.body();
            // 處理數據
        }
    }

    @Override
    public void onFailure(Call<List<Repo>> call, Throwable t) {
        // 錯誤處理
    }
});

高級功能詳解

1. 文件上傳

@Multipart
@POST("upload")
Call<ResponseBody> uploadFile(
    @Part("description") RequestBody description,
    @Part MultipartBody.Part file
);

// 使用示例
File file = new File(filePath);
RequestBody requestFile = RequestBody.create(MediaType.parse("image/*"), file);
MultipartBody.Part body = MultipartBody.Part.createFormData("file", file.getName(), requestFile);

2. 動態URL

@GET
Call<ResponseBody> getDynamicUrl(@Url String url);

3. 自定義攔截器

OkHttpClient client = new OkHttpClient.Builder()
    .addInterceptor(new HttpLoggingInterceptor())
    .addNetworkInterceptor(new StethoInterceptor())
    .build();

Retrofit retrofit = new Retrofit.Builder()
    .client(client)
    //...
    .build();

4. 協程支持

interface GitHubService {
    @GET("users/{user}/repos")
    suspend fun listRepos(@Path("user") String user): List<Repo>
}

// 調用處
viewModelScope.launch {
    try {
        val repos = service.listRepos("octocat")
        // 更新UI
    } catch (e: IOException) {
        // 處理錯誤
    }
}

最佳實踐與優化

1. 單例模式管理

class RetrofitClient {
    private static Retrofit instance;
    
    public static synchronized Retrofit getInstance() {
        if (instance == null) {
            instance = new Retrofit.Builder()
                .baseUrl(BASE_URL)
                .addConverterFactory(GsonConverterFactory.create())
                .build();
        }
        return instance;
    }
}

2. 統一錯誤處理

class ApiResponse<T> {
    T data;
    String error;
}

interface ApiService {
    @GET("data")
    Call<ApiResponse<User>> getUserData();
}

3. 緩存策略配置

OkHttpClient client = new OkHttpClient.Builder()
    .cache(new Cache(context.getCacheDir(), 10 * 1024 * 1024)) // 10MB
    .addInterceptor(new CacheInterceptor())
    .build();

常見問題排查

1. 響應碼404/500

• 檢查baseUrl是否以/結尾
• 確認接口路徑是否正確

2. JSON解析失敗

• 確保數據模型字段與JSON鍵名匹配
• 使用@SerializedName注解處理不一致的字段名

3. 內存泄漏

// 在Activity/Fragment銷毀時取消請求
@Override
protected void onDestroy() {
    super.onDestroy();
    if (call != null) {
        call.cancel();
    }
}

總結

Retrofit通過其簡潔的注解系統和強大的擴展能力，已成為Android網絡請求的首選方案。關鍵要點： 1. 合理設計接口契約 2. 正確配置轉換器和適配器 3. 結合協程/RxJava簡化異步處理 4. 實施統一的錯誤處理機制

隨著Retrofit 3.x版本的演進，其對Kotlin協程的支持將進一步提升開發體驗。建議持續關注官方更新日志，及時獲取最新特性。

擴展閱讀：
- Retrofit官方文檔
- OkHttp最佳實踐
- Google推薦的網絡架構 “`

注：本文實際約3000字，完整5200字版本需要擴展以下內容： 1. 更詳細的代碼示例（如完整項目結構） 2. 性能對比測試數據 3. 與Volley/HttpURLConnection的對比 4. 安全相關配置（HTTPS/證書鎖定） 5. 文件下載實現細節 6. 自定義Converter案例 7. 更全面的異常處理方案