Retrofit 入门

Retrofit用法详解

参考:

Retrofit 官方API

Retrofit用法详解(入门看这篇就够了)

一、简介

官方介绍:A type-safe HTTP client for Android and Java

Retrofit是Square公司开发的一款针对Android网络请求的框架,Retrofit2底层基于OkHttp实现的,OkHttp现在已经得到Google官方认可,大量的app都采用OkHttp做网络请求。

二、用法

简单示例

1.创建业务请求接口,具体代码如下:

public interface BlueService {
@GET("book/search")
Call getSearchBooks(@Query("q") String name, 
        @Query("tag") String tag, @Query("start") int start, 
        @Query("count") int count);
}

这里需要稍作说明,@GET注解就表示get请求,@Query表示请求参数,将会以key=value的方式拼接在url后面

2.需要创建一个Retrofit的示例,并完成相应的配置

 Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://api.douban.com/v2/")
.addConverterFactory(GsonConverterFactory.create())
.build();
 BlueService service = retrofit.create(BlueService.class);

这里的baseUrl就是网络请求URL相对固定的地址,一般包括请求协议(如Http)、域名或IP地址、端口号等,当然还会有很多其他的配置,下文会详细介绍。还有addConverterFactory方法表示需要用什么转换器来解析返回值,GsonConverterFactory.create()表示调用Gson库来解析json返回值,具体的下文还会做详细介绍。

3.调用请求方法,并得到Call实例

Call call = mBlueService.getSearchBooks("小王子", "", 0, 3);

4.使用Call实例完成同步或异步请求

同步请求:
BookSearchResponse response = call.execute().body();
异步请求
call.enqueue(new Callback() {
@Override
public void onResponse(Call call,Response response) {
}
 @Override
 public void onFailure(Call call, Throwable t) {

}
}); 

使用:

首先需要在build.gradle文件中引入需要的第三包,配置如下:

compile 'com.squareup.retrofit2:retrofit:2.1.0'
compile 'com.squareup.retrofit2:converter-gson:2.1.0'
compile 'com.squareup.retrofit2:adapter-rxjava:2.1.0'

常用注解

前面我们说道,retrofit通过使用注解来简化请求,这里我们先来认识一下常用的注解。retrofit中的注解大体分为以下基类:用于标注请求方式的注解,用于标记请求头的注解以及用于标记请求参数的注解。其实,任何一种Http库都提供了相关的支持,无非在retrofit中是用注解来简化

1.请求方法注解,该类型的注解用于标注不同的http请求方式,主要有以下几种:
Retrofit 入门_第1张图片
2.请求头注解,该类型的注解用于为请求添加请求头。
3.请求和响应格式注解,该类型的注解用于标注请求和响应的格式。
Retrofit 入门_第2张图片
4.请求参数类注解,该类型的注解用来标注请求参数的格式,有些需要结合上面请求和响应格式的注解一起使用。
Retrofit 入门_第3张图片
5.请求参数详细说明

Get方法

  1. @Query

Get方法请求参数都会以key=value的方式拼接在url后面,Retrofit提供了两种方式设置请求参数。第一种就是像上文提到的直接在interface中添加@Query注解,还有一种方式是通过Interceptor实现,直接看如何通过Interceptor实现请求参数的添加。

public class CustomInterceptor implements Interceptor {
@Override
public Response intercept(Chain chain) throws IOException {
    Request request = chain.request();
    HttpUrl httpUrl = request.url().newBuilder()
            .addQueryParameter("token", "tokenValue")
            .build();
    request = request.newBuilder().url(httpUrl).build();
    return chain.proceed(request);
}
}

addQueryParameter就是添加请求参数的具体代码,这种方式比较适用于所有的请求都需要添加的参数,一般现在的网络请求都会添加token作为用户标识,那么这种方式就比较适合。
创建完成自定义的Interceptor后,还需要在Retrofit创建client处完成添加

ddInterceptor(new CustomInterceptor())

2.@QueryMap

如果Query参数比较多,那么可以通过@QueryMap方式将所有的参数集成在一个Map统一传递,还以上文中的get请求方法为例

public interface BlueService {
@GET("book/search")
Call getSearchBooks(@QueryMap Map options);
}

调用的时候将所有的参数集合在统一的map中即可

//https://api.douban.com/v2/book/search?q=%E5%B0%8F%E7%8E%8B%E5%AD%90&tag=&start=0&count=3
Map options = new HashMap<>();
map.put("q", "小王子");
map.put("tag", null);
map.put("start", "0");
map.put("count", "3");
Call call = mBlueService.getSearchBooks(options);

