项目：Amphibians 应用

1. 准备工作

此 Codelab 将介绍如何自行构建一个名为 Amphibians 的新应用，并且会逐步引导您在 Android Studio 中完成 Amphibians 应用项目，包括项目设置和测试。

前提条件

  • 此项目的适用对象为已经完成《使用 Kotlin 进行 Android 开发的基础知识》课程第 4 单元的用户。

您将构建的内容

  • 使用 Retrofit 和 Moshi 以及适当的错误处理方法在应用中实现联网功能。

所需条件

  • 一台安装了 Android Studio 的计算机。

2. 已完成的应用概览

欢迎参与“项目：Amphibians 应用”！

截至目前为止，您构建的所有应用都依赖于本地存储的数据。这一次，您将构建一个显示不同两栖动物物种信息的应用，并运用您掌握的网络、JSON 解析和视图模型知识，让该应用能够使用来自网络的数据。该应用将通过此项目的自定义 API 获取数据，并将其显示在列表视图中。

在最终应用中，用户看到的第一个屏幕显示了 recycler 视图中的每个物种名称。

7697a4e0c9bb5a76.png

点按某个列表项将转到详情屏幕，该屏幕也显示了物种的名称，同时还显示了详细的说明。

9797605a20dc68d1.png

虽然我们已为您构建了此应用的界面部分，但起始应用运行时却不会显示任何数据。您需要实现应用的联网功能部分，然后在布局中显示下载的数据。

3. 开始

下载项目代码

请注意，文件夹名称为 android-basics-kotlin-amphibians-app。在 Android Studio 中打开项目时，请选择此文件夹。

如需获取此 Codelab 的代码并在 Android Studio 中打开它，请执行以下操作。

获取代码

  1. 点击提供的网址。此时，项目的 GitHub 页面会在浏览器中打开。
  2. 在项目的 GitHub 页面上，点击 Code 按钮，这时会出现一个对话框。

5b0a76c50478a73f.png

  1. 在对话框中，点击 Download ZIP 按钮，将项目保存到计算机上。等待下载完成。
  2. 在计算机上找到该文件（很可能在 Downloads 文件夹中）。
  3. 双击 ZIP 文件进行解压缩。系统将创建一个包含项目文件的新文件夹。

在 Android Studio 中打开项目

  1. 启动 Android Studio。
  2. 在 Welcome to Android Studio 窗口中，点击 Open an existing Android Studio project。

36cc44fcf0f89a1d.png

注意：如果 Android Studio 已经打开，请依次选择 File > New > Import Project 菜单选项。

21f3eec988dcfbe9.png

  1. 在 Import Project 对话框中，前往解压缩的项目文件夹所在的位置（很可能在 Downloads 文件夹中）。
  2. 双击该项目文件夹。
  3. 等待 Android Studio 打开项目。
  4. 点击 Run 按钮 11c34fc5e516fb1c.png 以构建并运行应用。请确保该应用按预期构建。
  5. 在 Project 工具窗口中浏览项目文件，了解应用的设置方式。

实现 API 服务

与之前的项目一样，我们已为您实现了该应用的大部分内容。您只需运用您在第 4 单元中学到的知识实现联网功能部分即可。您尽可以熟悉一下起始代码。大部分概念您应该已在第 1 至第 3 单元的学习中熟悉了。下面我们会根据每个步骤的需要展示特定的代码部分。

该应用会显示来自网络的两栖动物数据的列表。这些两栖动物数据来自 API 返回的 JSON 对象。请查看 network 软件包中的 Amphibian.kt 文件。此类会建立单个两栖动物对象的模型，该对象的列表将从 API 返回。每种两栖动物都有三个属性：名称、类型和说明。

data class Amphibian(
    val name: String,
    val type: String,
    val description: String
)

此 API 的后端相当简单。访问两栖动物数据需要两项关键信息：基础网址和用于获取两栖动物列表的端点。

  1. 基础网址：https://developer.android.com/courses/pathways/android-basics-kotlin-unit-4-pathway-2/
  2. 获取两栖动物列表：android-basics-kotlin-unit-4-pathway-2-project-api.json

该项目已有 Retrofit 和 Moshi 依赖项。在 network 软件包中，您可以找到 AmphibianApiService.kt 文件。该文件包含几条 TODO 注释。请执行以下五项任务，以实现 Amphibians 应用：

  1. 创建一个变量，用于存储 API 的基础网址。
  2. 使用 Kotlin 适配器工厂构建 Moshi 对象，Retrofit 将用其解析 JSON。
  3. 使用 Moshi 转换器构建 aRetrofit 实例。
  4. 使用 suspend 函数为每个 API 方法实现 AmphibianApiService 接口（此应用只有一个方法，即用于获取两栖动物列表的方法）。
  5. 创建一个 AmphibianApi 对象，用于公开使用 AmphibianApiService 接口的延迟初始化 Retrofit 服务。

