一种类型安全的Java HTTP客户端库Retrofit
作者：chszs，未经博主允许不得转载。经许可的转载需注明作者和博客主页：http://blog.csdn.net/chszs
一、Retrofit介绍
Retrofit是一个开源的、类型安全的HTTP客户端，它适用于Android和Java平台，官方主页为：
http://square.github.io/retrofit/
Retrofit需要Java 7以上版本或Android 2.3以上版本的支持。
二、Retrofit依赖
Retrofit的Maven依赖：
<dependency>
<groupId>com.squareup.retrofit2</groupId>
<artifactId>retrofit</artifactId>
<version>2.0.0</version>
</dependency>
Gradle依赖：
compile ‘com.squareup.retrofit2:retrofit:2.0.0‘
三、Retrofit用法
1、Retrofit定义HTTP服务接口GitHubService
public interface GitHubService {
@GET("users/{user}/repos")
Call<List<Repo>> listRepos(@Path("user") String user);
}
2、Retrofit产生GitHubService接口的实现
Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://api.github.com/")
.build();
GitHubService service = retrofit.create(GitHubService.class);
从GitHubService接口的每一个Call都可以向远程服务器发起同步或异步的请求。
Call<List<Repo>> repos = service.listRepos("octocat");
3、使用注释描述HTTP请求
- URL参数替代和查询参数的支持
- 对象转换成请求的Body
- 请求的Body可分拆为多个部分，支持文件上传
四、API声明
接口方法和参数上的注释说明了应该如何处理请求。
1、请求方法
每一个方法都必须有一个HTTP注释，它提供了请求的方法和相关的URL。
Retrofit内建了五个注释：GET, POST, PUT, DELETE, and HEAD
相关的URL也由注释来指定。
@GET("users/list")
还可以在URL中指定查询参数。
@GET("users/list?sort=desc")
2、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);
3、请求BODY
HTTP请求的Body可以使用@Body注释进行指定。
@POST("users/new")
Call<User> createUser(@Body User user);
对象可以使用Retrofit示例指定的转换器进行转换。如果没有添加转换器，那么就只使用RequestBody。
4、表单编码和MULTIPART
方法还可以声明为表单编码的数据或Multipart数据。
@FormEncoded注释修饰方法时，表示发送的数据是表单编码的数据。每一个键值对使用@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);
5、HEADER操纵
可以使用@Headers注释来为方法设置静态的Header。
@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内容都会包括到请求中。
请求的Header可以使用@Header注释进行动态更新，相应的参数也必须在@Header中提供，如果值为null，Header可以省略。否则会调用toString方法。
@GET("user")
Call<User> getUser(@Header("Authorization") String authorization)
Headers需要添加到每一个请求中，通过OkHttp拦截器进行指定。
五、同步与异步
Call实例可以以同步或异步的方式执行，每一个实例只使用一次，但是调用clone()方法就会创建一个新实例，新实例也会使用。
在Android系统，主线程会执行回调；而在JVM中，在执行HTTP请求的同一个线程会发生回调。
Retrofit类通过你饿API接口来转变成可回调的对象。
六、转换器
默认情况下，Retrofit只能反序列化HTTP Body为OkHttp的ResponseBody类型，它使用@Body接受RequestBody。
可以添加转换器来支持其它类型。Retrofit提供了六个转换器：
- 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);