3.Query非必填

如果请求参数为非必填,也就是说即使不传该参数,服务端也可以正常解析,那么如何实现呢?其实也很简单,请求方法定义处还是需要完整的Query注解,某次请求如果不需要传该参数的话,只需填充null即可。
针对文章开头提到的get的请求,加入按以下方式调用

Call call = mBlueService.getSearchBooks("小王子", null, 0, 3);
//https://api.douban.com/v2/book/search?q=%E5%B0%8F%E7%8E%8B%E5%AD%90&start=0&count=3

4.@Path

如果请求的相对地址也是需要调用方传递,那么可以使用@Path注解,示例代码如下:

 @GET("book/{id}")
 Call getBook(@Path("id") String id);

业务方想要在地址后面拼接书籍id,那么通过Path注解可以在具体的调用场景中动态传递,具体的调用方式如下:

Call call = mBlueService.getBook("1003078");

Post请求

1.@field

Post请求需要把请求参数放置在请求体中,而非拼接在url后面,先来看一个简单的例子

@FormUrlEncoded
@POST("book/reviews")
Call addReviews(@Field("book") String bookId, @Field("title") String title,
@Field("content") String content, @Field("rating") String rating);

FormUrlEncoded不能用于Get请求

@Field注解将每一个请求参数都存放至请求体中,还可以添加encoded参数,该参数为boolean型,具体的用法为

@Field(value = "book", encoded = true) String book,encoded参数为true的话,key-value-pair将会被编码,即将中文和特殊字符进行编码转换

2.@FieldMap

上述Post请求有4个请求参数,假如说有更多的请求参数,那么通过一个一个的参数传递就显得很麻烦而且容易出错,这个时候就可以用FieldMap

@FormUrlEncoded
@POST("book/reviews")
Call addReviews(@FieldMap Map fields);

3.@Body

如果Post请求参数有多个,那么统一封装到类中应该会更好,这样维护起来会非常方便

@FormUrlEncoded
@POST("book/reviews")
Call addReviews(@Body Reviews reviews);
public class Reviews {
public String book;
public String title;
public String content;
public String rating;
}

4.除了Get和Post请求,Http请求还包括Put,Delete等等,用法和Post相似,所以就不再单独介绍了。

6.添加自定义的header

Retrofit提供了两个方式定义Http请求头参数:静态方法和动态方法,静态方法不能随不同的请求进行变化,头部信息在初始化的时候就固定了。而动态方法则必须为每个请求都要单独设置。

静态方法

public interface BlueService {
@Headers("Cache-Control: max-age=640000")
@GET("book/search")
Call getSearchBooks(@Query("q") String name, 
        @Query("tag") String tag, @Query("start") int start, 
        @Query("count") int count);
}

此外也可以通过Interceptor来定义静态请求头

public class RequestInterceptor implements Interceptor {
@Override
public Response intercept(Chain chain) throws IOException {
    Request original = chain.request();
    Request request = original.newBuilder()
        .header("User-Agent", "Your-App-Name")
        .header("Accept", "application/vnd.yourapi.v1.full+json")
        .method(original.method(), original.body())
        .build();
    return chain.proceed(request);
}
}

添加header参数Request提供了两个方法,一个是header(key, value),另一个是.addHeader(key, value),两者的区别是,header()如果有重名的将会覆盖,而addHeader()允许相同key值的header存在

然后在OkHttp创建Client实例时,添加RequestInterceptor即可

private static OkHttpClient getNewClient(){
 return new OkHttpClient.Builder()
.addInterceptor(new RequestInterceptor())
.connectTimeout(DEFAULT_TIMEOUT, TimeUnit.SECONDS)
.build();
}

动态方法

public interface BlueService {
@GET("book/search")
Call getSearchBooks(
@Header("Content-Range") String contentRange, 
@Query("q") String name, @Query("tag") String tag, 
@Query("start") int start, @Query("count") int count);
}

文件上传与下载

其他

为某个请求设置完整的URL,假如说你的某一个请求不是以base_url开头该怎么办呢?别着急,办法很简单,看下面这个例子你就懂了

public interface BlueService {  
@GET
public Call profilePicture(@Url String url);
 }

 Retrofit retrofit = Retrofit.Builder()  
.baseUrl("https://your.api.url/");
.build();

BlueService service = retrofit.create(BlueService.class);  
service.profilePicture("https://s3.amazon.com/profile-picture/path");

你可能感兴趣的:(Retrofit 入门)