你的位置:首页 > 操作系统

[操作系统]Retrofit的使用


  本文算不上原创,只是大概翻译了 Retrofit 的英文文档,权当做是自己的笔记而已。

英文原地址:http://square.github.io/retrofit/

1.介绍

  Retrofit 把你的 HTTP API 转换为一个Java 接口。

1 public interface GitHubService {2  @GET("/users/{user}/repos")3  Call<List<Repo>> listRepos(@Path("user") String user);4 }

 

  Retrofit生成了 GithubService 接口的一个实现类。

1 Retrofit retrofit = new Retrofit.Builder()2   .baseUrl("https://api.github.com")3   .build();4 5 GitHubService service = retrofit.create(GitHubService.class);

  

  从生成的 GitHubService 发出的每一个 Call 都可以向远程的 Web服务器发出一个同步或者异步的HTTP请求。

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

 

  使用 annotations 描述 HTTP 请求:

  • 支持 URL 参数替换和请求参数
  • 支持对象转为请求体 (e.g.,JSON, protocol buffers)
  • 支持多个 request body 和 文件上传

2.API 的声明

  接口方法上的 Annotations 和它的参数标明了这个请求是如何被处理的。

  

  a.请求方法

  每个方法必须有一个提供了 request method 和 releative URL 的 HTTP annotation。Retrofit 内置了五种 annotations :GETPOSTPUTDELETE, 和HEAD。在 annotation 中资源的 relative URL 是被指定的。

 1 @GET("/users/list") 

你也可以在 URL 中指定请求参数。

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

 

  b.URL处理

  一个请求 URL 可以被其中的 replacement block 和方法上的参数动态的替换。replacement block 是一个被“{ }”包裹的含有字母或数字的字符串。相对应的参数必须是一个带有 @Path 的相同的字符串。即:

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

 

  查询的参数也可以被添加进来。

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

 

  对于复杂的查询参数可以组合成一个 Map 来使用。

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

 

  c.请求体

  一个带有 @Body 注解的对象可以被当做 HTTP 的请求体。

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

这个对象可以被 Retrofit 指定的转换器转换。如果没有指定,只有在 RequestBody 才能被使用。

  

  d.Form Encoded and Multipart

  Methods 也可以被声明发送 form-encoded 和 MutiPart 数据。

  使用 form-encoded 时要在 Method 上面添加 @FormUrlEncoded 注解。每一个键值对使用 @Field 注解包裹 key。即:

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

  使用多个请求时,要在 Method 上添加 @Multipart 注解,每部分使用 @Part 添加声明。即:

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

  多个请求部分使用 Retrofit 的转换器或者自己实现 RequestBody 处理自己的序列化。

  

  e.请求头的操纵

  你可以使用 @Headers 为一个请求方法设置静态的请求头。

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

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

  需要注意的是,所有的 Headers 之间不会重写,所有相同名字的 Headers 都会包含在请求里面。

  一个请求的 Headers 可以使用 @Headers 注解动态的更新。必须要为 @Headers 设置一个字母或者数字的参数。如果真实的值是 null ,这个请求头会被忽略,否则会调用 toString() 方法,并且在请求中使用。

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

  Headers that need to be added to every request can be specified using an OkHttp interceptor.

 

  f.同步 VS. 异步

  Call 实例可以再同步或者异步中执行。每个实例只能使用一次,但是如否使用 clone() 方法就能再创建一个可以使用的实例了。

  在 Android 中,回调会在主线程中执行。在 JVM 中回调会在发起 HTTP request 的同一线程中执行。

 

3.Retrofit 参数配置

  Retrofit 是一个通过你的 API 接口转换为 可回调对象的类。Retrofit 为你提供了默认的配置,但是也允许你自定义配置。

 

  a.转换器

  默认情况下,Retrofit 只能讲 HTTP bodies 发序列化为 OkHttp 的 ResponeBody 类型,对于 @Body 来说也只能在接收 ResponeBody 类型。

  转换器也可以支持下面类型:

  • 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 com.squareup.retrofit:converter-simple

  b.自定义转换器

  你也可以通过继承 Converter.Factory class 自定义转换器,然后在创建 adapter 是传入这个类得实例。

 

4.集成方式

  最新的 jar 包,请点击这里。

  Retrofit 源码与示例程序 On Github。

  Maven

<dependency> <groupId>com.squareup.retrofit</groupId> <artifactId>retrofit</artifactId> <version>(insert latest version)</version></dependency>

  Gradle

compile 'com.squareup.retrofit:retrofit:(insert latest version)'

  Retrofit 需要的环境:Java 7 以上及 Android 2.3以上。

  ProGuard

1 -dontwarn retrofit.**2 -keep class retrofit.** { *; }3 -keepattributes Signature4 -keepattributes Exceptions