プロジェクト: Amphibians アプリ

1. 始める前に

この Codelab では、Amphibians という、自分でビルドする新しいアプリを紹介します。また、Android Studio 内でのプロジェクトのセットアップやテストなど、Amphibians アプリプロジェクトを完了するための手順についても説明します。

前提条件

このプロジェクトは、「Kotlin を用いた Android の基本」コースのユニット 4 を修了したユーザーを対象としています。

作成するアプリの概要

Retrofit と Moshi を使用するアプリのネットワーキングと適切なエラー処理を実装します。

必要なもの

Android Studio がインストールされているパソコン

2. 完成したアプリの概要

プロジェクト: Amphibians へようこそ。

これまでに作成したアプリはすべて、ローカルに保存されたデータに依存していました。今回は、さまざまな両生類に関する情報を表示するアプリを基に、ネットワーキング、JSON 解析、ビューモデルの知識を活用して、アプリがネットワークのデータを利用できるようにします。このアプリは、このプロジェクトのカスタム API からデータを取得し、リスト表示します。

最終的なアプリの最初の画面で、リサイクラービューにそれぞれの種の名前が表示されます。

リストアイテムをタップすると詳細画面に移動し、種の名前と詳細な説明が表示されます。

このアプリの UI 部分はすでに作成されていますが、スタータープロジェクトを実行してもデータは表示されません。アプリのネットワーク部分を実装してから、ダウンロードしたデータをレイアウトに表示する必要があります。

3.始める

プロジェクトコードをダウンロードする

フォルダ名は android-basics-kotlin-amphibians-app です。Android Studio でプロジェクトを開くときは、このフォルダを選択してください。

この Codelab のコードを取得して Android Studio で開く手順は次のとおりです。

コードを取得する

指定された URL をクリックします。プロジェクトの GitHub ページがブラウザで開きます。
プロジェクトの GitHub ページで、[Code] ボタンをクリックすると、ダイアログが表示されます。

ダイアログで、[Download ZIP] をクリックして、プロジェクトをパソコンに保存します。ダウンロードが完了するまで待ってください。
パソコンに保存したファイルを見つけます（[ダウンロード] フォルダなど）。
ZIP ファイルをダブルクリックして展開します。プロジェクトファイルが入った新しいフォルダが作成されます。

Android Studio でプロジェクトを開く

Android Studio を起動します。
[Welcome to Android Studio] ウィンドウで [Open an existing Android Studio project] をクリックします。

注: Android Studio がすでに開いている場合は、メニューから [File] > [New] > [Import Project] を選択します。

[Import Project] ダイアログで、展開したプロジェクトフォルダがある場所（[ダウンロード] フォルダなど）に移動します。
そのプロジェクトフォルダをダブルクリックします。
Android Studio でプロジェクトが開くまで待ちます。
実行ボタンをクリックし、アプリをビルドして実行します。正常にビルドされたことを確認します。
[Project] ツールウィンドウでプロジェクトファイルを見て、アプリがどのように設定されているかを確認します。

API サービスを実装する

これまでのプロジェクトと同様に、アプリの大部分はすでに実装されています。ユニット 4 で学んだことを使用してネットワーク部分を実装するだけで済みます。スターターコードは自由に試してみてください。コンセプトの大部分はユニット 1～3 ですでに把握しているはずです。以降のステップでは、各ステップを完了するために必要なコードの特定の部分を呼び出します。

このアプリは、ネットワーク上の両生類データのリストを表示します。両生類データは、API が返す JSON オブジェクトから取得されます。network パッケージの Amphibian.kt ファイルを見てください。このクラスは単一の両生類オブジェクトをモデル化し、そのリストが API から返されます。各両生類には、name、type、description という 3 つのプロパティがあります。

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

この API のバックエンドは非常にシンプルです。両生類データにアクセスするには、2 つの重要な情報が必要です。ベース URL と、両生類のリストを取得するためのエンドポイントです。

ベース URL: https://developer.android.com/courses/pathways/android-basics-kotlin-unit-4-pathway-2/
両生類リストの GET リクエスト: android-basics-kotlin-unit-4-pathway-2-project-api.json

このプロジェクトには Retrofit と Moshi の依存関係がすでに存在します。network パッケージには、AmphibianApiService.kt ファイルがあります。このファイルには TODO コメントが複数含まれています。次の 5 つのタスクを行って Amphibians アプリを実装します。

API のベース URL を格納するための変数を作成します。
JSON を解析するために Retrofit が使用する Kotlin アダプターファクトリで、Moshi オブジェクトを作成します。
Moshi コンバータを使用して Retrofit インスタンスを作成します。
API メソッドごとに suspend 関数を使用して AmphibianApiService インターフェースを実装します（このアプリでは、両生類のリストを取得するメソッドは 1 つだけです）。
AmphibianApi オブジェクトを作成して、AmphibianApiService インターフェースを使用する遅延初期化 Retrofit サービスを公開します。

