Retrofit介绍

2018-03-08  本文已影响0人  米米在家

本文是对Retrofit官网的翻译

1.介绍(Intorduction)

简单说来Retrofit实现的功能就是将HTTP API转化成了Java接口的形式。

官网是这样描述的:Retrofit truns your HTTP API into a Java interface

例子:

public interface GitHubService {

  @GET("users/{user}/repos")

  Call> listRepos(@Path("user") String user);

}

用Retrofit这个类可以生成对上述接口的实现类:

Retrofit retrofit = new Retrofit.Builder()

    .baseUrl("https://api.github.com/")

    .build();

GitHubService service = retrofit.create(GitHubService.class);

接口返回的每个call对象都可以实现和远程web服务器的同步或者一步的通信

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

用注解的形式来描述HTTP请求:

URL参数是可以替换的并且提供请求参数

对象可以转换成请求实体(例如JSON,protocol buffers)

多重请求和文件上传

2.API说明(API Declaration)

接口方法需要的注解和参数来声明了这个请求如何处理

2.1请求方法

每个方法必须有关于HTTP的注解来提供请求方式和相对的URL。这里有五种关于请求方式的注解:GET,POST,DELETE,和HEAD。请求资源的相对URL地址也需要在注解中指出。

@GET("users/list")

你也可以在URL中声明你的请求参数

@GET("users/list?sort=desc")

2.2URL操作

一个请求的URL可以通过方法中声明的替代模块或者请求参数来动态的更新。替代模块是一个被{}包裹的数字或者字符串。必须用@Path来注释对应的字符串来声明相应的参数。

@GET("group/{id}/users")

Call> groupList(@Path("id") int groupId);

同时请求参数也可以被添加

@GET("group/{id}/users")

Call> groupList(@Path("id") int groupId, @Query("sort") String sort);

假如请求参数包含一个Map集合,也同样可以被添加

@GET("group/{id}/users")

Call> groupList(@Path("id") int groupId, @QueryMap Map options);

2.3请求实体

通过使用@Body注解可以实现将一个对象指定为HTTP的请求实体

@POST("users/new")

Call createUser(@Body User user);

这个参数对象会被Retrofit实例中的converter进行转化。如果没有给Retrofit实例添加任何converter的话则只有RequestBody可以作为参数使用。

2.4form encoded和multipart

方法也可以被声明来发送form-encoded和multipart

可以通过@FormUrlEncoded注解方法来发送form-encoded的数据。每个键值对需要用@Filed来注解键名,随后的对象需要提供值。

@FormUrlEncoded

@POST("user/edit")

Call updateUser(@Field("first_name") String first, @Field("last_name") String last);

也可以通过@Multipart注解方法来发送Mutipart请求。每个部分需要使用@Part来注解。

@Multipart

@PUT("user/photo")

Call updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);

多部分请求的数据使用Retrofit的转换器或者自己实现的转换器来进行请求数据的序列化

2.5表头操作

你可以通过@Heather注解来给方法设置静态的表头

@Headers("Cache-Control: max-age=640000")

@GET("widget/list")

Call> widgetList();

@Headers({

    "Accept: application/vnd.github.v3.full+json",

    "User-Agent: Retrofit-Sample-App"

})

@GET("users/{username}")

Call getUser(@Path("username") String username);

记住头部的值并不会相互覆盖,在请求中所有拥有相同名字的头部都会被保留

可以通过@Header注解来实现头部的动态更新。相应的参数值必须提给表头。假如相应的值为null,则该头部会被忽略。否则的话, 值的 toString 方法将会被调用,并且使用调用结果。

@GET("user")

Call getUser(@Header("Authorization") String authorization)

你可以使用okHttp interceptor为每个请求添加需要的头部

2.6同步VS异步

Call实例既可以同步的执行也可以异步执行。一个实例只能被执行一次,但是,当调用clone()将会产生一个新的实例供你使用。

在Android中,回调方法运行在主线程,在JVM,回调方法将和执行HTTP请求处于同一线程

3.Retrofit配置

Retrofit类会通过你定义的API接口转化为可调用的对象。默认情况下,Retrofit会返还给你合理的默认值,但也允许你进行指定。

3.1转化器(Converters)

默认情况下,Retrofit只能将HTTP体反序列化为OKHttp的 ResonseBody 类型,而且只能接收 RequestBody类型作为 @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);

3.2自定义转化器

如果你需要与没有使用Retrofit提供的内容格式的API进行交互的话或者是你希望使用一个不同的库来实现现有的格式,你也可以轻松创建使用自己的转化器。你需要创建一个继承自Converter.Factory的类并且在构建适配器的时候加入到实例里面。

上一篇下一篇

猜你喜欢

热点阅读