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接口的调用都会生成一个对远端web服务器同步或异步的http请求。

Call<List<Repo>> repos = service.listRepos("octocat");

使用注解描述http请求：

• URL参数替换和查询参数支持
• 对象转换为请求体（eg:JSON,protocol buffers）
• 多组件的请求体和文件上传

注意：这个站点作为最新2.0的APIs的扩展，一直在更新中。

API声明

接口方法上的注解和它的参数声明一个请求如何发起。

请求方法

每个方法必须有一个提供请求方法和相关URL的http注解。现存在五种内置的注解：GET,POST,PUT,DELETE,and 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请求体。

@POST("users/new")
Call<User> createUser(@Body User user);

对象也可以使用Retrofit实例指定的转换器来转换。如果没有转换器被添加，则只有RequestBody被使用。

表单编码和多组件

方法可以被声明用来发送表单编码和多组件数据。

当@FormUrlEncoded被声明在方法上时，表单编码数据可以被发送。每一对kay、value用@Field注释，包括名称和对象提供的值。

@FormUrlEncoded
@POST("user/edit")
Call<User> updateUser(@Field("first_name") String first, @Field("last_name") String last);

当@Multipart被声明在方法上时，多组件请求可以被使用。部分使用@Part注释声明。

@Multipart
@PUT("user/photo")
Call<User> updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);

多组件部分使用Retrofit中的一个转换器，他们或者可以实现RequestBody来操作自身的序列号。

Header操作

你可以用@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);

注意：headers不会相互覆盖。具有相同名称的所有头文件都会被包括在请求中。

一个请求头可以用@Header注解动态更新。@Header必须提供相应的参数。如果值为空，请求头将会被省略。否则，值的toString方法将会被调用，并且结果会被使用。

@GET("user")
Call<User> getUser(@Header("Authorization") String authorization)

需要添加到每个请求的Header可以使用一个指定的OkHttp拦截器。

同步VS异步

调用实例可以同步或异步执行。每个实例只可以被调用一次，但调用clone()方法可以创建一个新的实例。

在Android上,回调函数将在主线程上执行。在JVM上,回调函数会发生在同一线程执行HTTP请求。

Retrofit配置

通过Retrofit类可以把你的API接口转换为可调用对象。默认情况下，Retrofit会给你的平台一个智能的默认项，同时允许自定义。

转换器

默认情况下，Retrofit可以只将http请求体变成OKHttp的ResponseBody类型，并且对于@Body，它只接收它的RequestBody类型。

转换器可以添加到其他类型的支持。6个兄弟模块可以作为流行的序列化库为你提供方便。

• 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不支持开箱即用的API通信或你想使用一个不同的库来实现现有的格式,您可以轻松地创建自己的转换器。创建一个继承了Converter.Factory的类并且通过适配器构建一个实例。

下载

最新版Jar

Retrofit的源码和例子可以在GitHub上找到。

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和Android2.3。

混淆器

如果你正在你的项目中使用混淆器，在你的配置文件中加上下面几行内容：

-dontwarn retrofit2.**
-keep class retrofit2.** { *; }
-keepattributes Signature
-keepattributes Exceptions

原文地址：http://square.github.io/retrofit/