这是 Retrofit 系列文章的第一篇。该系列通过通过几个用例来探讨 Retrofit 的功能和扩展。
这篇博文中,我们将通过 Retrofit 的基础知识来创建一个 API 或者 Http 请求的 Android 客户端。
然而,这篇文章并不包含太多关于 Retrofit 和如何开始使用她的信息,如果你想了解更多,请访问该项目的主页。
什么是 Retrofit
据 Retrofit 的官方页面描述,她是
一个类型安全的 Android 或 Java 的 REST 客户端
你可以使用注解来描述 Http 请求,URL 参数替换,查询参数支持。这些都是默认集成的。此外,她还提供了多种多样的请求体和文件上传。
如何声明(API)请求
请访问 Retrofit 的主页阅读她的 API 文档说明,了解如何发起请求。通过清晰的代码示例你会获取到所有的重要信息。
准备你的 Android 工程
现在让我们的手回到键盘开始干活。如果你已经创建好工程,请直接看下一段。不然你就在你喜爱的 IDE 里面新建一个项目。我们更倾向于 Gradle 的构建系统,如果你使用 Maven 也是可以的。
声明依赖:Gradle 或者 Maven
现在让我们为自己的工程添加 Retrofit 的依赖。选择你的构建系统在 pom.xml 或者 build.gradle 里面声明 Retrofit 的依赖。当构建系统开始编译你的代码时,他会自动下载并为工程添加依赖库。我们也倾向于把 Retrofit 和 OkHTTP 结合使用。
Retrofit 1.9
pom.xml
1 | <dependency> |
build.gradle
1 | dependencies { |
Retrofit 2
如果你正在使用 Retrofit 2 请使用下面的依赖。
pom.xml
1 | <dependency> |
build.gradle
1 | dependencies { |
Retrofit 2 现在已经默认使用 OkHttp 作为网络层。你不需要为你的工程添加 OkHttp 的依赖了,除非你需要一个特定的版本。
现在你的工程已经集成了 Retrofit,让我们创造一个持久的 Android API/HTTP 客户端。
可持续的 Android 客户端
在研究已存在的 Retrofit 的客户端时,Bart Kiers 的仓库出现了。事实上,它是一个使用 Retrofit 的 Oauth 验证实例。它为一个可持续的 Android 客户端提供了必要的基本原理。这是我们为什么使用它作为一个稳定的基础。在未来的博文中,我们会进一步扩展验证功能。
下面的类定义了我们 Android 客户端的基础:ServiceGenerator
Service Generator
ServiceGenerator 是我们 API/HTTP 客户端的核心.现在, 她仅仅定义了一个方法为给定的类或者接口创建一个基本的 REST adapter。这里是代码:
Retrofit 1.9
1 | public class ServiceGenerator { |
Retrofit 2
1 | public class ServiceGenerator { |
ServiceGenerator 类使用 Retrofit 的 RestAdapter-Builder 来创建一个新的 REST 客户端通过一个被给定基础 url 的 API。例如,GitHub 的 API 基础 url 是 https://developer.github.com/v3/ 。serviceClass 定义了 API 请求的类或者接口。下面展示了 Retrofit 的用法和如何定义一个实例客户端。
JSON Mapping
Retrofit 1.9 默认使用 Google 的 Gson。你所要做的就是定义你的响应对象类,响应会自动映射为 Java 对象。
当使用 Retrofit 2 时,你需要为 Retrofit 对象添加一个 converter。这就是我们为什么会集成 GSON 到在 Retrofit 构建过程中要调用 .addConverterFactory(GsonConverterFactory.create()) 的原因了。
使用 Retrofit
好, 现在让我们定义一个从 github 请求数据的客户端实例。首先,我们需要创建一个接口并定义一个所需的方法。
GitHub 客户端
下面的代码定义了 GitHubClient 和一个请求某仓库贡献者列表的方法。它说明了 Retrofit 参数替代功能的用法。(当调用方法时,指定路径中的 owner 和 repo 将会被替换为给定的变量)
Retrofit 1.9
1 | public interface GitHubClient { |
Retrofit 2
1 | public interface GitHubClient { |
这是 Contributor 类的定义.该类包含了响应数据映射所需的属性。
1 | static class Contributor { |
关于前面提到的 JSON 映射:GitHubClient 定义了一个名为 contributors 返回类型为 List<Contributor> 的方法。Retrofit 确保服务器响应可以正确的得到映射。(在响应与给定的类匹配时)
API 实例请求
下面的代码片段说明了 ServiceGenerator 实例化你客户端的用法。Github 客户端通过调用方法来获取仓库贡献者的列表。这段代码是一个 Retrofit GitHub 客户端示例的修改版。
你需要为 ServiceGenerator 手动定义一个基本的 url https://developer.github.com/v3/ 。
Retrofit 1.9
1 | public static void main(String... args) { |
Retrofit 2
1 | public static void main(String... args) { |
接下来是什么
下篇文章将阐述如何使用 Retrofit 实现一个基本验证。
很高兴您可以阅读 Retrofit 系列的第一篇文章:)
原文地址:https://futurestud.io/blog/retrofit-getting-started-and-android-client/