retrofit 2.0使用详解

Retrofit使用方法

官网：http://square.github.io/retrofit/

首先需要添加访问网络的权限。

<uses-permission android:name="android.permission.INTERNET"/>

去官网添加最新依赖

compile'com.squareup.retrofit2:retrofit:2.0.1'

创建API接口

　　在retrofit中通过一个Java接口作为http请求的api接口。注：GET括号里面的是相对路径。Path括号里面的是对应Get括号的参数

public interface GitHubApi {    @GET("repos/{owner}/{repo}/contributors")    Call<ResponseBody> contributorsBySimpleGetCall(@Path("owner") String owner, @Path("repo") String repo);}

创建retrofit实例

　　在这里baseUrl是在创建retrofit实力的时候定义的，我们也可以在API接口中定义完整的url。在这里建议在创建baseUrl中以”/”结尾，在API中不以”/”开头和结尾。

构建根url

Retrofit retrofit = new Retrofit.Builder()        .baseUrl("https://api.github.com/")        .build();

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

之后就可以直接调用生成的GitHubServcie实例去发送同步或异步的请求给Web服务器

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

API 声明

接口函数的注解和参数表明如何去处理请求

请求方法

每一个函数都必须有提供请求方式和相对URL的Http注解，Retrofit提供了5种内置的注解：GET、POST、PUT、DELETE和HEAD，在注解中指定的资源的相对URL

@GET("users/list")
1
1

也可以在URL中指定查询参数

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

URL处理

请求的URL可以在函数中使用替换块和参数进行动态更新，替换块是{ and }包围的字母数字组成的字符串，相应的参数必须使用相同的字符串被@Path进行注释

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

也可以添加查询参数

@GET("group/{id}/users")List<User> groupList(@Path("id") int groupId, @Query("sort") String sort);
1
2
1
2

复杂的查询参数可以使用Map进行组合

@GET("group/{id}/users")List<User> groupList(@Path("id") int groupId, @QueryMap Map<String, String> options);

请求体

可以通过@Body注解指定一个对象作为Http请求的请求体

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

该对象将会被Retroofit实例指定的转换器转换，如果没有添加转换器，则只有RequestBody可用。（转换器的添加在后面介绍）

FORM ENCODED 和 MULTIPART

函数也可以声明为发送form-encoded和multipart数据。 
当函数有@FormUrlEncoded注解的时候，将会发送form-encoded数据，每个键-值对都要被含有名字的@Field注解和提供值的对象所标注

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

当函数有@Multipart注解的时候，将会发送multipart数据，Parts都使用@Part注解进行声明

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

Multipart parts要使用Retrofit的众多转换器之一或者实现RequestBody来处理自己的序列化。

Header处理

可以使用@Headers注解给函数设置静态的header

@Headers("Cache-Control: max-age=640000")@GET("widget/list")Call<List<Widget>> widgetList();
1
2
3
1
2
3

@Headers({    "Accept: application/vnd.github.v3.full+json",    "User-Agent: Retrofit-Sample-App"})@GET("users/{username}")Call<User> getUser(@Path("username") String username);
1
2
3
4
5
6
1
2
3
4
5
6

需要注意的是：header不能被互相覆盖。所有具有相同名字的header将会被包含到请求中。

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

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

Header处理

可以使用@Headers注解给函数设置静态的header

@Headers("Cache-Control: max-age=640000")@GET("widget/list")Call<List<Widget>> widgetList();
1
2
3
1
2
3

@Headers({    "Accept: application/vnd.github.v3.full+json",    "User-Agent: Retrofit-Sample-App"})@GET("users/{username}")Call<User> getUser(@Path("username") String username);
1
2
3
4
5
6
1
2
3
4
5
6

需要注意的是：header不能被互相覆盖。所有具有相同名字的header将会被包含到请求中。

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

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

Retrofit 配置

Retrofit是通过API接口转换成的可调用的对象，默认有一些合理的配置，这些配置也可以进行定制。

转换器

默认情况下，Retrofit只能够反序列化Http体为OkHttp的ResponseBody类型，并且只能够接受ResponseBody类型的参数作为@body。 
添加转换器可以支持其他的类型，为了方便的适应流行的序列化库，Retrofit提供了六个兄弟模块：

• Gson : com.squareup.retrofit:converter-gson
• Jackson: com.squareup.retrofit:converter-jackson
• Moshi: com.squareup.retrofit:converter-moshi
• Protobuf: com.squareup.retrofit:converter-protobuf
• Wire: com.squareup.retrofit:converter-wire
• Simple XML: com.squareup.retrofit:converter-simplexml

自定义转换器

如果需要使用Retrofit不支持开箱即用的内容格式(如YAML、txt、自定义格式)和API进行通信，或者想要使用不同的库实现已经存在的格式，你可以很方便的创建自己的转换器。创建方式：新建一个类继承Converter.Factory类，并在构建Retrofit实例时传入转换器实例。

 Retrofit retrofit = new Retrofit.Builder()        .baseUrl(BASE_URL)        .addCallAdapterFactory(RxJavaCallAdapterFactory.create()) // 使用RxJava作为回调适配器        .addConverterFactory(GsonConverterFactory.create()) // 使用Gson作为数据转换器        .build();
1
2
3
4
5
1
2
3
4
5

使用RxJava和Gson转换器需要添加依赖

// Retrofit适配RxJavacompile 'com.squareup.retrofit:adapter-rxjava:2.0.0-beta1'// Retrofit Gson数据转换器compile 'com.squareup.retrofit:converter-gson:2.0.0-beta1'

配合RxJava使用

在Rxjava下，你可以用Observable定义异步函数：

@GET("user/{id}/photo")Observable<Photo> getUserPhoto(@Path("id") int id);
1
2
1
2

现在你可以做很多事情，不光可以获取数据还可以改变数据。 
Retrofit 支持Observable导致了将多个REST调用组合在一起变得简单了。例如，我们有一个调用去获取照片，第二个调用去获取原生数据，我们可以将结果一起打包。

Observable.zip(    service.getUserPhoto(id),    service.getPhotoMetadata(id),    (photo, metadata) -> createPhotoWithData(photo, metadata))    .subscribe(photoWithData -> showPhoto(photoWithData));
1
2
3
4
5
1
2
3
4
5

通过RxJava + Retrofit可以让多个REST调用组合成一个变得更简单。