实现 ViewModel

实现 API 后，您要向 amphibians API 发出请求，并存储任何需要显示的值。您要在 ui 软件包中的 AmphibianViewModel.kt 类中执行此操作。

您会发现，类声明上方是一个名为 AmphibianApiStatus 的枚举。

enum class AmphibianApiStatus {LOADING, ERROR, DONE}

三个可能的值为 LOADING、ERROR 和 DONE，用于向用户显示请求的状态。

在 AmphibianViewModel.kt 类本身中，您需要实现一些 LiveData 变量，一个用于与 API 交互的函数，还有一个用于在详情屏幕上设置两栖动物的函数。

  1. 添加 _status，这是一个私有 MutableLiveData 变量，用于保存 AmphibianApiStatus 枚举和各状态的后备属性 status。
  2. 为类型为 List<Amphibian> 的两栖动物列表添加一个 amphibians 变量和私有后备属性 _amphibians。
  3. 为所选的两栖动物对象（类型为 LiveData<Amphibian>）添加一个类型为 MutableLiveData<Amphibian> 的 _amphibian 变量和后备属性 amphibian。此变量将用于存储详情屏幕上显示的所选两栖动物。
  4. 定义一个名为 getAmphibianList() 的函数。使用 ViewModelScope 启动一个协程，在协程内，通过调用 Retrofit 服务的 getAmphibians() 方法执行 GET 请求，以下载两栖动物数据。您需要使用 try 和 catch 妥善处理错误。在发出请求之前，请将 _status 的值设为 AmphibianApiStatus.LOADING。如果请求成功，_amphibians 应设为来自服务器的两栖动物列表，_status 应设为 AmphibianApiStatus.DONE。如果发生错误，_amphibians 应设为一个空列表，_status 应设为 AmphibianApiStatus.ERROR。
  5. 实现 onAmphibianClicked() 方法，将您定义的 _amphibian 属性设为传入该函数的 amphibian 参数。在选择两栖动物时已调用此方法，以使所选两栖动物显示在详情屏幕上。

从 ViewModel 更新界面

实现 ViewModel 后，您只需修改 fragment 类和布局文件即可使用数据绑定。

  1. AmphibianListFragment 中已引用了 ViewModel。在 onCreateView() 方法中，膨胀布局后只需从 ViewModel 调用 getAmphibianList() 方法即可。
  2. 在 fragment_amphibian_list.xml 中，数据绑定变量的 <data> 标记已添加到布局文件中。您只需实现 TODO，界面就会根据视图模型更新。请为 listData 和 apiStatus 设置适当的绑定。
  3. 在 fragment_amphibian_detail.xml 中实现 TODO，以便为两栖动物的名称和说明设置适当的文本属性。

4. 测试说明

运行测试

如需运行测试，您可以执行以下任一操作。

对于单个测试用例，打开测试用例类，并点击类声明左侧的绿色箭头。然后，从菜单中选择“Run”选项。这样会运行测试用例中的所有测试。

a32317d35c77142b.png

很多时候您可能只需要运行单个测试，例如，其他测试都通过了，只有一个测试失败。您可以像运行整个测试用例一样运行单个测试。点击绿色箭头并选择 Run 选项。

ac6244434cfafb60.png

如果您有多个测试用例，也可以运行整个测试套件。就像运行应用一样，您可以在 Run 菜单中找到此选项。

7a925c5e196725bb.png

请注意，Android Studio 默认运行您运行的最后一个目标（应用目标、测试目标等），因此如果菜单仍然显示 Run > Run ‘app'，您可以通过选择 Run > Run 运行测试目标。

ee1e227446c536fe.png

然后从弹出式菜单中选择测试目标。

d570c947769db65c.png

运行测试的结果显示在 Run 标签页中。在左侧的窗格中，您会看到失败测试的列表（如有）。如果测试失败，其函数名称旁边会显示红色感叹号。如果测试通过，则其函数名称旁边会显示绿色对勾标记。

6d68f2bf589501ae.png

如果测试失败，文本输出会提供相关信息，帮助您修复导致测试失败的问题。

92f3c8219c03651d.png

例如，在上述错误消息中，测试检查 TextView 是否有使用特定字符串资源。但是，测试失败了。“Expected”和“Got”后面的文本不一致，也就是说，测试预期的值与从正在运行的应用中获取的值不一致。在此示例中，TextView 中使用的字符串不是测试所预期的实际上的 squeeze_count。