1. Getting Started and Create an Android Client

Posted 2020-08-17 wchhuangya

1. Getting Started and Create an android Client

Retrofit

tutorial

 

• • 什么是 Retrofit
  • 如何申明请求
  • 准备 Android 项目
  • 使用 Gradle 或 Maven 定义依赖
    • Retrofit 1.9 的依赖定义
      • pom.xml
      • build.gradle
    • Retrofit 2.0 的依赖定义
      • pom.xml
      • build.gradle
  • 持续发展的 Android 客户端
    • 服务生成器
      • Retrofit 1.9
      • Retrofit 2
  • JSON 映射
  • 使用 Retrofit
    • GitHub 客户端
      • Retrofit 1.9
      • Retrofit 2
  • Request 示例
    • Retrofit 1.9
    • Retrofit 2

 

该篇讲述了 Retrofit 的基础知识，并讲述了如何创建 Android 客户端的 API 或 HTTP 请求。

但是，本篇不会覆盖太多起步知识。如果想知道这些信息，请参见 主页 的内容。

什么是 Retrofit

---

Retrofit 的官网是这样描述的：

A type-safe REST client for Android and Java

因此，在 Retrofit 中，默认使用注解来描述 HTTP 请求、URL 参数占位符等操作。此外，它还支持多个请求体，也提供了文件上传的能力。

如何申明请求

---

请访问 Retrofit 的主页 ，阅读 API 申明部分，以便获取如何创建请求的感觉。在那里，既有重要的说明，又有示例代码。

准备 Android 项目

---

如果你已经创建了 Android 项目，那请跳过本段。如果没有，就使用你最喜欢的 IDE 来创建一个 Android 项目。推荐使用 Gradle 作为构建系统，当然，也可以使用 Maven。

使用 Gradle 或 Maven 定义依赖

---

依赖于构建工具的不同，依赖定义的地方也不同，在 pom.xml 或 build.gradle 中定义依赖。

Retrofit 1.9 的依赖定义

pom.xml

---

1. <dependency>  

   ---

2. <groupId>com.squareup.retrofit</groupId> 

   ---

3. <artifactId>retrofit</artifactId> 

   ---

4. <version>1.9.0</version> 

   ---

5. </dependency>  

   ---

6. <dependency>  

   ---

7. <groupId>com.squareup.okhttp</groupId> 

   ---

8. <artifactId>okhttp</artifactId> 

   ---

9. <version>2.7.2</version> 

   ---

10. </dependency>  

    ---

build.gradle

---

1. dependencies { 

   ---

2. // Retrofit & OkHttp 

   ---

3. compile ‘com.squareup.retrofit:retrofit:1.9.0‘ 

   ---

4. compile ‘com.squareup.okhttp:okhttp:2.7.2‘ 

   ---

5. } 

   ---

Retrofit 2.0 的依赖定义

pom.xml

---

1. <dependency>  

   ---

2. <groupId>com.squareup.retrofit2</groupId> 

   ---

3. <artifactId>retrofit</artifactId> 

   ---

4. <version>2.1.0</version> 

   ---

5. </dependency>  

   ---

6. <dependency>  

   ---

7. <groupId>com.squareup.retrofit2</groupId> 

   ---

8. <artifactId>converter-gson</artifactId> 

   ---

9. <version>2.1.0</version> 

   ---

10. </dependency>  

    ---

build.gradle

---

1. dependencies { 

   ---

2. // Retrofit & OkHttp 

   ---

3. compile ‘com.squareup.retrofit2:retrofit:2.1.0‘ 

   ---

4. compile ‘com.squareup.retrofit2:converter-gson:2.1.0‘ 

   ---

5. } 

   ---

Retrofit 2 默认使用 OKHttp 作为网络层，并且基于它进行构建。因此，在项目中不需要显示的定义这个依赖，除非你需要一个不同的版本。

到现在为止，你的 Android 项目已经为 Retrofit 做好准备了，让我们创建一个持久的 Android API/Http 的客户端吧。

持续发展的 Android 客户端

---

在对已经存在的 Android 客户端的调研中，由 Bart Kiers 创建的 example repository示例 崭露头角。其实，它是一个使用 Retrofit 进行 OAuth 认证的示例。但是，对于一个可持续发展的客户端来说，它提供了所有必要的元素。这就是为什么我们将把它当作一个稳定版来使用，并在后面的教程中给它扩展高级的认证功能。

下面的类：ServiceGenerator 定义了 Android 客户端的基础。

服务生成器

---

ServiceGenerator 是 API/HTTP 客户端的核心。在当前的状态中，它仅仅定义了一个方法，用于使用给定的类创建 REST 类型的适配器，下面是代码：

Retrofit 1.9

---

1. public class ServiceGenerator { 

   ---

2.  

   ---

3. public static final String API_BASE_URL = "http://your.api-base.url"; 

   ---

4.  

   ---

5. private static RestAdapter.Builder builder = new RestAdapter.Builder() 

   ---

6. .setEndpoint(API_BASE_URL) 

   ---

7. .setClient(new OkClient(new OkHttpClient())); 

   ---

8.  

   ---

9. public static <S> S createService(Class<S> serviceClass) { 

   ---

10. RestAdapter adapter = builder.build(); 

    ---

11. return adapter.create(serviceClass); 

    ---

12. } 

    ---

13. } 

    ---

