Retrofit研究1

　　如下爲來自Github的retrofit的介紹。話說，翻譯還真蛋疼，就這個花了快3個小時。

Retrofit 
一個在Android和Java上類型安全的HTTP客戶端

介紹
Retrofit能夠把你的HTTP API轉換成java接口。
public interface GitHubService {
    @GET("users/{user}/repos")
    Call<List<Repo>> listRepos(@Path("user") String user);
}
Retrofit類實現GitHubService接口的實現。
Retrofit retrofit = new Retrofit.Builder().baseUrl("https://api.github.com").build();
GitHubService service = retrofit.create(GitHubService.class);
建立的GitHubService的每一個 Call 能夠產生一個同步的或者異步的HTTP請求到遠程網絡服務器。
Call<List<Repo>> repos = service.listRepos("octocat");
使用註釋來描述HTTP請求：
1.支持URL參數替換和查詢參數
2.請求body的對象轉換(例如JSON,協議buffers)
3.Multipart的請求body和file上傳

API描述
在接口方法和它的參數上面的註解暗示了請求怎麼處理。

請求方法
每一個方法必須有一個提供請求方法和相關URL的HTTP註解。這裏有五個內置的註解：GET,POST,PUT,DELETE,和
HEAD.相關資源的URL被指定在註解中。
@GET("users/list")
你也能夠在URL中指定查詢的參數。
@GET("users/list?sort=desc")

URL操做
一個請求的URL能夠用替代塊和方法中的參數來動態更新。一個替代塊是一個由{and}環繞的字母數字字符串。
一個匹配的參數必須使用一樣的字符串的 @Path來註解。
@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId);
也能夠添加查詢參數
@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId,@Query("sort") String sort);
複雜的查詢參數能夠用一個組合的Map.
@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId),@QueryMap Map<String,String> options);

請求塊
一個對象能夠指定成一個用 @Body註解的HTTP請求body
@POST("users/new")
Call<User> createUser(@Body User user);
這個對象能夠被Retrofit實例指定的轉換者converter來轉換。若是沒有添加轉換者，那麼僅僅RequestBody能夠被添加。

編碼形式和Multipart
方法能夠被定義來發送form-encoded和multipart 數據。
當 @FormUrlEncoded出如今方法中編碼形式的數據就能夠發送。每一個鍵值對被用包含了名字和提供了值的對象的 
@Field註解。
@FormUrlEncoded
@POST("user/edit")
Call<User> updateUser(@Field("first_name") String first,@Field("last_name") String last);
當 @Multipart 出如今方法中可使用Multipart 請求。Parts能夠用 @Part註解來聲明。
@Multipart
@PUT("user/photo")
Call<User> updateUser(@Part("photo") RequestBody photo,@Part("description") RequestBody description);
Multipart部分使用Retrofit的一個轉換器或者它們能夠實現RequestBody來處理它們本身的序列化。

頭操做(HEADER MANIPULATION)
你能夠用 @Headers 註解來給方法設置靜態的headers。
@Headers("Cache-Control:max-age=640000")
@GET("widget/list")
Call<List<Widget>> widgetList();

@Headers({
    "Accept: application/vnd.github.v3.full+json",
    "User-Agent: Retrofit-Sample-App"
})
@GET("users/{username}")
Call<User> getUser(@Path("username") String username);
注意不能每一個頭部都重寫。全部的使用一樣名字的頭部都將被包含在請求中。
一個請求頭可使用 @Header註解來動態更新。一個匹配的參數是必需要提供 @Header。若是值爲null,那麼
頭將被省略。不然，toString 將會調用這個值，而且使用這個結果。
@GET("user")
Call<User> getUser(@Header("Authorization") String authorization)
須要被添加到每一個請求的Header頭部能夠用OkHttp interceptor插值器來指定。

同步與異步
Call 實例能夠被同步或者異步來調用。每一個實例僅僅被使用一次，可是呼叫clone()將會在使用的時候建立一個
新的實例。
在Android中，回調將會在main線程中執行。在JVM中，回調將會執行了HTTP請求的同一個線程中發生。

Retrofit配置
Retrofit是一個經過將你的API接口轉換成可調用的對象的類。默認地，Retrofit將針對你的平臺給你一個健全的
默認配置，可是也容許定製。

轉換器
默認的，Retrofit僅僅能夠支持反序列化HTTP的Body到OkHttp的ResponseBody類型，並且僅僅只能用 @Body 接受它的
RequestBody類型。
轉換器能夠被添加支持其它類型。六個同級的模塊能夠方便適配流行的序列化庫。
1.Gson:com.squareup.retrofit2:converter-gson
2.Jackson:com.squareup.retrofit2:converter-jackson
3.Moshi:com.squareup.retrofit2:converter-protobuf
4.Wire:com.squareup.retrofit2:converter-wire
5.Simple XML:com.squareup.retrofit2:converter-simplexml
6.Scalars(原始的primitives，打包的boxed，和字符串String):com.squareup.retrofit2:converter-scalars
這裏是一個使用GsonConverterFactory類生成使用了Gson的反序列化的GitHubService接口的實現的例子。
Retrofit retrofit = new Retrofit.Builder().baseUrl("https://api.github.com").addConverterFactory(
GsonConverterFactory.create()).build();
GitHubService service = retrofit.create(GitHubService.class);

定製的轉換器
若是你須要和使用了Retrofit不支持的內容格式(例如YAML，txt,定製的格式)的API交流或者你但願使用不一樣的庫
來實現一個存在的格式，那麼你能夠輕易地建立你本身的轉換器。經過繼承Converter.Factory類建立一個類，而且當
構建你的適配器時傳到實例裏面去。

MAVEN
<dependency>
  <groupId>com.squareup.retrofit2</groupId>
  <artifactId>retrofit</artifactId>
  <version>(insert latest version)</version>
</dependency>

GRADLE
compile 'com.squareup.retrofit2:retrofit:(insert latest version)'

Retrofit要求最小Java7或者Android 2.3

混淆
若是你在你的工程中使用混淆器，那麼在你的配置中添加下列行：
-dontwarn retrofit2.**
-keep class retrofit2.** { *; }
-keepattributes Signature
-keepattributes Exceptions

Apache 版權