原文：http://square.github.io/retrofit/
简介
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 请求：
- URL 参数替换，查询后的参数支持
- 对象转化为请求Body格式（例如，JSON，协议缓冲区）
- 多类型的请求Body和文件上传组合
备注：这个部分正在在开发中，会在新的 2.0 API中完成拓展。
API 定义
用注解来标注接口方法和参数，就可以完成整个 HTTP 请求的构建。
请求方法
所有的 HTTP 请求无非五种，也对应着五种注解，这些注解在标记请求的时候都是必须的，它们后面跟着的内容是请求的 URL，这五种是：GET, POST, PUT, DELETE, HEAD。
@GET("users/list")
也可以在 URL 中写上查询参数
@GET("users/list?sort=desc")
URL 设置
请求 URL 可以通过替换块来动态调整，替换块是一个由大括号{}括起来的字符串。参数必须在注解 @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
可以通过注解 @Body 来转化对象，为 HTTP 请求 添加 body
@POST("users/new")
Call<User> createUser(@Body User user);
该对象也需要通过 Retrofit 实例来转化，如果没有添加过这样的转化，只有 RequestBody 这种对象类型可以使用。
表单数据(form encoded) 和 multipart
表单数据需要添加注解 @FormUrlEncoded，每一个键值对通过注解 @Field 来添加。
@FormUrlEncoded
@POST("user/edit")
Call<User> updateUser(@Field("first_name") String first, @Field("last_name") String last);
multiPart 请求需要使用注解 @Multipart，每一个部分由注解 @Part 标记。
@Multipart
@PUT("user/photo")
Call<User> updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);
MultiPart 也需要通过 Retrofit 实例的转化，否则只能通过实现 RequestBody 来完成序列化。
头部（Header）设置
可以通过注解 @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 来动态配置，如果值为空，则改条会被忽略，反之，改值的 toString 方法会被调用，用于添加头部信息。
@GET("user")
Call<User> getUser(@Header("Authorization") String authorization)
每个请求都需要添加的通用头部可以使用 OkHttp interceptor.
同步异步
Call 实例可以在同步或者异步中执行。每个实例仅会使用一次，但可以通过 clone() 方法来获取一个新的实例来使用。
在 Android 中，回调将在主进程中执行。在 JVM 中，回调会在执行 HTTP 请求的同一个线程中执行。
Retrofit 配置
Retrofit 是一个将你的 API 接口转化为可调用对象的类。默认的，Retrofit 会给你一整套设置，但它也允许个性化配置。
转化器（Converters）
默认的，Retrofit 只能反序列化 HTTP body 到 OkHttp 的 ResponseBody 类型的对象，并且它只能接受 ResponseBody 类型的对象作为 @Body 的参数。
可以添加转化器用于支持其他的类型。下面列举六种模型比较欢迎的模型和对应的库。
Gson: com.squareup.retrofit2:converter-gson
Jackson: com.squareup.retrofit2:converter-jackson
Moshi: com.squareup.retrofit2:converter-moshi
Protobuf: com.squareup.retrofit2:converter-protobuf
Wire: com.squareup.retrofit2:converter-wire
Simple XML: com.squareup.retrofit2:converter-simplexml
Scalars (primitives, boxed, and String): com.squareup.retrofit2:converter-scalars
下面是一个使用 GsonConverterFactory 类来实现一个 GitHubService 接口的例子，其中用到了 Gson 作为反序列化方法。
Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://api.github.com")
.addConverterFactory(GsonConverterFactory.create())
.build();
GitHubService service = retrofit.create(GitHubService.class);
自定义转化器
如果需要和一个 Retrofit 本身不支持的格式进行转化（例如 YAML, txt, 自定义格式），或者你想用一个不一样的库去实现已有的格式，你可以加单地创建自定义转化器。创建一个类，继承父类 Converter.Factory，并将其传给你的 Retrofit 实例中即可。
下载
JAR
↓ v2.0.2 JAR
Source code
available on GitHub.
Maven
<dependency>
<groupId>com.squareup.retrofit2</groupId>
<artifactId>retrofit</artifactId>
<version>2.0.2</version>
</dependency>
Gradle
compile 'com.squareup.retrofit2:retrofit:2.0.2'
Proguard
如果在项目中用到了 Proguard，在配置里添加下述代码：
-dontwarn retrofit2.**
-keep class retrofit2.** { *; }
-keepattributes Signature
-keepattributes Exceptions
