はじめからはじめる @ngrx/data 第2話（NgRx 激闘編）

今日も、@ngrx/data の続きです。

前回は @ngrx/data が何なのかをくどくど説明して、プロジェクトをセットアップして、ライブラリをブチ込んだところで時間切れでした。

今日はいよいよ本格的に @ngrx/data に挑戦します。

例題

次のエンティティに対する CRUD 処理を @ngrx/data で実装してみよう。ちなみに主キーは id だよ。

エンティティ名: Hero

項目名	型
id	`number`
name	`string`

まずはこのエンティティを表現するクラスが必要だね。 DTO みたいなやつが。

エンティティクラスを作ろう

それじゃ、Hero エンティティのための Hero クラスを作ろう。

ちなみにエンティティ名は、今回の例に限らず基本的に名詞の単数形にしておくと吉だよ。

$ ng g class Hero --skipTests

コマンドの最後の --skipTests って何？

余計な spec.ts が作られなくなるおまじない。

単なるデータの容いれ物は、単体テストを書く意味があまりないからね。

src/app/hero.ts

export class Hero {
  id: number;
  name: string;
}

エンティティメタデータの編集

次に、@ngrx/data に Hero エンティティの存在を教えてあげなきゃいけない。

src/app/entity-metadata.ts を開いて、以下のように編集しましょう。

  import { EntityMetadataMap, EntityDataModuleConfig } from '@ngrx/data';

  const entityMetadata: EntityMetadataMap = {
+   Hero: { } // ❶
  };

  const pluralNames = {
+   Hero: 'Heroes'  // ❷
  };

  export const entityConfig: EntityDataModuleConfig = {
    entityMetadata,
    pluralNames
  };

❶ を書くことで、先ほど作った Hero クラスが @ngrx/data に登録されるよ。

とりあえず、 { } の中は何も書かなくていい。

どういうときに { } の中身が必要なの？

レコードを絞ったり（WHEREみたいなやつ）、ソートしたり（ORDER BYみたいなやつ）。

あと、主キーの項目名が id 以外の場合は、ここで主キーを指定する必要があるよ。

❷ はエンティティ名 Hero の複数形を指定しているんだね。

補足: エンティティの主キーの話

デフォルトでは、暗黙的に id という名の項目がエンティティの主キーと見なされるんだよ。

だから、今回の例では ❶ には特になにも指定していない。

id 以外の項目も主キーにできるんだよね？

うん。でも複合主キーは基本的に許されない。

たとえば、多対多の関係性を取り持つ連関エンティティの場合も、ちゃんと単独で機能する主キーが別途必要になるんだ。

ここはエンティティ設計に影響を与えそうなポイントだから、ちょっと注意が必要だね。

補足: エンティティ名の単数形と複数形

❷ の plural は、複数形という意味だよ。

@ngrx/data は、API 設計的に単数形と複数形を区別しているんだ。

どういうこと？

ちょっと先回りすると、Hero エンティティの一覧を取得しようとしたとき、@ngrx/data は自動で /api/heroes/ という URL に HTTP Get リクエストを投げる。

URL が複数形になってるね。

一方、id = 1 みたいに、主キーを指定して単一のレコードを削除しようとしたときは、 /api/hero/1 という URL に HTTP Delete を投げる。

こっちは URL が単数形だね。

まぁそんな感じで、@ngrx/data は対象が単数形か複数形かに応じて Web API の URL を打ち分けるんだよ。

なるほど、わかりやすい。

しかも、この複数形の URL は、エンティティ名に基づいて @ngrx/data が自動生成してくれる。

だからさっき「エンティティ名は名詞の単数形で」って言ってたのか。

でもタネを明かすと、 @ngrx/data がやっていることは、機械的にエンティティ名のうしろに〝s〟をつけてるだけなんだ。

たとえば Book というエンティティ名の複数形は Books みたいにね。

単純にエンティティ名のうしろに〝s〟をつけるだけではダメな場合は、@ngrx/data に教えてやる必要があるんだね。

Hero と Heroes とか、Octopus と Octopi とか。

そうそう。そういうのを ❷ に指定するんだ。

サービス経由でエンティティを操る

ここまでで、だいたい前準備はおしまい。

コードよりも周辺の会話の方が多かったね。

いよいよコンポーネントから、@ngrx/data のエンティティサービス経由で Hero エンティティを操作する方法を見ていこう。

まず、サービスを使えるようにしないとね。

いろいろな書き方があるけれど、一番簡単なのはコレかな。

❶

コンストラクタに EntityServices のインスタンスを DI して、

❷

EntityServices#getEntityCollectionService(エンティティ名) で当該エンティティのサービスを取得する。

src/app/app.component.ts

import { Component } from '@angular/core';
import { EntityCollectionService, EntityServices } from '@ngrx/data';
import { Hero } from './hero';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {
  private heroService: EntityCollectionService<Hero>;

  constructor(entityServices: EntityServices) { // ❶
    this.heroService = entityServices.getEntityCollectionService<Hero>('Hero'); // ❷
  }
}

たとえばもし、 Villain というエンティティのためのサービスを取得したければ、上記の Hero をすべて Villain に換えればいいんだね。

そういうこと。

❷ で取得したサービスは heroService に代入している。

この heroService を通して CRUD 操作を行えばいいの？

うん。

代表的なメソッドを以下にまとめたよ。

METHOD	MEANING	HTTP METHOD WITH ENDPOINT
add(entity: T)	新しいエンティティを追加します	`POST` /api/hero/
delete(id: any)	主キーの値でエンティティを削除します	`DELETE` /api/hero/5
getAll()	このエンティティタイプのすべてのインスタンスを取得します	`GET` /api/heroes/
getById(id: any)	主キーでエンティティを取得します	`GET` /api/hero/5
getWithQuery(queryParams: QueryParams \| string)	クエリを満たすエンティティを取得します	`GET` /api/heroes/?name=bombasto
update(update: Update)	既存のエンティティを更新します	`PUT` /api/hero/5