简介
Retrofit是由Square公司出品的针对Android和Java的类型安全的Http客户端，网络服务基于OkHttp 。
Retrofit2.0: 有史以来最大的改进
使用Retrofit2.0
下载 v2.0.0-beta2 JAR
Gradle :
compile com.squareup.retrofit:retrofit:2.0.0-beta2
Maven :
<dependency> <groupId>com.squareup.retrofitgroupId> <artifactId>retrofitartifactId> <version>2.0.0-beta2version> dependency>
用法介绍
转换HTTP API为Java接口
public interface GitHubService { @GET("/users/{user}/repos")
CalllistRepos(@Path("user") String user);
}
使用类Retrofit生成接口GitHubService的实现
Retrofit retrofit = new Retrofit.Builder() .baseUrl("https://api.github.com") .build() GitHubService service = retrofit.create(GitHubService.class)
以后就能够直接调用生成的GitHubServcie实例去发送同步或异步的要求给Web服务器
Callrepos = service.listRepos("octocat");
API 声明
接口函数的注解和参数表明如何去处理要求
要求方法
每个函数都必须有提供要求方式和相对URL的Http注解，Retrofit提供了5种内置的注解：GET、POST、PUT、DELETE和HEAD，在注解中指定的资源的相对URL
@GET("/users/list")
也能够在URL中指定查询参数
@GET("/users/list?sort=desc")
URL处理
要求的URL可以在函数中使用替换块和参数进行动态更新，替换块是{ and }包围的字母数字组成的字符串，相应的参数必须使用相同的字符串被@Path进行注释
@GET("/group/{id}/users") ListgroupList(@Path("id") int groupId);
也能够添加查询参数
@GET("/group/{id}/users")
ListgroupList(@Path("id") int groupId, @Query("sort") String sort);
复杂的查询参数可使用Map进行组合
@GET("/group/{id}/users") ListgroupList(@Path("id") int groupId, @QueryMap Map<String, String> options);
要求体
可以通过@Body注解指定1个对象作为Http要求的要求体
@POST("/users/new") Call<User> createUser(@Body User user);
该对象将会被Retroofit实例指定的转换器转换，如果没有添加转换器，则只有RequestBody可用。（转换器的添加在后面介绍）
函数也能够声明为发送form-encoded和multipart数据。
当函数有@FormUrlEncoded注解的时候，将会发送form-encoded数据，每一个键-值对都要被含着名字的@Field注解和提供值的对象所标注
@FormUrlEncoded @POST("/user/edit") CallupdateUser(@Field("first_name") String first, @Field("last_name") String last);
当函数有@Multipart注解的时候，将会发送multipart数据，Parts都使用@Part注解进行声明
@Multipart @PUT("/user/photo") CallupdateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);
Multipart parts要使用Retrofit的众多转换器之1或实现RequestBody来处理自己的序列化。
可使用@Headers注解给函数设置静态的header
@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}") CallgetUser(@Path("username") String username);
需要注意的是：header不能被相互覆盖。所有具有相同名字的header将会被包括到要求中。
可使用@Header注解动态的更新1个要求的header。必须给@Header提供相应的参数，如果参数的值为空header将会被疏忽，否则就调用参数值的toString()方法并使用返回结果
@GET("/user") CallgetUser(@Header("Authorization") String authorization)
使用OkHttp拦截器可以指定需要的header给每个Http要求
OkHttpClient client = new OkHttpClient() client.networkInterceptors().add(new Interceptor() {
@Override
public com.squareup.okhttp.Response intercept(Chain chain) throws IOException { com.squareup.okhttp.Response response = chain.proceed(chain.request()) // Do anything with response here
return response }
}) Retrofit retrofit = new Retrofit.Builder() .baseUrl(BASE_URL)
... .client(client) .build()
同步 VS 异步
每个Call实例可以同步(call.excute())或异步(call.enquene(CallBack callBack))的被履行，每个实例仅仅能够被使用1次，但是可以通过clone()函数创建1个新的可用的实例。
也能够使用CallBack定义1个异步方法：
@GET("/user/{id}/photo") void getUserPhoto(@Path("id") int id, Callbackcb);
在Android上，回调被履行在主线程；在JVM上，回调被履行在发送Http要求的线程。
Retrofit 配置
Retrofit是通过API接口转换成的可调用的对象，默许有1些公道的配置，这些配置也能够进行定制。
转换器
默许情况下，Retrofit只能够反序列化Http体为OkHttp的ResponseBody类型，并且只能够接受ResponseBody类型的参数作为@body。
添加转换器可以支持其他的类型，为了方便的适应流行的序列化库，Retrofit提供了6个兄弟模块：
-
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进行通讯，或想要使用不同的库实现已存在的格式，你可以很方便的创建自己的转换器。创建方式：新建1个类继承Converter.Factory类，并在构建Retrofit实例时传入转换器实例。
Retrofit retrofit = new Retrofit.Builder() .baseUrl(BASE_URL) .addCallAdapterFactory(RxJavaCallAdapterFactory.create()) // 使用RxJava作为回调适配器 .addConverterFactory(GsonConverterFactory.create()) // 使用Gson作为数据转换器 .build()
使用RxJava和Gson转换器需要添加依赖
compile com.squareup.retrofit:adapter-rxjava:2.0.0-beta1 compile com.squareup.retrofit:converter-gson:2.0.0-beta1
配合RxJava使用
在Rxjava下，你可以用Observable定义异步函数：
@GET("/user/{id}/photo") ObservablegetUserPhoto(@Path("id") int id);
现在你可以做很多事情，不光可以获得数据还可以改变数据。
Retrofit 支持Observable致使了将多个REST调用组合在1起变得简单了。例如，我们有1个调用去获得照片，第2个调用去获得原生数据，我们可以将结果1起打包。
Observable.zip(
service.getUserPhoto(id),
service.getPhotoMetadata(id),
(photo, metadata) -> createPhotoWithData(photo, metadata)) .subscribe(photoWithData -> showPhoto(photoWithData))
通过RxJava + Retrofit可让多个REST调用组合成1个变得更简单。
RxJava系列教程：
-
深入浅出RxJava（1：基础篇）
-
深入浅出RxJava(2：操作符)
-
深入浅出RxJava3