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<List<Repo>> 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<List<Repo>> 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<List<User>> groupList(@Path("id") int groupId);

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

query参数也可以添加。

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

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

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

请求体（request body）

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

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

表单和分块请求

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

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

@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 来处理自己的串行化。

HEADER处理

通过@Headers注解来给方法增加header信息

@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不互相重写，相同name的header都被包含在请求里。

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

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

通过OkHttp interceptor.可以添加统一的头信息。

同步和异步

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 来自定义转换器。

 

原文地址 ：

http://square.github.io/retrofit/