Retrofit 2

---

1. public class ServiceGenerator { 

   ---

2.  

   ---

3. public static final String API_BASE_URL = "http://your.api-base.url"; 

   ---

4.  

   ---

5. private static OkHttpClient.Builder httpClient = new OkHttpClient.Builder(); 

   ---

6.  

   ---

7. private static Retrofit.Builder builder = 

   ---

8. new Retrofit.Builder() 

   ---

9. .baseUrl(API_BASE_URL) 

   ---

10. .addConverterFactory(GsonConverterFactory.create()); 

    ---

11.  

    ---

12. public static <S> S createService(Class<S> serviceClass) { 

    ---

13. Retrofit retrofit = builder.client(httpClient.build()).build(); 

    ---

14. return retrofit.create(serviceClass); 

    ---

15. } 

    ---

16. } 

    ---

ServiceGenerator 基于一个基本的地址，使用 Retrofit 的 RestAdapter - Builder，创建了一个新的 REST 客户端。例如，GitHub 的基本地址是：https://api.github.com/。该类中定义了用于 API 请求的、有注解的类和接口。下面的章节显示了 Retrofit 具体的用法，并演示如何定义一个典范式的客户端。

JSON 映射

---

Retrofit 1.9 默认集成了 Google GSON。你要做的就是定义你所需的用于响应的对象类，响应将会被自动映射。

Retrofit 2 中，需要自己显式地为 Retrofit 对象添加转换器。上面的示例，在 build.gradle 文件中添加了下面的代码来引入 Retrofit 2 使用的 GSON 转换器：

1. compile ‘com.squareup.retrofit2:converter-gson:2.1.0‘ 

   ---

现在，需要给 Retrofit 对象添加转换器，给 Retrofit Builder 对象使用 addConverterFactory(GsonConverterFactory.create()) 方法来为对象集成 GSON 用为它的默认转换器。

使用 Retrofit

---

好了，现在让我们定义一个 REST 客户端从 GitHub 上请求数据。首先，得创建接口、定义方法。

GitHub 客户端

---

下面的代码定义了一个 GitHubClient，和一个用于获取某个仓库贡献者列表的方法。代码来演示了 Retrofit 参数占位符功能（定义在路径中的 {owner} 和 repo）的用法，它们的作用是：在方法被调用时，占位符将被替换为传入的变量。

Retrofit 1.9

---

1. public interface GitHubClient {  

   ---

2. @GET("/repos/{owner}/{repo}/contributors") 

   ---

3. List<Contributor> contributors( 

   ---

4. @Path("owner") String owner, 

   ---

5. @Path("repo") String repo 

   ---

6. ); 

   ---

7. } 

   ---

Retrofit 2

---

1. public interface GitHubClient {  

   ---

2. @GET("/repos/{owner}/{repo}/contributors") 

   ---

3. Call<List<Contributor>> contributors( 

   ---

4. @Path("owner") String owner, 

   ---

5. @Path("repo") String repo 

   ---

6. ); 

   ---

7. } 

   ---

下面是 Contributor 类的定义，类中必须的属性与响应数据映射相对应：

1. static class Contributor {  

   ---

2. String login; 

   ---

3. int contributions; 

   ---

4. } 

   ---

关于先前提到的 JSON 映射：GitHubClient 类定义了名为 contributors 的方法，它的返回类型是 List。Retrofit 确保了服务响应能被正确的匹配（也就是响应匹配为相应的类）。

Request 示例

---

下面的代码片断演示了使用 ServiceGenerator 类实例化客户端，具体就是 GitHubClient，使用创建的客户端可以获取贡献者。这里的片断显示的是一个改进版。

在运行 GitHub 示例中，需要手动给 ServiceGenerator 设置基本网址，示例中是 https://api.github.com：

Retrofit 1.9

1. public static void main(String... args) {  

   ---

2. // Create a very simple REST adapter which points the GitHub API endpoint. 

   ---

3. GitHubClient client = ServiceGenerator.createService(GitHubClient.class); 

   ---

4.  

   ---

5. // Fetch and print a list of the contributors to this library. 

   ---

6. List<Contributor> contributors = 

   ---

7. client.contributors("fs_opensource", "android-boilerplate"); 

   ---

8.  

   ---

9. for (Contributor contributor : contributors) { 

   ---

10. System.out.println( 

    ---

11. contributor.login + " (" + contributor.contributions + ")"); 

    ---

12. } 

    ---

13. } 

    ---

Retrofit 2

---

1. public static void main(String... args) {  

   ---

2. // Create a very simple REST adapter which points the GitHub API endpoint. 

   ---

3. GitHubClient client = ServiceGenerator.createService(GitHubClient.class); 

   ---

4.  

   ---

5. // Fetch and print a list of the contributors to this library. 

   ---

6. Call<List<Contributor>> call = 

   ---

7. client.contributors("fs_opensource", "android-boilerplate"); 

   ---

8.  

   ---

9. try { 

   ---

10. List<Contributor> contributors = call.execute().body(); 

    ---

11. } catch (IOException e) { 

    ---

12. // handle errors 

    ---

13. } 

    ---

14.  

    ---

15. for (Contributor contributor : contributors) { 

    ---

16. System.out.println( 

    ---

17. contributor.login + " (" + contributor.contributions + ")"); 

    ---

18. } 

    ---

19. } 

    ---