一种类型安全的Java HTTP客户端库Retrofit

一种类型安全的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);