Android：Retrofit中文说明

Android

版本：2
译者：陈小默

原文地址：http://square.github.io/retrofit/#api-declaration
GitHub仓库地址：https://github.com/square/retrofit

Retrofit

为Android和Java设计的一款类型安全的HTTP客户端

简介

Retrofit 通过一个Java接口实现HTTP请求对象

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

译者注：Repo是一个相应数据的JavaBean类

GitHubService 接口的实例由 Rerofit 类实现

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");

译者注：Call对象能够使用execute()方法和enqueue()方法发出请求，请参考OKHttp使用方式

采用注解的方式去描述一个HTTP请求:

• 支持URL占位操作
• 能够将JavaBean对象转换为请求体(request body)
• 支持表单上传

说明: 本站点仍会持续扩展2.0 APIs中的内容

API 说明

通过接口中方法上的注解和方法参数上的注解来表示如何处理一个请求

请求方法

任何一个方法都必须有一个能够提供请求方式和请求地址的注解。Retrofit提供了五个已经被构建好的注解：GET, POST, PUT, DELETE, and HEAD 。

@GET("users/list")

另外，你也可以在URL中指定查询参数

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

URL处理

URL可以使用占位符来自动替换补全参数。占位符使用一个被大括号包围的只能是字母和数字的字符串。匹配参数必须使用和占位符相同字符串的@path注解。

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

查询参数的也要添加注解

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

Map集合可以被用来表示复杂查询条件的组合

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

请求体

一个使用了@Body注解的JavaBean对象能够被转换为HTTP请求体对象

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

一个对象也能使用Retroft实例中指定的转换器转换，如果没有多余的转换器，就只能使用RequestBody对象了。

表单的编码和Multipart

方法可以被声明去发送URL编码的表单和Multipart数据

当方法上存在@FormUrlEncoded注解时表单数据会被编码。使用@Field修饰参数表示表单属性

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

当方法上存在@Multipart注解时表示使用Multipart表单，对应的属性参数需要使用@Part注解

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

处理请求头

静态方式：你可以在方法上使用@Headers注解设置请求头

@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注解。如果传入的value为null，则该请求头会被忽略。否则会调用value的toString方法并使用

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

如果你想要给所有请求设置请求头，那么你需要设置一个OKHttp拦截器

同步 vs 异步

Call的实例可以使用同步或者异步中任意一种方式运行。每一个实例一次只能选择一种方法运行，除非是使用clone()方法克隆的对像。

在Android中，回调必须运行在主线程当中。在Java虚拟机中，回调可以在与HTTP相同的线程中执行。

Retrofit 配置

Retrofit是一个能够将自定义请求接口转换为调用对象的工具类。默认情况下,Retrofit会为你的平台提供个一套完整的默认值，除此之外，Retrofit允许自定义配置。

转换器

默认情况下，Retrofit只能将HTTP响应体对象反序列化为OKHttp的ResponseBody类型的对象，并且Retrofit的@Body 注解仅能接受OKHttp的RequestBody类型参数。

当然，转换器可以添加其他类型的支持。这里提供本公司出品的六款受欢迎的序列化类库

• 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 生成需要使用 Gson 去反序列化的 GithubService 接口实例的例子

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.github.com")
    .addConverterFactory(GsonConverterFactory.create())
    .build();
GitHubService service = retrofit.create(GitHubService.class);

自定义转换器

如果你需要和使用了Retrofit所不支持的可直接使用的内容格式或者是你希望使用不同的类库去实现一个已存在的内容格式的API去通信，你可以很容易的创建你自己的转换器。你只需要创建一个类去继承 Converter.Factory 类，并且在创建你的适配器的时候将这个类转变成一个实例。

下载

Retrofit的源代码和示例

MAVEN仓库地址

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

译者推荐:http://mvnrepository.com/ 该网站提供了各种开源类库的版本查询，和提供了Maven或者Gradle的配置信息。

GRADLE

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

Retrofit 要求Java最低版本为7，Android最低版本为2.3

如果你使用了混淆工具，请在配置文件中添加如下语句

-dontwarn retrofit2.**
-keep class retrofit2.** { *; }
-keepattributes Signature
-keepattributes Exceptions

贡献代码

如果你想要贡献你的代码，你需要通过forking创建一个GitHub仓库的分支并且使用request方式提交你的代码。

当你提交代码的时候，为了保持代码的可阅读性，请您尽量遵循已存在的代码惯例和风格。另外也请您编译的代码通过mvn clean verify

在您的代码被项目接受之前，您必须要签署个体贡献者协议(CLA)

开源许可

Copyright 2013 Square, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

[http://www.apache.org/licenses/LICENSE-2.0]()

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.