本文算不上原创，只是大概翻译了 Retrofit 的英文文档，权当做是自己的笔记而已。
英文原地址：http://square.github.io/retrofit/
1.介绍
Retrofit 把你的 HTTP API 转换为一个Java 接口。
1 public interface GitHubService {2 @GET("/users/{user}/repos")3 Call<List<Repo>> listRepos(@Path("user") String user);4 }
Retrofit生成了 GithubService 接口的一个实现类。
1 Retrofit retrofit = new Retrofit.Builder()2 .baseUrl("https://api.github.com")3 .build();4 5 GitHubService service = retrofit.create(GitHubService.class);
从生成的 GitHubService 发出的每一个 Call 都可以向远程的 Web服务器发出一个同步或者异步的HTTP请求。
1 Call<List<Repo>> repos = service.listRepos("octocat");
使用 annotations 描述 HTTP 请求:
- 支持 URL 参数替换和请求参数
- 支持对象转为请求体 (e.g.,JSON, protocol buffers)
- 支持多个 request body 和 文件上传
2.API 的声明
接口方法上的 Annotations 和它的参数标明了这个请求是如何被处理的。
a.请求方法
每个方法必须有一个提供了 request method 和 releative URL 的 HTTP annotation。Retrofit 内置了五种 annotations ：GET, POST, PUT, DELETE, 和HEAD。在 annotation 中资源的 relative URL 是被指定的。
1 @GET("/users/list")
你也可以在 URL 中指定请求参数。
1 @GET("/users/list?sort=desc")
b.URL处理
一个请求 URL 可以被其中的 replacement block 和方法上的参数动态的替换。replacement block 是一个被“{ }”包裹的含有字母或数字的字符串。相对应的参数必须是一个带有 @Path 的相同的字符串。即：
1 @GET("/group/{id}/users")2 List<User> groupList(@Path("id") int groupId);
查询的参数也可以被添加进来。
1 @GET("/group/{id}/users")2 List<User> groupList(@Path("id") int groupId, @Query("sort") String sort);
对于复杂的查询参数可以组合成一个 Map 来使用。
1 @GET("/group/{id}/users")2 List<User> groupList(@Path("id") int groupId, @QueryMap Map<String, String> options);
c.请求体
一个带有 @Body 注解的对象可以被当做 HTTP 的请求体。
1 @POST("/users/new")2 Call<User> createUser(@Body User user);
这个对象可以被 Retrofit 指定的转换器转换。如果没有指定，只有在 RequestBody 才能被使用。
d.Form Encoded and Multipart
Methods 也可以被声明发送 form-encoded 和 MutiPart 数据。
使用 form-encoded 时要在 Method 上面添加 @FormUrlEncoded 注解。每一个键值对使用 @Field 注解包裹 key。即：
1 @FormUrlEncoded2 @POST("/user/edit")3 Call<User> updateUser(@Field("first_name") String first, @Field("last_name") String last);
使用多个请求时，要在 Method 上添加 @Multipart 注解，每部分使用 @Part 添加声明。即：
1 @Multipart2 @PUT("/user/photo")3 Call<User> updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);
多个请求部分使用 Retrofit 的转换器或者自己实现 RequestBody 处理自己的序列化。
e.请求头的操纵
你可以使用 @Headers 为一个请求方法设置静态的请求头。
1 @Headers("Cache-Control: max-age=640000")2 @GET("/widget/list")3 Call<List<Widget>> widgetList();
1 @Headers({2 "Accept: application/vnd.github.v3.full+json",3 "User-Agent: Retrofit-Sample-App"4 })5 @GET("/users/{username}")6 Call<User> getUser(@Path("username") String username);
需要注意的是，所有的 Headers 之间不会重写，所有相同名字的 Headers 都会包含在请求里面。
一个请求的 Headers 可以使用 @Headers 注解动态的更新。必须要为 @Headers 设置一个字母或者数字的参数。如果真实的值是 null ，这个请求头会被忽略，否则会调用 toString() 方法，并且在请求中使用。
1 @GET("/user")2 Call<User> getUser(@Header("Authorization") String authorization)
Headers that need to be added to every request can be specified using an OkHttp interceptor.
f.同步 VS. 异步
Call 实例可以再同步或者异步中执行。每个实例只能使用一次，但是如否使用 clone() 方法就能再创建一个可以使用的实例了。
在 Android 中，回调会在主线程中执行。在 JVM 中回调会在发起 HTTP request 的同一线程中执行。
3.Retrofit 参数配置
Retrofit 是一个通过你的 API 接口转换为 可回调对象的类。Retrofit 为你提供了默认的配置，但是也允许你自定义配置。
a.转换器
默认情况下，Retrofit 只能讲 HTTP bodies 发序列化为 OkHttp 的 ResponeBody 类型，对于 @Body 来说也只能在接收 ResponeBody 类型。
转换器也可以支持下面类型：
- Gson:
com.squareup.retrofit:converter-gson - Jackson:
com.squareup.retrofit:converter-jackson - Moshi:
com.squareup.retrofit:converter-moshi - Protobuf:
com.squareup.retrofit:converter-protobuf - Wire:
com.squareup.retrofit:converter-wire - Simple XML:
com.squareup.retrofit:converter-simplexml
b.自定义转换器
你也可以通过继承 Converter.Factory class 自定义转换器，然后在创建 adapter 是传入这个类得实例。
4.集成方式
最新的 jar 包，请点击这里。
Retrofit 源码与示例程序 On Github。
Maven
<dependency> <groupId>com.squareup.retrofit</groupId> <artifactId>retrofit</artifactId> <version>(insert latest version)</version></dependency>
Gradle
compile 'com.squareup.retrofit:retrofit:(insert latest version)'
Retrofit 需要的环境：Java 7 以上及 Android 2.3以上。
ProGuard
1 -dontwarn retrofit.**2 -keep class retrofit.** { *; }3 -keepattributes Signature4 -keepattributes Exceptions