android retrofit入门,Retrofit入门

Retrofit

A type-safe HTTP client for Android and Java  。

下文基于 Retrofit 2.0.

介绍

Retrofit将你的Http请求函数转换成Java 接口

public interface GitHubService {

@GET("users/{user}/repos")

Call> listRepos(@Path("user") String user);

}

这是Retrofit请求gitHub用户信息的例子。

GitHubService 接口的Retrofit的具体实现如下 ：

Retrofit retrofit = new Retrofit.Builder()

.baseUrl("https://api.github.com/")

.build();

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

基于GitHubService创建的每一个Call，可以向远程服务端发起一个同步或异步的请求。

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

应用注解来描述Http 请求

支持URL参数和Query参数的替换

对象转换成request body (例如JSON 、 protocol buffers等)

Multipart 请求和文件上传

API声明

在接口方法或它参数上的注解说明了一个请求将被怎么处理

请求方法

每一个方法必须有一个HTTP注解，来说明请求的方式和相对的URL，Retrofit提供了5个内嵌的注解：GET, POST, PUT, DELETE, and HEAD。 资源的相对URL通过注解指定。

@GET("users/list")

也可以在地址中加入query参数

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

sort=desc就是 query参数。

URL处理

一个请求URL可以动态更新，通过替换块和方法中的参数。一个替换块是一个由字母数字组成的字符串，被{}包裹。对应的参数必须通过@Path注解，且字符串相同。

@GET("group/{id}/users")

Call> groupList(@Path("id") int groupId);

{id} 为可修改的请求参数，在方法参数的注解中 通样有一个id被@Path注解。

query参数也可以添加。

@GET("group/{id}/users")

Call> groupList(@Path("id") int groupId, @Query("sort") String sort);

复杂的query参数可以通过map来添加

@GET("group/{id}/users")

Call> groupList(@Path("id") int groupId, @QueryMap Map options);

请求体(request body)

通过@Body注解可以将一个对象作为HTTP请求的请求体(request body)使用

@POST("users/new")

Call createUser(@Body User user);

表单和分块请求

可以声明方法为发送表单或分块请求

表单请求通过@FormUrlEncoded注解，每一个键值对通过@Field注解，包含key，参数具体值是value。

@FormUrlEncoded

@POST("user/edit")

Call updateUser(@Field("first_name") String first, @Field("last_name") String last);

分块请求通过@Multipart注解，每个请求部分通过@Part注解

@Multipart

@PUT("user/photo")

Call updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);

分块请求使用Retrofit的转换器或实现自己的RequestBody 来处理自己的串行化。

HEADER处理

通过@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}")

Call getUser(@Path("username") String username);

注意header不互相重写，相同name的header都被包含在请求里。

通过@Header可以动态修改一个请求的头信息。这时相应的参数必须提供@Header注解，如果值是null，将被忽略，否则，将调用toString()方法获取具体的值。

@GET("user")

Call getUser(@Header("Authorization") String authorization)

同步和异步

Call实例可以同步或异步执行，每个实例只能执行一次。但是调用clone可以创建新的实例来使用。

在Android平台，回调将在主线程调用，在jvm平台，回调在执行http请求的线程执行。

转换器

默认情况下，Retrofit只能序列化它的http bodies到 OkHttp's ResponseBody，它只能接受它的RequestBody 通过@Body注解。

可以添加转化器来支持别的类型，下面留个比较流行的模块可以为你带来方便。

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 的例子。

Retrofit retrofit = new Retrofit.Builder()

.baseUrl("https://api.github.com")

.addConverterFactory(GsonConverterFactory.create())

.build();

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

自定义转换器

如果你需要和API通信通过一种Retrofit不支持的内容组织形式(比如YAML, txt, custom format)，你可以自定义转换器。可以容易的通过继承 Converter.Factory class 来自定义转换器。