Retrofit：型別安全的REST用戶端for 安卓&Java

標籤：des   http   java   os   檔案   資料   io   2014   

Retrofit：型別安全的REST用戶端for 安卓&Java

2014年5月5日 星期一

21:11

官網：  http://square.github.io/retrofit/

GitHub地址： https://github.com/square/retrofit

JavaDocs地址： http://square.github.io/retrofit/javadoc/index.html

 本隨筆是對官網教程的一個翻譯，放出來供大家參考！

大綱

@GET,@POST,@PUT,@DELETE,@HEAD

@Path :{id}

@Query :name=value

@QueryMap

@Body ：傳對象

@FormUrlEncoded,@Field

@Multipart,@Part :TypedFile 傳送檔案

@Headers ,@Header

RequestInterceptor ：通過攔截器添加Header

Callback(void返回)，Observable：非同步

返回Response

setConverter：配置Gson，自動以轉換器

setErrorHandler：設定錯誤處理

 

 

 

 

概覽：將你的請求API定義在一個Java 介面中：

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

然後通過RestAdapter類來產生一個該介面的實現。

RestAdapter restAdapter = new RestAdapter.Builder()     .setEndpoint("https://api.github.com")     .build();   GitHubService service = restAdapter.create(GitHubService.class);

然後就可以調用了：

List<Repo> repos = service.listRepos("octocat");

 

一. 通過註解來進行HTTP請求：

1. URL參數替換和query參數支援（就是?name=value&…的意思）
2. 自定進行POJO類轉換（自動將響應轉換成POJO類，GSON）
3. Multipart請求對象和檔案上傳支援（請求中包含多種媒體類型，片等）

 

二. 要求方法：

支援GET，POST，PUT，DELETE，HEAD

1. 正常的請求：

//要求方法：通過註解進行請求 //普通請求 @GET("/users/list") //請求中可以直接加query parameter：sort=desc @GET("/users/list?sort=desc") //可以通過@Path註解和{name}文法替換參數:id @GET("/group/{id}/users") List<User> groupList(@Path("id") int groupId); //可以通過@Query添加請求參數:sort @GET("/group/{id}/users") List<User> groupList(@Path("id") int groupId, @Query("sort") String sort); //可以通過@QueryMap大量新增請求參數：options @GET("/group/{id}/users") List<User> groupList(@Path("id") int groupId, @QueryMap Map<String, String> options);

1. 特殊的請求：

//通過@Body可以直接發送一個對象，通過RestAdapter進行轉換 @POST("/users/new") void createUser(@Body User user, Callback<User> cb); //通過@FormUrlEncoded和@Field註解發送form-encoded data？TODO @FormUrlEncoded @POST("/user/edit") User updateUser(@Field("first_name") String first, @Field("last_name") String last); //Multipart請求通過@Multipart和@Part註解 @Multipart @PUT("/user/photo") User updateUser(@Part("photo") TypedFile photo, @Part("description") TypedString description);

1. 添加Header

//靜態添加方式 //添加單個頭部 @Headers("Cache-Control: max-age=640000") @GET("/widget/list") List<Widget> widgetList(); //@Headers多個頭部資訊：可以有重複的名字 @Headers({ "Accept: application/vnd.github.v3.full+json", "User-Agent: Retrofit-Sample-App" }) @GET("/users/{username}") User getUser(@Path("username") String username); //動態添加頭部 //動態添加頭部:authorization @GET("/user") void getUser(@Header("Authorization") String authorization, Callback<User> callback)   //添加所有資訊 //如果想將頭部加到所有的請求上，可以通過RequestIntercepter類。 RequestInterceptor requestInterceptor = new RequestInterceptor() { @Override public void intercept(RequestFacade request) { request.addHeader("User-Agent", "Retrofit-Sample-App"); } };   RestAdapter restAdapter = new RestAdapter.Builder() .setEndpoint("https://api.github.com") .setRequestInterceptor(requestInterceptor) .build();

 

1. 同步非同步和rx.Observable

//有返回的方法是同步方法 @GET("/user/{id}/photo") Photo getUserPhoto(@Path("id") int id); //最後一個方法是Callback<T>的話就是非同步請求（T是要返回的資料） @GET("/user/{id}/photo") void getUserPhoto(@Path("id") int id, Callback<Photo> cb); //Retrofit同時整合了R小Java去支援返回一個rx.Observable來支援非同步請求 @GET("/user/{id}/photo") Observable<Photo> getUserPhoto(@Path("id") int id);

三. 返回物件類型：可以通過函數傳回型別，Callback，Observable得到

//通過返回對象 @GET("/users/list") List<User> userList(); //通過Callback @GET("/users/list") void userList(Callback<List<User>> cb); //通過Observable @GET("/users/list") Observable<List<User>> userList();

可以返回原生的Http Response：通過返回Response

@GET("/users/list") Response userList();   @GET("/users/list") void userList(Callback<Response> cb);   @GET("/users/list") Observable<Response> userList();

 

四. RestAdapter 配置：可以預設配置也可以自訂

1. 配置Gson：自訂GSON執行個體的例子

Gson gson = new GsonBuilder()     .setFieldNamingPolicy(FieldNamingPolicy.LOWER_CASE_WITH_UNDERSCORES)     .registerTypeAdapter(Date.class, new DateTypeAdapter())     .create();   RestAdapter restAdapter = new RestAdapter.Builder()     .setEndpoint("https://api.github.com")     .setConverter(new GsonConverter(gson))     .build();   GitHubService service = restAdapter.create(GitHubService.class);

1. 返回資料類型的配置(可以支援XML)：預設是JSON，也可以定義Convertor去支援xml等其他返回資料格式（如預設還有一個SimpleXMLConverter）

RestAdapter restAdapter = new RestAdapter.Builder()     .setEndpoint("https://api.soundcloud.com")     .setConverter(new SimpleXMLConverter())     .build();   SoundCloudService service = restAdapter.create(SoundCloudService.class);

1. 自訂轉換器：去實現Converter介面皆可。
2. 自訂同步請求的錯誤處理器：ErrorHandler

class MyErrorHandler implements ErrorHandler {   @Override public Throwable handleError(RetrofitError cause) {     Response r = cause.getResponse();     if (r != null && r.getStatus() == 401) {       return new UnauthorizedException(cause);     }     return cause;   } }   RestAdapter restAdapter = new RestAdapter.Builder()     .setEndpoint("https://api.github.com")     .setErrorHandler(new MyErrorHandler())     .build();

 

Maven整合：

<dependency>   <groupId>com.squareup.retrofit</groupId>   <artifactId>retrofit</artifactId>   <version>1.5.0</version> </dependency>