初识Retrofit2 —— Retrofit配置及基本使用

本文旨在向初学者介绍Retrofit2这一网络框架。Retrofit与Retrofit2之间的Api改动较大,目前关于Retrofit的文章有大多是在介绍先前的版本的api。于是此篇文章变应运而生。通过本文你可以了解:

  • 使用Retrofit所需要的依赖
  • 最新依赖的Jar文件获取方法(search.maven.org)
  • 使用Retrofit进行Http请求
  • Retrofit 注释Api的简单介绍

Retrofit依赖配置

想要使用Retrofit,需要进行配置的依赖有:

GRADLE:

compile 'com.squareup.retrofit2:retrofit:2.0.2'
compile 'com.squareup.okhttp3:okhttp:3.2.0'
compile 'com.squareup.okio:okio:1.8.0'
compile 'com.google.code.gson:gson:2.6.2'
compile 'com.squareup.retrofit2:converter-gson:2.0.2'

Retrofit: 基本的依赖,想要用这个网络请求框架,就要添加这个依赖。
okhttp: Retrofit的底层网络访问是使用的okhttp,所以这个也是必须添加的。
okio: 这个是okhttp所用到的依赖库
gson: Retrofit序列化与反序列化所用到的库(可替换)
converter-gson: 与gson对应,用于初始化Retrofit 的(可替换)

小提示:
Retrofit,Volley 等等是封装好了具体请求,线程切换以及数据转换的网络框架。而okhttp是基于http请求的一套客户端,okhttp的职责是和HttpClient,HttpUrlConnection一样的。

如何获取到最新的依赖jar文件

我们通过这个网站:http://search.maven.org 进行搜索,在搜索结果中即可获取最新的jar文件,理论上所有的开源框架都可以在这里找到

使用Retrofit进行Http请求

“A type-safe REST client for Android and Java” 这是Retrofit官网对其的介绍。Retrofit主要的针对的即是REST API,你还不了解REST API是什么的话,先去了解了解吧。

这里我将使用有道翻译的翻译Api 来完成下面的案例。如果你想试一试下面演示的案例,就需要自己去申请一个有道翻译的key。

Retrofit将你的Http请求转换成一个java接口

public interface TranslateService {
    @GET("openapi.do?keyfrom=<keyfrom>&key=<key>&type=data&doctype=json&version=1.1")
    Call<Translate> listString(@Query("q") String words);
}

简单的分析一下这个接口:
@GET("...") : 这个注释所代表的含义即为Get请求,要是进行Post请求只需要把GET改为Post 即:@POSt("...")。有道翻译的api并不支持Post请求。
@Query("...") : 代表的是增加请求参数, 参数名为注释里的内容,参数值为传入的形参值。
一个简单的例子介绍一下:如果我们传入words的值为"retrofit" 那么在底层我们请求的Url就会变为:http://......&version=1.1&q=retrofit

Retrofit会自动生成一个TranslateService的实现类

Retrofit retrofit = new Retrofit.Builder()
        .baseUrl("http://fanyi.youdao.com")
        .addConverterFactory(GsonConverterFactory.create())
        .build();
TranslateService service = retrofit.create(TranslateService.class);

TranslateService 创建出的每一个Call都可以产生一个同步或者异步的Http 请求访问远程服务器

//同步方式请求
Response<Translate> response = translateCall.execute();
Translate translate = response.body();
System.out.println(translate.getTranslation().get(0));

//异步方式请求
translateCall.enqueue(new Callback<Translate>() {
    @Override
    public void onResponse(Call<Translate> call, Response<Translate> response) {
        Translate translate = response.body();
        System.out.println(translate.getTranslation().get(0));
    }

    @Override
    public void onFailure(Call<Translate> call, Throwable throwable) {

    }
});

Retrofit 注释Api的简单介绍

注释在接口的方法以及参数中的作用是指明该Http请求会如何被处理

1. 请求方法

每一个函数都必须指定HTTP 注释,它可以指定请求方法以及相关的URL。这里有五个内建的注释:GET, POST, PUT, DELETE 和 HEAD。相关的URL资源定义在注释里面。

@GET("users/list")

你也可以在URL中指定请求参数

@GET("users/list?srot=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请求的请求体

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

这个对象将会被Retrofit的实例指定的转换器所转换。如果Retrofit实例没有添加转换器,那么只有RequestBody可以被使用

4. 来自编码和更多

函数也可以声明发送以编码的表单和多部分的数据。当@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去处理他们自己的序列化方法

5. 处理标头

你可以为一个方法使用@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);

注意:请求头不会相互之间被覆盖,所有的拥有相同名字的请求头都会被包含到整个请求里面。

一个请求头可以使用注释 @Header动态的更新。相应的参数将会提供给@Header。如果这个值为空,那么这个请求头将会被忽略。否则toString方法将会被调用,而且其结果将会赋予这个值

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

如果每一个请求都需要添加多个请求头我们可以使用OkHttp 拦截器

6. 同步vs异步

Call实例可以被同步或者异步地执行。每一个实例只能使用一次,但是使用clone() 将会创建一个可被使用的新实例。
在Android上,回调方法将会在主线程上执行。在JVM上回调方法将会在和执行HTTP 请求的相同线程上执行。

还想学习更多吗?

推荐阅读
Retrofit 官网介绍
用 Retrofit 2 简化 HTTP 请求
Rest Api 介绍

推荐阅读更多精彩内容

  • Android 自定义View的各种姿势1 Activity的显示之ViewRootImpl详解 Activity...
    passiontim阅读 157,643评论 24 688
  • Spring Cloud为开发人员提供了快速构建分布式系统中一些常见模式的工具(例如配置管理,服务发现,断路器,智...
    卡卡罗2017阅读 121,062评论 16 134
  • 本文翻译自https://futurestud.io/tutorials/retrofit-getting-sta...
    sakasa阅读 15,067评论 3 54
  • 又是不算圆满的一天。大理的太阳依旧很大,我躺着床上,无聊地刷着屏。是的,我想去看书,去练瑜伽。去学习。但我什么都没...
    曾曾的麻麻阅读 70评论 0 0
  • 有人说过:未来属于那些会讲故事的人。 之前一直对这句话半信半疑,随着后来了解和接触的人和事越来越多,也越来越坚信这...
    一梦同学阅读 2,271评论 24 81