Retrofit的使用 (1)

标签：

　　本文算不上原创，只是大概翻译了 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 ：GET, POST, PUT, DELETE, 和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 @FormUrlEncoded
2 @POST("/user/edit")
3 Call<User> updateUser(@Field("first_name") String first, @Field("last_name") String last);

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

1 @Multipart
2 @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 XML: com.squareup.retrofit:converter-simplexml

　　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 Signature
4 -keepattributes Exceptions

Retrofit的使用 (1)

标签：

原文地址：http://www.cnblogs.com/zhangyn/p/5090344.html