【Retrofit-v2.1.0】使用说明

最新推荐文章于 2021-08-27 11:27:36 发布

Large_bearR

最新推荐文章于 2021-08-27 11:27:36 发布

阅读量470

点赞数

分类专栏： android 文章标签： Retrofit 使用说明

android 专栏收录该内容

22 篇文章 0 订阅

订阅专栏

原文链接：http://square.github.io/retrofit/

简介

Rtrofit将你的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请求到远程web服务器.

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

使用注解来描述HTTP请求.

URL 参数替换和查询参数支持
请求主体的对象替换(比如JSON,协议缓冲区)
多部分的请求主体和文件上传

API声明

接口中方法和参数的注解表明了一个请求将会被怎么处理.

请求方法

每一个方法都必须要有一个提供请求方式和关联URL的注解，有5个内置的注解：GET，POST,PUT, DELETE, HEAD。资源的关联URL在注解中指定.

@GET("users/list")

你也可以在URL中指定请求所需要的参数.

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

URL操作

通过使用方法中的替换块和参数能够动态地更新一个URL请求.所谓的替换块是指被{}包围的字母数字串(译者注：如下面的id)，对应的参数必须用@Path注解而且字符串要相同.

@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId);

可以增加查询需要的参数(译者注：如下面增加了sort)

@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 注解.

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

通过在Retrofit实例中指定一个转换器可以将一个对象转换.如果没有添加转换器,只能使用RequestBody。

表单和其它部分

方法同样能够发送表单数据和其它部分数据.
在方法中使用 @FormUrlEncoded注解那么表单数据会一起发送，键值对使用@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来处理它们各自的序列化.

你可以通过使用注解@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不会相互覆盖.具有相同名字的Headers全部都会包括在请求里面.
一个请求头使用@Header注释可以动态更新。必须提供相应的参数给@Header。如果该值为null,头就会被忽略掉。否则,值会调用toString方法,toString的结果会被使用。

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

通过使用OkHttp interceptor可以为每一个请求指定要添加的Headers.

同步VS异步

无论是同步或者异步Call实例都可以被执行.一个实例只能够执行一次，但是调用clone()方法将会创建一个新的可以使用的实例.
在Android，回调函数会在主线程中执行.在JVM，回调函数和执行HTTP请求在同一个线程里面.

Rtrofit配置

Retrofit是通过API接口的类转化为可调用对象。默认情况下,Rtrofit会根据平台提供对应的默认,但它允许定制。

转换器

默认情况下,Rtrofit只能反序列化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);