ViewModel を実装する

API を実装したら、amphibians API に対してリクエストを行い、表示する必要がある値を保存します。これは、ui パッケージにある AmphibianViewModel.kt クラスで行います。

クラス宣言の上に、AmphibianApiStatus という列挙型があります。

enum class AmphibianApiStatus {LOADING, ERROR, DONE}

取り得る 3 つの値 LOADING、ERROR、DONE は、リクエストのステータスを示すために使用されます。

AmphibianViewModel.kt クラス自体では、いくつかの LiveData 変数、API とやり取りする関数、詳細画面での両生類の設定を処理する関数を実装する必要があります。

ステータスについて、AmphibianApiStatus 列挙型とバッキングプロパティ status を保持できる、_status というプライベート MutableLiveData 変数を追加します。
両生類のリスト（List<Amphibian> 型）について、amphibians 変数とプライベートバッキングプロパティ _amphibians を追加します。
選択した両生類オブジェクト（LiveData<Amphibian> 型）について、MutableLiveData<Amphibian> 型の _amphibian 変数とバッキングプロパティ amphibian を追加します。これは、詳細画面に表示される選択した両生類を格納するために使用されます。
getAmphibianList() という関数を定義します。ViewModelScope を使用してコルーチンを起動し、コルーチン内で、Retrofit サービスの getAmphibians() メソッドを呼び出すことで両生類データをダウンロードするための GET リクエストを行います。try と catch を使用してエラーを適切に処理する必要があります。リクエストを行う前に、_status の値を AmphibianApiStatus.LOADING に設定します。リクエストに成功したら、_amphibians をサーバーからの両生類のリストに設定し、_status を AmphibianApiStatus.DONE に設定する必要があります。エラーが発生した場合は、_amphibians を空のリストに設定し、_status を AmphibianApiStatus.ERROR に設定する必要があります。
onAmphibianClicked() メソッドを実装し、定義した _amphibian プロパティを、関数に渡す両生類の引数に設定します。両生類が選択されたときにこのメソッドはすでに呼び出されているため、詳細画面に表示されます。

ViewModel から UI を更新する

ViewModel を実装したら、あとはデータバインディングを使用するようにフラグメントクラスとレイアウトファイルを編集するだけです。

ViewModel はすでに AmphibianListFragment で参照されています。onCreateView() メソッドで、レイアウトがインフレートされた後、ViewModel から getAmphibianList() メソッドを呼び出します。
fragment_amphibian_list.xml では、データバインディング変数の <data> タグがすでにレイアウトファイルに追加されています。あとはビューモデルに基づいて UI を更新する TODO を実装するだけです。listData と apiStatus に適切なバインディングを設定します。
fragment_amphibian_detail.xml で、TODO を実装して、両生類の名前と説明の適切なテキストプロパティを設定します。

4. テスト手順

テストを実行する

テストを実行するには、次のいずれかを行います。

1 つのテストケースの場合、テストケースクラスを開き、クラス宣言の左側にある緑色の矢印をクリックします。メニューから [Run] オプションを選択します。これにより、テストケース内のすべてのテストが実行されます。

多くの場合、1 つのテストを実行するだけで済みます。たとえば、失敗したテストが 1 つしかなく、他のテストには合格している場合などです。テストケース全体を実行するときと同じように、1 つのテストを実行できます。緑色の矢印をクリックして [Run] オプションを選択します。

複数のテストケースがある場合は、テストスイート全体を実行することもできます。アプリを実行する場合と同様に、このオプションは [Run] メニューにあります。

Android Studio は、デフォルトでは最後に実行したターゲット（アプリやテストターゲットなど）を実行するので、メニューに [Run] > [Run 'app'] と表示されている場合は、[Run] > [Run] を選択してテストターゲットを実行できます。

ポップアップメニューからテストターゲットを選択します。

テストの実行結果が [Run] タブに表示されます。左側のペインに、失敗したテストのリストが表示されます（ある場合）。失敗したテストについては、関数名の横に赤い感嘆符が表示されます。合格したテストには緑色のチェックマークが表示されます。

テストが失敗すると、テキスト出力に、テスト失敗の原因となった問題の解決に役立つ情報が表示されます。

たとえば、上記のエラーメッセージは、TextView が特定の文字列リソースを使用しているかどうかをテストし、失敗したことを示しています。「Expected」と「Got」の後のテキストが一致していませんが、これは、テストで予想された値と実行中のアプリから得られた値が一致しないことを意味します。この例では、TextView で使用されている文字列が、テストで予想される squeeze_count と異なります。