Retrofit 2.0 實戰入門：從接口定義到動態代理調用的完整流程

核心依賴

<dependency>
    <groupId>com.squareup.retrofit2</groupId>
    <artifactId>retrofit</artifactId>
    <version>2.0.1</version>
</dependency>
<dependency>
    <groupId>com.squareup.retrofit2</groupId>
    <artifactId>converter-gson</artifactId>
    <version>2.0.1</version>
</dependency>
<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.6.1</version>
</dependency>
<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>3.3.1</version>
</dependency>

構建 Retrofit 實例

OkHttpClient client = new OkHttpClient.Builder().build();

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

定義 API 接口

public interface ApiService {
    @GET("v1/items")
    Call<ItemList> listItems(@Query("page") int page);

    @POST("v1/items")
    Call<Item> createItem(@Body Item item);

    @PUT("v1/items/{id}")
    Call<Item> updateItem(@Path("id") String id, @Body Item item);

    @DELETE("v1/items/{id}")
    Call<Void> deleteItem(@Path("id") String id);
}

關鍵註解對照

同步/異步調用

ApiService service = retrofit.create(ApiService.class);

// 同步
Response<ItemList> resp = service.listItems(1).execute();
if (resp.isSuccessful()) { ... }

// 異步
service.listItems(1).enqueue(new Callback<ItemList>() {
    @Override public void onResponse(Call<ItemList> call, Response<ItemList> resp) { ... }
    @Override public void onFailure(Call<ItemList> call, Throwable t) { ... }
});

錯誤處理最佳實踐

Response<ItemList> resp = call.execute();
if (!resp.isSuccessful()) {
    // 解析錯誤體
    Converter<ResponseBody, ErrorResp> converter =
        retrofit.responseBodyConverter(ErrorResp.class, new Annotation[0]);
    ErrorResp error = converter.convert(resp.errorBody());
    throw new ApiException(resp.code(), error.getMessage());
}
return resp.body();

單元測試：MockWebServer

MockWebServer server = new MockWebServer();
server.start();

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl(server.url("/"))
    .addConverterFactory(GsonConverterFactory.create())
    .build();

server.enqueue(new MockResponse()
    .setResponseCode(200)
    .setBody("{\"items\":[]}"));

ApiService service = retrofit.create(ApiService.class);
service.listItems(1).execute();  // 驗證請求/響應

server.shutdown();

總結

• Retrofit 2.x 核心：Retrofit.Builder + 接口 + Call<T>
• 轉換器工廠支援 Gson、Moshi、Protobuf 等
• 攔截器（OkHttp）實現日誌、認證、重試等橫切關注點
• MockWebServer 實現無後端聯調測試