はじめに

こんにちは、モチベーションクラウドの開発にフリーのエンジニアとして参画している@HayatoKamonoです。

この記事は、「モチベーションクラウド Advent Calendar 2018」2日目の記事となります。

先に成果物のイメージ

$ yo mcs

     _-----_
    |       |    ╭──────────────────────────╮
    |--(o)--|    │    Welcome to MCS App    │
   `---------´   │        Generator!        │
    ( _´U`_ )    ╰──────────────────────────╯
    /___A___\   /
     |  ~  |
   __'.___.'__
 ´   `  |° ´ Y `

? What do you want to generate? (Use arrow keys)
❯ Vue Component
  Vuex Store Module
? What's the component name? SampleComponent
   create SampleComponent/SampleComponent.index.js
   create SampleComponent/SampleComponent.vue
   create SampleComponent/SampleComponent.stories.js
   create SampleComponent/SampleComponent.specs.js

↑ この記事では、このようなものを作っていきます。

概要

モチベーションクラウドの開発チームでは2018年10月から改善期間と称して、開発に関するガイドラインやルール作りをはじめとする、様々な改善活動に取り組んでいます。

私が所属するフロントエンド開発チームでも、改善活動の一環として複数のガイドラインを作成しているのですが、その作成したガイドラインの１つに、コンポーネントを配置するディレクトリ構成・ファイル構成に関するガイドラインがあります。

.
├── atoms
├── molecules
├── organisms
│   └── SampleComponent
│       ├── index.js
│       ├── SampleComponent.specs.js
│       ├── SampleComponent.stories.js
│       └── SampleComponent.vue
├── templates
├── pages
└── decorators

簡単に説明をすると、componentsディレクトリ配下のディレクトリを、Atomic Designのatoms、molecules、organisms、templates、pagesで切り、そして、開発するコンポーネント毎にそのコンポーネント名でディレクトリを切るというディレクトリ構成で行くという方針で固まりました。

また、コンポーネント単位のディレクトリ配下には、「index.js」、単一ファイルコンポーネントの「ComponentName.vue」、Storybook用の「ComponentName.stories.js」、テスト用の「ComponentName.specs.js」を作成するというファイル構成で行くことに決まりました。

しかしながら、コンポーネント単位のディレクトリ以下に、毎回、４つのファイルを手動で決まった命名規則に合わせて作成するのは何気に面倒ですし、また、コード内に登場するコンポーネント名や、importするファイル名などを毎回、手動で書いたりするのも面倒です。

そこで今回はこれらのファイル一式を雛形ファイルをもとに自動生成するジェネレーターを作ってみたいと思います。

Yeoman事始め

今回、ジェネレーターを作成するに当たっては、Yeomanを利用します。

What's Yeoman?
Yeoman helps you to kickstart new projects, prescribing best practices and tools to help you stay productive.
To do so, we provide a generator ecosystem. A generator is basically a plugin that can be run with the yo command to scaffold complete projects or useful parts.

$ npm install -g yo

まずは、Yeomanをインストール。

$ mkdir generator-mcs

早速、ジェネレーター用のフォルダをYeomanの命名規則に従って作成します。
ジェネレーター用のフォルダ名は「generator-name」のように、「generator」をフォルダ名のprefixとし、ハイフンで次に続くジェネレーター名を区切る必要があります。

$ cd generator-mcs
$ npm init -y
$ npm install --save yeoman-generator　yosay

次に、package.jsonを作成し、今回の記事で作成するジェネレーターで使う依存モジュールを先にインストールしておきます。

※ 今回は、npm init -yでpackage.jsonの細かな設定はスキップしましたが、作成したジェネレーターをYeomanのGeneratorsページにインデックスさせたい場合は、package.jsonのkeywordに["yeoman-generator"]を指定、また、descriptionに任意の説明文を入れる必要があります。

$ mkdir -p generators/app generators/component
$ touch generators/app/index.js generators/component/index.js

今度は作業ディレクトリにgeneratorsフォルダーを作成し、その中にappフォルダーとcomponentフォルダーを作成します。

.
├── generators
│   ├── app
│   │   └── index.js
│   └── component
│       └── index.js
└── package.json

Yeomanにはapp generatorというメインのジェレネーターと、sub generatorというサブのジェネレーターの２種類のジェネレーターが作成可能です。

両者の使い分けは、app generatorは主にアプリケーション全体の雛形を作る為に利用し、sub generatorはより限定的な用途に利用するといったイメージです。

デフォルトの設定では、appディレクトリ以下のindex.jsがapp generatorに対応します。

そして、その他の任意の名前をつけるディレクトリ以下のindex.jsがそれぞれsub generatorに対応し、今回の例でいうと、componentディレクトリ下のindex.jsがsub generatorに該当します。

$ yo mcs

例えば、この記事で作成しているジェネレーターの名前はgenertor-mcsなので、appディレクトリ以下のapp generatorは上記のコマンドで後ほど実行出来ることになります。

$ yo mcs:component

また、先ほどgeneratorディレクトリ以下に作成したcomponentディレクトリの名前は、そのまま、サブジェネレーターの名前となるので、上記のコマンドでこちらのサブジェネレーターを後ほど実行出来るようになります。

const Generator = require('yeoman-generator');
const yosay = require('yosay');

module.exports = class extends Generator {
  constructor(args, opts) {
    super(args, opts);
    this.log(yosay('Welcome to MCS App Generator!'));
  }
};

とりあえず、app generatorに対応するapp/index.jsを上記のように編集して、Hello World的なものを作り動作確認をしてみます。

$ npm link

動作確認をする為にも、上記のコマンドを実行して、現在作成しているジェネレーターをグローバールインストールしておきます。

$ yo mcs

     _-----_
    |       |    ╭──────────────────────────╮
    |--(o)--|    │    Welcome to MCS App    │
   `---------´   │        Generator!        │
    ( _´U`_ )    ╰──────────────────────────╯
    /___A___\   /
     |  ~  |
   __'.___.'__
 ´   `  |° ´ Y `

yo generator-nameを実行すると、無事にapp generatorの実行が確認出来るはずです。

This Generator is empty. Add at least one method for it to run.というエラーが出るかもしれませんが、後で他にメソッドを追加すれば解消されるエラーなので、今は特に気にせず、次に進みます。

ちなみに、最初にインストールしたyosayライブラリは、上記の実行結果を見て分かる通り、Yeomanのイメージキャラクターのアスキーアートを出力する為のライブラリです。(見た目大事、楽しさ大事！)

今回は特にアプリケーション全体の雛形ファイルを作ることはしないので、一旦、app generatorはここまでとします。

雛形ファイルをもとにファイルを自動生成する

.
├── atoms
├── molecules
├── organisms
│   └── SampleComponent
│       ├── index.js
│       ├── SampleComponent.specs.js
│       ├── SampleComponent.stories.js
│       └── SampleComponent.vue
├── templates
├── pages
└── decorators

ここからは、この記事の概要で説明した通り、上記のようにcomponent単位のディレクトリ以下にindex.js、componentName.vue, componentName.stories.js、componentName.specs.jsの４ファイルを雛形ファイルをもとに生成するsub generatorを作って行きます。

.
├── generators
│   ├── app
│   │   └── index.js
│   └── component
│       └── index.js
└── package.json

それでは、既に作成しておいたcomponentディレクトリ以下のindex.jsを編集して、yo mcs:componentで実行出来るジェネレーターを作成して行きます。

$ mkdir generators/component/templates

先に、componentディレクトリ以下にtemplatesという名前で雛形ファイルを配置する為のディレクトリを作成しておきます。

Yeomanのデフォルトの設定では、templatesと名前の付いたディレクトリのパスが、後述するthis.templatePath()で取得可能なパスになります。

$ cd generators/component/templates/
$ touch _index.js _ComponentName.vue _ComponentName.specs.js _ComponentName.stories.js
$ tree .
.
├── _ComponentName.specs.js
├── _ComponentName.stories.js
├── _ComponentName.vue
└── _index.js

続けて、templatesディレクトリ以下に雛形となる４つのファイルを任意の名前で作成します。

現時点では単に空ファイルを作成しているだけですが、後ほど、これらの雛形ファイルにそれらしいベースとなるコードを追記したいと思います。

※　ファイル名は任意の名前で大丈夫です。_をファイル名の先頭に付けることは必須ではありません。

const Generator = require('yeoman-generator');

module.exports = class extends Generator {
  constructor(args, opts) {
    super(args, opts);
  }

  writing () {
    this.fs.copyTpl(
      this.templatePath('_index.js'),
      this.destinationPath('ComponentName/ComponentName.index.js')
    );

    this.fs.copyTpl(
      this.templatePath('_ComponentName.vue'),
      this.destinationPath('ComponentName/ComponentName.vue')
    );

    this.fs.copyTpl(
      this.templatePath('_ComponentName.stories.js'),
      this.destinationPath('ComponentName/ComponentName.stories.js')
    );

    this.fs.copyTpl(
      this.templatePath('_ComponentName.specs.js'),
      this.destinationPath('ComponentName/ComponentName.specs.js')
    );
  }
};

早速、component/index.jsを上記のように編集し、雛形ファイルをもとに新規ファイルを生成してみます。

ファイルの書き込み処理は、Generatorクラスに定義されているwritingメソッドの中に記述するようにします。

現段階では、コンポーネント名を直書きしていますが、後ほど、ユーザーからコンポーネント名の入力を受け付けるようにして、動的にコンポーネント名をファイル名に適用して行きます。

this.fs.copyTpl(
  this.templatePath('_index.js'),
  this.destinationPath('ComponentName/ComponentName.index.js')
);

ここでやっていることは、templatesディレクトリ以下の雛形ファイルをコピー元として指定し、yoコマンドが実際に実行されるカレントディレクトリ以下のComponentName/ComponentName.index.jsにファイルをコピーするという処理です。

$ mkdir ~/demo-project
$ cd ~/demo-project
$ yo mcs:component

ジェネレーター開発用の作業ディレクトリで、yoコマンドでジェネレーターを実行してしまうと、作業ディレクト内にファイルが生成されてしまうので、ここからは、yoコマンドを実行する時には、別に作成したプロジェクトディレクトリ内で実行して行きます。

.
└── ComponentName
    ├── ComponentName.index.js
    ├── ComponentName.specs.js
    ├── ComponentName.stories.js
    └── ComponentName.vue

yoコマンドを実行すると、コマンドを実行したカレントディレクトリ上に、ComponentNameというディクレトリが作られ、その中に４つのファイルが生成されていることが確認出来ました。

今度は動的にコンポーネント名を生成されるファイルに反映出来るようにして行きます。

const Generator = require('yeoman-generator');

module.exports = class extends Generator {
  constructor(args, opts) {
    super(args, opts);
  }

  async prompting() {
    // ユーザーの入力に関する情報をインスタンス変数に入れておく
    this.answers = await this.prompt([
      {
        type: 'input',
        name: 'componentName',
        message: `What's the component name?`,
        validate (input) {
          if (input.length > 0) {
            return true;
          } else {
            // 文字列を返すと検証エラー時にそのメッセージが出力表示される
            return "You need to provide the component name.";
          }
        }
      }
    ]);
  }

  writing () {
    // ユーザーが入力したコンポーネント名をインスタンス変数を参照して渡す
    this.fs.copyTpl(
      this.templatePath('_index.js'),
      this.destinationPath(`${this.answers.componentName}/${this.answers.componentName}.index.js`)
    );

    this.fs.copyTpl(
      this.templatePath('_ComponentName.vue'),
      this.destinationPath(`${this.answers.componentName}/${this.answers.componentName}.vue`)
    );

    this.fs.copyTpl(
      this.templatePath('_ComponentName.stories.js'),
      this.destinationPath(`${this.answers.componentName}/${this.answers.componentName}.stories.js`)
    );

    this.fs.copyTpl(
      this.templatePath('_ComponentName.specs.js'),
      this.destinationPath(`${this.answers.componentName}/${this.answers.componentName}.specs.js`)
    );
  }

};

ユーザーからの入力を受け付ける処理は、Generatorクラスに定義されているprompting()の中に記述するようにします。

promptingメソッドの中で実行しているpromptメソッドは非同期実行され、promiseを返します。

そのため、async, awaitをpromptingメソッドのところでは使っています。

$ yo mcs:component
? What's the component name? SampleComponent
   create SampleComponent/SampleComponent.index.js
   create SampleComponent/SampleComponent.vue
   create SampleComponent/SampleComponent.stories.js
   create SampleComponent/SampleComponent.specs.js

yoコマンドを実行すると、コンポーネント名を入力するプロンプトが表示され、入力したコンポーネント名が反映されたディレクトリとファイルが生成されることが確認出来ました。

<template>

</template>

<script>
  export default {
    name: "<%= componentName %>"
  }
</script>

<style lang="scss" scoped>

</style>

ここまでは、空の雛形ファイルをもとに動作確認を進めていたので、templates/_ComponentName.vueに簡易的なコードを加えて保存しておきます。

既に雛形ファイルをコピーする際に使用してきたfs.copyTplメソッドはejs template syntaxを使用しているので、雛形ファイルの方では、<%= componentName %>のようなejsの記法を使用することが可能です。

this.fs.copyTpl(
  this.templatePath('_ComponentName.vue'),
  this.destinationPath(`${this.answers.componentName}/${this.answers.componentName}.vue`),
  { componentName: this.answers.componentName }
);

_ComponentName.vue内の<%= componentName %>の部分に、ユーザーから入力されたコンポーネント名を反映出来るようにしてみます。

その為には、上記のコードのように、fs.copyTplメソッドの第３引数に対象の雛形ファイルに渡したい変数をkey, valueペアのオブジェクトで渡してあげます。

$ yo mcs:component
? What's the component name? SampleComponent
identical SampleComponent/SampleComponent.index.js
 conflict SampleComponent/SampleComponent.vue
? Overwrite SampleComponent/SampleComponent.vue? (ynaxdH)
  y) overwrite
  n) do not overwrite
  a) overwrite this and all others
  x) abort
  d) show the differences between the old and the new
  h) Help, list all options

これで、再度、yoコマンドを実行し、コンポーネント名を入力してあげれば、入力したコンポーネント名が生成される.vueファイルの該当箇所に反映されます。

尚、ファイル生成時に既に同じファイルが存在していて、既存のファイルと新規に生成されるファイルの内容が異なる場合は、上記のようにconflictが発生します。

その際は、Hを押せば選択可能なオプションが表示されるので、その中から任意のオプションを選択すると良いです。

ちなみに、yを押せば上書き保存してくれます。

app generatorからsub generatorに処理を委譲する

最後に、ジェネレーターから別のジェネレーターに処理を委譲する方法を紹介して、今回の記事を終わりにしたいと思います。

ここでは例として、app generatorからsub generatorに処理を委譲してみたいと思います。

const Generator = require('yeoman-generator');
const yosay = require('yosay');

module.exports = class extends Generator {
  constructor(args, opts) {
    super(args, opts);
    this.log(yosay('Welcome to MCS App Generator!'));
  }

  // ユーザーにサブジェネレーターを選択してもらう
  async prompting() {
    const answers = await this.prompt([
      {
        type: 'list',
        name: 'generatorName',
        message: 'What do you want to generate?',
        choices: [
          {
            name: 'Vue Component',
            value: 'component'
          },
          {
            name: 'Vuex Store Module',
            value: 'module'
          }
        ]
      }
    ]);

    // ユーザーが選択したサブジェネレーターに処理を委譲する
    this.composeWith(
      require.resolve(`../${answers.generatorName}`)
    );
  }
};

app generatorに対応するapp/index.jsを上記のように編集します。

これで、yo mcsとコマンド実行した時に、先ほど作成したcomponentサブジェネレーターを実行するのか、moduleサブジェネレーターを実行するのかを、ユーザーに選択してもらえるようになり、選択されたサブジェネレーターに処理が委譲され実行されることになります。

※ 尚、２つ目の選択肢に対応するサブジェネレーターは未作成の為、選択するとファイルが見つからずエラーになります。上記の例はmoduleサブジェネレーターが仮に既に作成済みであったという想定の例になります。

$ yo mcs

     _-----_
    |       |    ╭──────────────────────────╮
    |--(o)--|    │    Welcome to MCS App    │
   `---------´   │        Generator!        │
    ( _´U`_ )    ╰──────────────────────────╯
    /___A___\   /
     |  ~  |
   __'.___.'__
 ´   `  |° ´ Y `

? What do you want to generate? (Use arrow keys)
❯ Vue Component
  Vuex Store Module
? What's the component name? SampleComponent
   create SampleComponent/SampleComponent.index.js
   create SampleComponent/SampleComponent.vue
   create SampleComponent/SampleComponent.stories.js
   create SampleComponent/SampleComponent.specs.js

今後やりたいこと

1. yosayライブラリで出力されるYeomanのイメージキャラクターの代わりに、モチベーションクラウドの広告に起用されている役所広司さんのアスキーアートをウェルカムメッセージに表示出来るようにしたい
2. 実際のプロジェクトで使われているコードを雛形ファイルにし、今回作成したジェネレーターを実用的なものにしたい
3. 単一ファイルコンポーネントの<script>部分をASTにparseしてprops情報を抽出し、そのprops情報をもとにStorybook addonのknobsに対応したStorybookファイルを自動生成出来るようにしたい

参考

• WRITING YOUR OWN YEOMAN GENERATOR
• SBoudrias/Inquirer.js
• Sboudrias/mem-fs-editor
• EJS#docs

関連記事

こちらの記事はモチベーションクラウド Advent Calendar 2018に投稿した記事です。

他にも、以下の記事をモチベーションクラウド Advent Calendar 2018に投稿しています。
- Vueを用いた開発プロジェクト用にカスタムジェネレーターを作ってみる
- Vueを用いた開発プロジェクト用に「コンポーネント設計・実装ガイドライン」を作った話
- Vuexを用いた開発プロジェクト用にガイドラインを作成した話

こんにちは。フリーランスエンジニアの@dayoshixです。

現在、リンクアンドモチベーションのモチベーションクラウドの開発に、主にフロントエンドエンジニアとしてお手伝いさせて頂いております。
そのようなご縁もありモチベーションクラウドのアドベントカレンダー（３日目）に参加させて頂くことになりましたので宜しくお願いします！！

トップバッターの@ishigeさん、２日目の@HayatoKamonoさんお疲れ様でした！！
お二人の記事はこちら。どちらも力作なので宜しくお願いします。

• 1年半取り組んだWebプロジェクトマネジメントを振り返って、やって良かったこと、やっておけば良かったことをすべて書く
• Vueを用いた開発プロジェクト用にカスタムジェネレーターを作ってみる

ということで始めたいと思います。

概要

最近モチベーションクラウドのWebAPI設計ガイドラインが作成されたのですが、それはどのような方針で作成されたのか、その結果どのようなガイドラインが出来上がったのかを紹介します。

背景

これまでの状況

これまで、開発チームではWebAPIの設計に関する明文化されたルールがありませんでした。
WebAPI設計に関して専任の担当者がいるわけではなく、最近では状況にもよりますがフロントエンドエンジニアが設計を行う場面も増えてきました。

また、新たな開発メンバーも徐々に増えていき、迷いが生ずる場面が多くなり小さなストレスになっていました。
その結果かどうかわかりませんが、APIとしての一貫性が徐々に失われているように感じていた人も少なくなかったと思います。

改善しよう！！

開発チームとして技術的負債返済のための改善活動の一環としてWebAPI設計ガイドラインを作ろうという話になりました。

結果、私がガイドライン作成の音頭取りとベース作成を担当させて頂くことになり、開発メンバー全員にレビューして貰いブラッシュアップするようなフローで進めることになりました。

大切にしたこと

ガイドラインを作成するに当たって下記の点を大切にしました。

身の丈に合わせる

ネット上に公開されているガイドラインをそのまま模倣するのではなく、それらを参考にしつつも自分達が開発を通じて実際に迷ったことをもとに、今の自分達に必要な身の丈にあった最小限のルールだけを定義しようと考えました。

また、システムの文脈に依存する一般化できないようなルールがこぼれ落ちないことに注意しました。

基本を意識する

基本の理解を疎かにした状態で応用から入らないよう、基本を崩す場合の具体的な判断例を示すことを意識しました。
例えば、最初から特段の根拠もなく基本を崩しパフォーマンス最適化した設計にしないことを促したいと考えました。

べき論よりやり易さを優先する

セオリーや思想的にこうあるべき、という事が自分達にとってやりにくければ執着せずに無視することを意識しました。

システム概要

システムの特徴によってルールとして考慮する点が異なってくる事から、ガイドラインを紹介する前にモチベーションクラウドのシステム概要をざっくりと説明します。

• SaaS型のBtoBサービス
• バックエンドにRuby on Rails、フロントエンドにVue.jsを使用したいわゆるシングルページアプリケーション
• 2018年11月時点でクライアントのプラットフォームはWebのみ
• WebAPIはシステム内で閉じた使われ方をしており、ユーザーに公開するAPIはない

WebAPI設計ガイドライン

それでは実際に作られたWebAPI設計ガイドラインを紹介します。
ガイドライン中に時折なぜこのような選択をしたのかをコメントしています。

概要

本文書はMCSバックエンド〜フロントエンド間のWebAPI設計のガイドラインです。

MCSはモチベーションクラウドの社内での総称になります。

設計指針

RESTful like

基本的にはRESTに従い設計して下さい。
但し、RESTを原則的に従うことでアプリケーションが複雑になる、パフォーマンスに問題が生ずるなどの理由がある場合はRESTの原則に逸れても問題ありません。

RESTful likeな設計を目指して下さい。

RESTの原則に外れる設計パターンについてはこちらを参照して下さい。

画面に最適化されたWebAPIを作るよりもREST APIを作ることを優先する

画面が必要とする情報を取得するための汎用性の無いWebAPIを設計することよりも、その画面に必要なリソースを取得するためのWebAPIを設計することを優先して下さい。

その画面に必要なリソースの種別が多く、API呼び出しのラウンドトリップ過多でパフォーマンスに影響が出た場合に初めて画面向けのAPIを設計することを検討して下さい。

なぜ？

画面向けのWebAPIは画面の表示要素が変更されるたびにバックエンド側にも改修が発生します。 　

RESTベースでWebAPIを作っている場合、変更対象の表示要素の情報を取得するためのエンドポイントが既に作られている可能性がありますし、新規に作った場合でも将来的に他の用途で再利用できる可能性があります。

画面の文言をバックエンドで管理しない

特別な理由が無い限り、画面に表示する文言リソースをバックエンドで管理しWebAPI経由でフロントエンドに提供するような設計にせず、フロントエンドで持つようにして下さい。

🙅 Bad

GET /menu_items

{
  "meta": null,
  "data": [{
    "id": 1000,
    "title": "属性検索",
    "description": "登録済みの属性の一覧を検索することができます。"
  },{
  "meta": null,
  "data": [{
    "id": 1001,
    "title": "ユーザー検索",
    "description": "登録済みのユーザーの一覧を検索することができます。"
  }]
}

🙆 good

GET /menu_items

{
  "meta": null,
  "data": [{
    "id": 1000,
    "type": 1
  },{
  "meta": null,
  "data": [{
    "id": 1001,
    "type": 2
  }]
}

共通ルール

命名

endpoint（URL）

path

snake caseであること

🙅 Bad

/surveySettings/1

/survey-settings/1

🙆 good

/survey_settings/1

railsとの親和性を考慮しました

query paramter

lower camel caseであること

🙅 Bad

/survey_settings?suvey_id=1000

🙆 good

/survey_settings?suveyId=1000

クライアントサイドJSで触るデータに関してはクライアントサイドJSの命名規則と同じlower camel caseに統一しました。

response body

property名

lower camel caseであること

🙅 Bad

{
  "meta": null,
  "data": {
    "id": 1000,
    "first_name": "foo"
  }
}

🙆 good

{
  "meta": null,
  "data": {
    "id": 1000,
    "firstName": "foo"
  }
}

ページング

ページング操作に対応したエンドポイントにおいてはページング情報は下記の命名に従って下さい。

request:

response:

既存に暗黙の命名ルールがありましたがたまに外れた命名もあったため明文化しました。

HTTP method

POST、GET、PUT、DELETEのみ使って下さい。

各methodはCRUDのそれぞれに対応します。

responseのsatus code

正常系

一律 200 を設定して下さい。

異常系

エラーの表現を参照のこと。

response bodyのフォーマット

基本

リソースとリソース以外の情報（リストデータのページング情報、セキュリティトークン等）を分けるために、リソースをdataプロパティに、リソース以外の情報をmetaプロパティに分ける下記を基本のフォーマットとする。

{
  "meta": { // リソース以外の情報をここに定義
    "totalCount": 5000,
    "securityToken" "trHqrxxwK8mJhY"
  }, 
  "data": [
    // リソースはここに定義
    {
      "id": 100,
      "name": "foo"
    }
  ]
}

このルールは意見の別れるところかと思います。
response bodyはあくまでも純粋なリソースとし、meta情報はHTTP Responseの拡張ヘッダーに設定すべきという考え方もあります。
RESTを前提に扱ったツールと相性が悪いなどデメリットもありますが、情報がJSONに集約されていることによる開発・デバッグ時の分かりやすさを優先しました。

HTTP method: GET

フォーマットはendpointごとの任意の形式にして下さい。

HTTP method: POST

フォーマットはリクエストされたデータにID、生成日が設定されているデータにして下さい。

例）ユーザー情報の新規登録が正常に行われた場合のresponse

• 新規登録のrequest情報:
  • endpoint:
  • /users
  • requst body: json { "name": "foo", "gender": 1 }

🙅 Bad

status code: 200のみを返却し、response bodyを返却しない。

🙆 good

リソースのIDと生成日が含まれる下記のresponse bodyを返却する。

{
  "id": 1001,
  "name": "foo",
  "gender": 1,
  "createdAt": "2018-11-12T06:41:58.898+0900"
}

HTTP method: PUT

フォーマットはリクエストされたデータに更新日が更新されているデータにして下さい。

例）ユーザー情報の更新が正常に行われた場合のresponse

• 更新のrequest情報:
  • endpoint:
  • /users/1001
  • requst body: json { "id": 1001, "name": "bar", "gender": 0 }

🙅 Bad

status code: 200のみを返却し、response bodyを返却しない。

🙆 good

リソースのIDと更新日が含まれる下記のresponse bodyを返却する。

{
  "id": 1001,
  "name": "bar",
  "gender": 0,
  "updatedAt": "2018-11-12T06:44:34.894+0900"
}

HTTP method: DELETE

bodyを設定せず、status codeのみ返却して下さい。

非同期操作（※）

フォーマットはendpointごとの任意の形式にして下さい。

※ 非同期操作とは、バッチ処理を起動するなどの最終的な結果が即時に出ない操作を意味します。

エラーの表現

種類

エラーはシステム仕様上起こり得る業務エラーと、システム仕様上想定していないシステムエラーでエラーを区別し、適したエラーを定義して下さい。

業務エラー・システムエラーの具体例

業務エラーの例

• ユーザーの入力内容に誤りがあった。
  • 所謂バリデーションエラー
• 他のユーザーが削除したデータを参照した。
• 閲覧権限の無いリソースへのアクスセスを検出した。

システムエラーの例

• バグが原因でサーバーサイドで例外が発生した。
• 外部連携システムがダウンした。

responseのstatus code

業務エラー

エラーの種別により下記のstatus codeを設定して下さい。

上記は一例になります

システムエラー

エラーの種別により下記のstatus codeを設定して下さい。

status codeの追加について

扱うエラーに対して本ガイドラインで定めているstatus codeに適したものが無い場合、適したstatus codeをガイドラインに追加して下さい。
また、扱わないエラーのstatus codeをあらかじめガイドラインに追加しないようにして下さい。

参考：HTTPステータスコード

response bodyのフォーマット

エラーを表現する場合、基本的にはreponseのstatus codeで表しますが、クライアント側でより詳細なレベルのエラー情報が必要な場合にのみ、reponse bodyで詳細なエラー情報を表現して下さい。

基本

エラーの詳細情報を表す場合、下記の基本フォーマットに従って下さい。

{
  "meta": null,
  "data": [
    {
      "code": 400000,      // ※ 詳細エラーコード。必須。
      "message": "error!!" // 任意
    },
    // ...
  ]
}

※ 詳細エラーコードの採番についてはこちらで説明します。

基本フォーマットで表現できない詳細情報を付加したい場合は基本フォーマットを変更しないことを前提に拡張して構いません。

{
  "meta": null,
  "data": [
    {
      "code": 400002,
      "message": null,
      "rowNo": 1,       // 拡張部分
      "columnNo": 10    // 拡張部分
    },
    {
      "code": 400003,
      "message": null,
      "rowNo" 1,
      "columnNo": 15
    }
  ]
}

詳細エラーコードの採番規則

詳細エラーコードは数値型で、HTTPレスポンスのstatus codeと連番を組み合わせて採番して下さい。
フォーマットは６桁の数値で先頭３桁はstatus code、後続の３桁はエラー種別を表す0から始まる連番になります。

例）status codeが400のBad requestで、エラー種別が 3 の場合

{
  "meta": null,
  "data": [
    {
      "code": 400003
    }
  ]
}

詳細エラーコード

詳細エラーコードは下記を使用して下さい。

適したエラーコードが無い場合、上記のテーブルに追加して下さい。

Formのバリデーションエラー

Formのバリデーションエラーにおいて、エラー発生元フィールドとエラー情報を関連付ける必要がある場合は下記のルールに従って下さい。

• エラーレスポンスの詳細エラー情報ごとにfieldNameという名前のフィールドを追加し、リクエストに含まれているバリデーション対象のフィールド名を設定する

例）メールアドレスに重複エラーとクレジットカード番号に与信エラーのバリデーションエラーが発生した場合

• メールアドレスのフィールド名はemail、クレジットカードの番号のフィールド名はcardNoとします。
• メールアドレスの重複エラーの詳細エラーコードは400001、クレジットカードの番号の与信エラーの詳細エラーコードを400002とします。

request:

{
  "meta": null,
  "data": {
    "email": "osumi_kumamon@ggmail.com",
    "cardNo": "378282246310005"
  }
}

response:

（status codeは400:bad request）

{
  "meta": null,
  "data": [
    {
      "code": 400001,
      "fieldName": "email"
    },
    {
      "code": 400002,
      "fieldName": "cardNo"
    }
  ]
}

データが無い場合の表現

リソース自体が無い

リソースのデータ形式が配列の場合は空配列（[]）を設定して下さい。

{
  "meta": null,
  "data": []
}

リソースのデータ形式がObjectの場合はnullを設定して下さい。

{
  "meta": null,
  "data": null
}

リソース内の一部のpropertyが無い

リソース自体が無い場合のルールと同じです。

リソースのデータ形式が配列の場合は空配列（[]）を設定して下さい。

{
  "meta": null,
  "data": {
    "id": 1,
    "children": []
  }
}

リソースのデータ形式がObjectの場合はnullを設定して下さい。

{
  "meta": null,
  "data": {
    "id": 1,
    "firstName": "Thet Win Aung",
    "lastName": null
  }
}

データのフォーマット

データ型

基本的にデータに適したデータ型で設定して下さい。

🙅 Bad

{
  "meta": null,
  "data": {
    "id": 1,
    "score": "60.5" ‼️ 
  }
}

🙆 Good

{
  "meta": null,
  "data": {
    "id": 1,
    "score": 60.5 👍 
  }
}

日時型

ISO8601拡張形式のタイムゾーンJSTで表現して下さい。

🙅 Bad

{
  "meta": null,
  "data": {
    "id": 1,
    "createdAt": "2018/10/29 05:38:24"
  }
}

🙆 Good

{
  "meta": null,
  "data": {
    "id": 1,
    "createdAt": "2018-10-29T05:38:24.486+09:00"
  }
}

区分値

区分を表すコード値は数値で指定して下さい。

区分値の例

🙅 Bad

{
  "meta": null,
  "data": {
    "id": 1,
    "status": "in_progress"
  }
}

🙆 Good

{
  "meta": null,
  "data": {
    "id": 1,
    "status": 1
  }
}

真偽値

真偽を表すフラグ値はBooleanで指定して下さい。

フラグ値の例

🙅 Bad

{
  "meta": null,
  "data": {
    "id": 1,
    "published": 1
  }
}

🙆 Good

{
  "meta": null,
  "data": {
    "id": 1,
    "published": true
  }
}

サニタイズ

responce bodyをXSS対策のためにサニタイズせず、rawデータで指定して下さい。

🙅 Bad

{
  "meta": null,
  "data": {
    "id": 1,
    "name": "<script>alert("foo")</script>"
  }
}

🙆 Good

{
  "meta": null,
  "data": {
    "id": 1,
    "published": "<script>alert(\"foo\")</script>"
  }
}

サニタイズはクライアントサイドのテンプレートシステムで行なっているためです。

query parameter

配列

配列データは<フィールド名>[]で表現して下さい。

🙅 Bad

GET /suveys?id=1,2,3,4,5

🙆 Good

GET /suveys?id[]=1&id[]=2&id[]=3&id[]=4&id[]=5

railsとの親和性を考慮しました。

構造を持つデータ表現

複数の異なるリソースを含むリソースはリソース単位でネスト構造を持たせて表現して下さい。

🙅 bad

{
  "meta": null,
  "data": {
    "id": 1,
    "name": "foo"
    "barId": 1,
    "barName": "foo"
  }
}

🙆 good

{
  "meta": null,
  "data": {
    "id": 1,
    "name": "foo"
    "bar": {
      "id": 1,
      "name": "foo"
    }
  }
}

エンドポイントのネスト

エンドポイントのネストは基本的にせず、path parameterよりquery parameterで表現することを優先して下さい。

🙅 bad

/companies/:company_id/survys/:survey_id/foos/:foo_id

🙆 good

/foos/:foo_id?companyId=:company_id&surveyId=:survey_id

REST原則に外れる設計パターン

REST原則に従うことによってアプリケーションとして問題が生ずる場合があります。

下記に示すパターンに沿って設計を行って下さい。

WebAPIコールのN+1問題

問題

複数のリソースで構成されたリソースの一覧を取得する場合、単純にRESTらしい設計を行うとN+1問題が発生します。

下記に例を示します。

前提

• 画面表示対象の回答者は100人いる
• 回答者として表示する情報は回答数、ユーザー名、性別、生年月日
• 用意されているリソースは下記の２つ
  • 回答者リソース
    • Endpoint: /answers
    • 回答数とユーザーIDを保持する
  • ユーザーリソース
    • Endpoint: /users
    • ユーザー名、性別、生年月日を保持する

制御フロー

1. 回答者リソースを全件（100件）取得する
   • /answersのAPIコール数：1回
2. 回答者に紐づくユーザーリソースを取得する
   • /users/:idのAPIコール数：100回

😱回答者の数だけAPIコールが発生しクライアント側のパフォーマンスやサーバー負荷の問題が発生しうる!!

設計パターン

本問題に対する設計パターンは２つあり、それぞれの状況によって使い分けて下さい。

パターンA: リソースの検索条件として複数のIDを指定できるようにする

対象のリソースのEndpointのフィルタ条件として複数のIDを指定できるように設計します。
これにより複数のリソースで構成された情報を取得する際のAPIコール回数がリソースの種別数分に抑えることができます。

先の例ではユーザーリソースのフィルタ条件に配列型のIDを定義できるようにします。

1. 回答者リソースを全件（100件）取得する
   • /answersのAPIコール数：1回
2. 回答者に紐づくユーザーリソースを取得する
   • /users?id[]=1&id[]=2&id[]=3....のAPIコール数：1回

😀合計２回のAPIコールで済みました。

基本的にはパターンBよりパターンAを優先します。

パターンB: リソースに異なるリソースを含める

REST原則に違反する形にはなりますが、リソースに異なるリソースを含めます。
これにより複数のリソースで構成された情報を１度のAPIコールで取得することができます。

先の例では回答者のリソースにユーザーのリソースを含めるように拡張します。

{
  "meta": null
  "data": [
    {
      "id": 1,
      "answerCount": 50,
      "user": {
        "id": 1,
        "name": "foo",
        "gender": 1,
        "birthDate": "1994-07-30T00:00:00.000+0900"
      }
    },
    {
      "id": 2,
      "answerCount": 45,
      "user": {
        "id": 2,
        "name": "bar",
        "gender": 0,
        "birthDate": "1974-10-02T00:00:00.000+0900"
      }
    },
    ...
  ]
}

パターンAとの使い分けの観点としては、このリソースが拡張した異なるリソースとともに複数個所でよく使われるのかどうかになります。

よく使われる場合はパターンAよりパターンBを採用した方が良いでしょう。
そうでなければ、拡張したリソースは多くのケースで余計な情報になるためパターンAを採用すべきでしょう。

また、本パターンを採用する場合、拡張するリソースが3種類以上、及び3階層以上にならないようにして下さい。

🙅 Bad

{
  "meta": null
  "data": [
    {
      "id": 1,
      "answerCount": 50,
      "user": {
        "id": 1,
        "name": "foo",
        "gender": 1,
        "birthDate": "1994-07-30T00:00:00.000+0900",
        "company": {  // 🙆 2階層目のリソース
          "id": 100,
          "name": "bar",
          "address": { // 🙅 3階層目のリソース
            "id": 30,
            "location": "東京都中央区銀座6丁目10-1"
          }
        }
      },
      "answerdQuestion": [{ // 🙅 3種類以上のリソース
        "no": 1,
        "title": "第一問 あなたの性別は？",
        "answer": 1
      }]
    },
    ...
  ]
}

🙆 good

パターンAを使用し複数のリソースを複数回のAPIコールで取得する、もしくは画面に最適化した専用のリソースとして新たに定義しましょう。

最後に

紹介したガイドラインを適用した本格運用をまだ始めたばかりで、今後足り無い部分や余計な部分など色々な問題が出て来ると思います。
しかしこの点に関しては心配はしていません。

ガイドラインはシステムの改変、チームの成長、文化の変化などにより成長していく生き物のようなものです。
チームでこのガイドラインを放置せず大切に育て行くことにこそ意義があります。

ということでレビューをしてくれた全ての開発メンバーの皆様ありがとうございました！！
一緒にガイドラインを大切に育てて行きましょう！！😀

最後の最後に

組織改善にご興味のある方は全ての組織がこれで変わるモチベーションクラウドを是非ご検討して頂ければと思います！！

フロントエンドAPIモック導入したことでビルド時間が爆速になった

おはようございます、モチベーションクラウドの開発に参画している@sinpaoutです。

TL; DR
Docker + Rails + Mysql + webpackerで起動するのが時間かかりすぎるので
全てを捨ててnodeのみ（webpack-dev-server）で生きていくことに。。。

環境

Rails + Mysql + webpacker（vue.jsビルド）がDockerイメージとして管理され、
コマンド一発で開発環境を起動できる。

問題

起動にdb:setup や db:migrate などDBの初期化が走り大体3〜5分前後かかる。
更に画面が起動後にWebpackerが走り、フロントのビルドは１分ちょい。

DBの処理化なしでマイグレーションのみでもRailsが立上がるまで2,3分かかってしまう。
普段はJSのビルド時間も入れると5分はかかってしまう。

立上がったあとは毎回ログインして目的の画面に進むが途中で何かしらエラーに直面して進めなくなることはよくある。
また、 Seeds データが全てのパターンきちんと用意さていない事が多く
目的の画面まで到達するのにかなりの時間と労力がかかってしまう。
ときにはDockerが壊れて丸一日をクジラのお世話に費やされてしまうエンジニアもいた。

Seedsデータを用意できても更新系やデータのありなしなどの
パターンはDBを直接触る必要が出てき来たりするので手間がかかるので
APIモックシステムの構築を検討することになった。

APIモックとは

APIをJSONファイルとしてwebpack-dev-serverなど簡易Webサーバで提供する仕組み
Railsなどのバックエンドを起動しないため高速に開発環境を起動可能

バックエンドの関係者たちを退場させる：

Nodeは今どきnvmなど入れとけばバージョン管理も楽なのでDockerも退場。
（みんな今まで頑張ってくれてありがとう。。。）

アプリのAPIパスとJSONファイルのマッピングはyamlファイルで定義し
axiosのintercepeterでアドレスを変換する

使ってみる

マッピングの設定：

# js/mocks/apiMapper.yml
default:
  desc: デフォルトのモック
  api:
    /users: mocks/users.json
    /users/1/: mocks/users/detail.json

users.json の中身

{
  "users": [{
    "id": "",
    "name": "",
  }]
}

上記の例は
/users のAPIをmocks/users.json に
/users/1/ のAPIを mocks/users/detail.json
に置き変える。

※ パスのidの部分は全て1として解釈するようにする。

APIをJSONファイルと関連付けてくれる人

API mocker 役割

API Mockerの詳細

// js/mocks/apiMocker.js
import urlParse from 'url-parse'
import apiMapper from './apiMapper.yml'

const defaultApi = apiMappers.default.api

global.apiMockIntercepter = (config) => {
  const originalUrl = config.url
  const parsedUrl = urlParse(config.url)
  let apiPath = parsedUrl.pathname.replace(new RegExp(`^${config.baseURL}`), '')

  // idをすべて1に置き換える
  apiPath = apiPath.replace(/\/([0-9]+)\//ig, '/1/')
  const mockApiPath = defaultApi[apiPath]

  if (mockApiPath) {
    // 強制的にGETに
    config.method = 'get'
    config.url = config.baseURL + mockApiPath
    // 元情報を書き出す
    console.info('api mocked', originalUrl, mockApiPath)
  }

  return config
}

※ 環境に合わせてパスを調整する必要がある。

Webpackの設定

普段は index のみバンドルするが、実行環境がlocalの時のみ apiMockerを挿入する。
apiMocker が index より前に挿入する必要がある。

CopyWebpackPlugin:
モックのJSONファイルをoutputパスにコピーさせる

// webpack.local.js
if (process.env.DEV_ENV === 'local') {
  ...

  // Inject api mocker
  webpackConfig.entry.index = [
    `${dir.mocks}/apiMocker.js`,
    `${dir.js}/index.js`
  ]

  webpackConfig.plugins.push(new CopyWebpackPlugin([{
    from: `${dir.mocks}/api/`,
    to: `${output.path}/api/`
  }]))

  ...
}

axiosの設定

実行環境がlocalの時かつ apiMockIntercepter が存在したら使うようにする

axios.interceptors.request.use((config) => {
  if (process.env.DEV_ENV === 'local' && global.apiMockIntercepter) {
    return global.apiMockInterceptor(config)
  }
  return config
})

モックマッピングの拡張

パターンごとに切り替えられるようにする。

# js/mocks/apiMapper.yml
default: &default
  desc:
  api: &api
    /users: /users.json
    /users/1/: /users/detail.json
    ...

noData:
  <<: *default
  api:
    <<: *api
    /users: /users_no_data.json

noData のパターンでは /users をデータなしに置き換える

users_no_data.json

{
  "users": []
}

一捻り

Devtoolのネットワークでデバッグ

元のAPIやPOST場合は中身がリクエストの中身がわからなくなるので
console で元の情報を表示するように apiMocker を更新

// js/mocks/apiMocker.js
global.apiMockIntercepter = (config) => {
  const originalUrl = config.url

  ...

  if (mockApiPath) {

    ...

    // 元情報を書き出す
    console.info('api mocked', originalUrl, mockApiPath)
  }

  return config
}

UIからの置き換え

開発時に直接モックを切替変えられると、より効率上がるので
画面の右上あたりにパターン一覧を置き換えるポップアップ的なものを実装。

ブラウザーのリロード後もモックの設定を有効にしたいのでsessionStorageに突っ込む。
cookieを使わない理由はhttpOnlyなどを考慮したため。

E2E用

Cypressなどからパターンを変えられるように apiMocker を更新

// js/mocks/apiMocker.js

const apiMocker = {
  currentPattern: sessionStorage.getItem('apiMockerPattern') || 'default'
}

// E2Eようの外部モジュールから参照できるようにグローバル変数にしておく
window.apiMocker = apiMocker

...

// モックパターンをセットする関数を用意
apiMocker.setCurrentMock = function (patternName) {
  apiMocker.currentPattern = patternName
  sessionStorage.setItem('apiMockerPattern', apiMocker.currentPattern)
}

global.apiMockIntercepter = (config) => {
  ...
  const apiMap = apiMappers[apiMocker.currentPattern].api
  const mockApiPath = apiMap[apiPath]
  ...
}

Cypressから使う

cy.window().then((win) => {
  win.apiMocker.setCurrentMock('noData')
  cy.visit('localhost:8081/company/1/users')
})

結果

• 開発環境の立ち上げ5分 → 1分ちょい
• パターンごとにのデータの用意がjsonファイルのみで完結（ストレス激減）
  • Dockerの死亡やSeed不足の悩みから開放
• E2Eからのパターンが切替えられるようになるためUIテストが書きやすい
• DirやPOなどのエンジニア以外への画面共有が楽

今後の追加機能

• Webpackerのビルド廃止（Railsと完全に縁を切る）
  • Railsは嫌いではない（むしろ好き）がやりすぎると制御しづらくなるの要注意。
• POSTなどの更新系API対応
• 4xx、5xx系のエラー対応
• webpackのバージョンアップやチューニング
• プルリクエスト単位でのレビュー環境の用意
  • 静的なファイルで再現できるためS3にビルド結果を展開が可能

Cypressの導入

おはようございます、モチベーションクラウドの開発に参画している@sinpaoutです。

TL; DR

フロントエンドの機能動作を担保するためCypressを導入しインテグレーションテスト機構を構築した。
Cypressの導入、使い方、工夫、運用方法について記述する。

経緯

新機能を開発していると、ある日「手を止めて負債を解消しようぜ」という天命が下って希望の日差しが見えた。

みんなで負債リストを書き出し、優先順位づけしてリファクタリングを行う準備をした。
そこでリファクタリングの動作確認に自動テストの導入が必須であることに気づきCypressを使ったインテグレーションを導入することに至った。

インテグレーションテストとは

ユニットテストを増やすと勝手に品質が上がるという話をよく聞くが
書くことが多く短時間で品質を担保するためには不向き。
しかし、E2E全機能を全ブラウザーでテストもできないので
Chromeのみで基本動線を担保するレベルのものにすることになった。

環境

Rails、Vue+Vuex、SPA。
一部coffee+erbも残っているが今回はSPAだけを対象にする。

Cypress

先ず動かして感覚をつかめる

https://docs.cypress.io/guides/getting-started/writing-your-first-test.html#Add-a-test-file

実際のテスト

シナリオ１

• データが存在する場合ユーザー一覧が表示されること
  
• データなしのメッセージが表示されないこと

cy.get('.users tbody tr').should('to.have.length.gt', 0)
cy.get('.empty-msg').should('not.exist')

基本的にDOMの特定はcy.getを使いjqueryのセレクターがサポートされている。

アサーションはshould関数をしよう。

シナリオ２

• 一覧のデータをクリックすることで詳細ページへ遷移できること
• 表示されたページが詳細ページであること
• パンくずの一つ前をクリックで元の一覧画面に戻ること

import url from 'url'

cy.get('.users tbody tr').eq(0).click()
cy.url().should(pageUrl => {

  const parsedUrl = url.parse(pageUrl)
  // urlが正しいこと
  expect(parsedUrl.pathname.match(/\/user\/[0-9]+/)).to.ok
})

※ SPAのURLの検証はパターンのみ検証するため正規表現を使う

Page Object Pattern

各テストでDOMを直接参照しているとDOMの変更があった場合の修正範囲が広がる。
別の画面の機能を呼び出したい時にページのDOM構成を調べる必要がある。

上記の問題を解決するためPage Object Patternを導入する。

先ず共通的なPage Objectを追加。

• ページを意識しない共通的な機能を実装

import url from 'url'

const PAGE_URLS = {
  companies: '/companies/?',
  users: '/companies/[0-9]+/users/?',
  users: '/companies/[0-9]+/users/[0-9]+/?'
}
export default class PageObject {
  reload () {
    cy.reload()
  }

  breadcrumb () {
    return cy.get('.breadcrumbs')
  }

  breadcrumbs () {
    return cy.get('.breadcrumbs-list > li')
  }

  // 現在のページのURLをチェック
  isPageOf (pageName) {
    cy.url().should(pageUrl => {
      if (!PAGE_URLS[pageName]) {
        throw new Error(`Page url regex not found for pageName: ${pageName}`)
      }

      const pathReg = new RegExp(PAGE_URLS[pageName])

      const parsedUrl = url.parse(pageUrl)
      expect(parsedUrl.pathname.match(pathReg)).to.ok
    })
  }
}

各ページのPage Objectが共通を継承し、該当ページの機能を実装。

import CommonPageObject from '../../common/PageObject'

const URL = '/users'

export default class UsersPageObject extends CommonPageObject {
  visit () {
    cy.visit(URL)
  }

  // 検索エリアを開く
  expandSearchArea () {
    cy.get('.users .fieldset').then($elements => {
      if ($elements.length <= 2) {
        cy.get('.users .expand-button').click()
      }
    })
  }

  // 検索ボタンの押下
  search () {
    cy.get('.users .actions button').click()
  }

  getUserRows () {
    return cy.get('.user-list tbody tr')
  }

  emptyMessage () {
    return cy.get('.empty-data')
  }
}

シナリオ３

• リクエストの中身を検証する

共通PageObjectに関数を追加。

// PageObject.js
spyApiModule () {
  cy.window().its('axios').then((module) => {
    cy.spy(module, 'get')
    cy.spy(module, 'post')
    cy.spy(module, 'put')
    cy.spy(module, 'delete')
  })
}

getSpiedApiModule () {
  return cy.window().its('axios')
}

※ windowオブジェクトからaxiosを取得しているので
axiosがグローバル変数としてセットされている必要がある。

if (process.env.NODE_ENV === 'test') {
  window.axios = axios
}

使い方

import UsersPageObject from './UsersPageObject'

const userPage = new UsersPageObject()

// 予めスパイさせる
userPage.spyApiModule()
userPage.search()

userPage.getSpiedApiModule().then((module) => {
  cy.wrap(module.get).should('be.called')
  const firstArgs = module.get.firstCall.args[0]
  const parsedQuery = queryString.parse(url.parse(firstArgs).query)

  expect(parsedQuery).eqls({
    page: '1',
    limit: '25',
    sort: 'email',
    direction: 'asc'
  })
})

※ SpyモジュールはSinonが使われている。

運用

テストの記述は２段階に分けて行う。
1. 先ずテストケースだけ（describeとit）のみを記述しレビューを通す
2. それからテストの中身（DOM操作やアサーション）を記述する

テストケースとテストの中身を分けることによってレビューコストを削減ができる。

また、作業分担できるので担当者の得意な部分を依頼ができ、作業効率化が図れる。

Config

cypress.json

{
  "baseUrl": "http://localhost:8081/",
  "ignoreTestFiles": [
    "!/**/*.spec.js"
  ],
  "viewportWidth": 1300,
  "viewportHeight": 800,
  "video": false
}

integrationフォルダー配下は全てテストファイル扱いになる。

PageObejctのファイルを対象外にしたいので *.spec.js のみが対象となるようにする。

CI連携

モックサーバーが立ち上がってからCypressが走る必要あるのでCI上では工夫が必要。
先ず公式のGuideを参照し、npm scriptを工夫する。

モック

モックサーバーは基本的にDockerなどを使わずローカルでwebpack-dev-serverで起動する。
APIのモックはJSON静的なJSONファイルで提供している。

APIモックの詳細はこちらの記事 を参照。

シェルスクリプトを用意して環境変数のセットとwebpack-dev-serverの起動を行っている。

./bin/local-front-dev

運用コマンド

# モックサーバーを起動
yarn serve:local

# Cypressのtest runnerを起動（モックサーバーを立上げておく）
yarn cy:open

# ヘッドレスでテストを実行（モックサーバーを立上げておく）
yarn cy:run

# ローカルでテストを記述
yarn e2e:local

# CI上でテストを実行
yarn e2e:ci

タスクの詳細

Cypressの起動＆テストタスク

"cy:open": "cypress open",
"cy:run": "cypress run",

モックサーバー起動・終了タスク

"serve:local": "./bin/local-front-dev",
"serve:local:kill": "kill $(lsof -i :8081 | grep node | awk '{print $2}')",

モックが立ち上がるのをwaitするタスク

"serve:local:wait": "wait-on http-get://localhost:8081/assets/packs/index.js",

ローカル用タスク

"e2e:local": "run-p serve:local e2e:test",
"e2e:test": "run-s serve:local:wait cy:open",

CIで用タスク（終了後プロセスを殺す）

"e2e:ci": "run-p serve:local e2e:ci:test",
"e2e:ci:test": "run-s serve:local:wait cy:run serve:local:kill",

wait-on モジュールのスターも忘れずに。

問題

ヘッドレスの場合 Electron ブラウザーしか選択肢がない。
テストケースによってヘッドレスで固まってしまうことがあるので
CIの安定した運用はまだ先になりそう。

Chromeのヘッドレスもサポートするそうで期待したい。
https://github.com/cypress-io/cypress/issues/832

感想

E2Eに特化しているサービスだけあってデバッグ機能など豊かで使いやすい。
OSSで始められて将来テストが遅くなったらお金払って並列実行などで運用してもらうことも可能。

Test runner:

Test runner のUI上でselectorやデータ型の相違などの問題が解決するので
になれることをおすすめ。

https://docs.cypress.io/guides/core-concepts/test-runner.html#Overview

おまけ

主に使われるコマンド一覧。

visit:

指定のURLへ遷移

cy.visit('http://localhost:8081/')

url:
現在のURLを取得

cy.url().should('include', '/operations/companies/1/users')

get:
DOMの取得

cy.get('.breadcrumbs-menulist > li').eq(0).click()

contains:
指定の文字列が含まれている要素を取得

cy.contains('メンバー設定').click()

eq:
複数要素取れた場合指定インデックスで取得

cy.get('.users-actions button').eq(1).should('be.visible')

find:
小要素から検索

cy.get('.users-conditions .users-field')
  .find('input[type=text]')
  .should('have.value', '田中')

children:
小要素一覧を取得

cy.get('.users-conditions .users-field')
  .eq(fieldIndex)
  .find('select.form-select-target')
  .should('be.visible')
  .children()
  .should('have.length', options.length)

click:
クリックイベントを発火

cy.get('.breadcrumbs .breadcrumbs-menulist').eq(0).find('a').click()

select:
セレクトボックスを指定した値で選択

cy.get('.users-conditions .users-field')
  .find('select')
  .select('3')

each:
小要素一覧を回す

wrap:
取得した要素をラップしてCypressコマンド使えるようにする

cy.get('.users-conditions .users-field')
  .find('select.form-select-target')
  .children()
  .each(($el, index) => {
    cy.wrap($el)
      .should('have.value', options[index].value)
      .and('have.text', options[index].text)
  })

アサーション

should:
基本的なアサーションの作成機能である。
文字列として指定できるものはchainersと予備chaiはsinonの関数が使える。
https://docs.cypress.io/api/commands/should.html#Syntax

// テキストフィールドが表示されていること
cy.get('.users-conditions .users-field')
  .should('be.visible')

// クラスが指定されていないこと
cy.get('.list-pager .list-pager-next')
  .should('not.have.class', 'is-disabled')

// href属性が存在すること
cy.get('.users-conditions .users-link')
  .should('have.attr', 'href')

// 指定数のDOMの数がヒットすること
cy.get('.users-conditions .users-item')
  .should('have.length', 5)

// 指定した値が選択されていること
cy.get('.users-conditions .users-item')
  .should('have.value', '3')

// 指定した文字列が入力されていること
cy.get('.users-conditions .users-item')
  .should('have.text', 'user01@mail.com')

and:
shouldと合わせてAND条件を指定可能にする

cy.get('.users-conditions .users-link')
  .should('have.attr', 'href')
  .and('contain', '/operations/companies/1/magellan_operation_menu')

expect:
ChaiのBDDアサーション
https://docs.cypress.io/guides/references/assertions.html#Chai

// trim後の文字列の比較
expect($btn.text().trim()).eq('検索')
// checkboxが中間（未選択）状態であること
expect($el[0].indeterminate).eq(true)

リクエストの中身

server:

router関数が使用可能にするためにサーバーを起動

route:

ネットワークリクエストの振る舞いを管理

as:

ルートのリクエスト情報のエリアス、DOMでも使用可能

it('Getting users api status should be 200', () => {
  cy.server()
  // companies/1/users で始まるリクエストを監視
  cy.route('GET', '/companies/1/users*').as('getUsers')
  cy.get('.users-conditions .users-form-actions button').click()
  cy.url().should('include', '?page=1&sort=email&direction=asc')

  // getUsersエリアスのxhrオブジェクトからstatusを取得
  cy.wait('@getUsers').its('status').should('eq', 200)
  cy.visit('/operations/companies/1/users')
})

ApiモジュールのSpy

it('リクエストパラメーターにpage、sort、directionのみが含まれること', () => {
  userPage.spyApiModule()
  userPage.search()

  userPage.getSpiedApiModule().then((module) => {
    cy.wrap(module.get).should('be.called')
    const firstArgs = module.get.firstCall.args[0]
    const parsedQuery = queryString.parse(url.parse(firstArgs).query)

    expect(parsedQuery).eqls({
      page: '1',
      limit: '25',
      sort: 'email',
      direction: 'asc'
    })
  })
})

小技

例：windowオブジェクトからaxiosを取得してaxios.getをスパイする

Spyの機能一覧

cy
  .window()
  .its('axios')
  .as('axios')
  .then((axios) => {
    cy.spy(axios, 'get')
  })

...

cy.get('@axios').then((axios) => {
  expect(axios.get).to.be.calledOnce
})

デザイナーとStorybookをS3上で共有

おはようございます、モチベーションクラウドの開発に参画している@sinpaoutです。

開発の流れ

UI部品をStorybookで管理しデザイナーが部品の組合せで画面デザインを行う。
Storybook化されている部品で完結するデザインはワイヤーレベルのもので実装する。
デザインの差異などが発生したらStorybookが正解とする。

問題

• デザイナーが簡単にStorybookを閲覧できる環境がない
• 開発現場にいる場合はエンジニアのPCを覗いて閲覧するしかない
• 見ているブランチが古かったりする
• リモートの場合は見れないがどうしているのだろうか！！

解決策

• Storybookを静的にビルドしS3で展開てい共有
• 成果物はブランチ単位でビルドし、誰でも簡単に見れるようにする

S3の展開への流れ

手動で実行するshellを用意し、エンジニアが実行してアップロードする。
将来はCIと連携してPushのたびにビルドされるようにすることも可能。
ブランチ一覧のページを用意し、見ているブランチを認識できるようにする。

展開コマンド

./bin/publish-storybook.sh

詳細

aws s3 sync などのコマンドが使えるようにする。
現場では awsアカウントは開発でログインしているので aws-cli は普通に使用可能

npm-scriptsの用意

"storybook:build": "rm -rf tmp/storybook && build-storybook -c ./js/.storybook -o tmp/storybook",

バケットと同期

# bin/publish-storybook.sh

branch=$(git symbolic-ref --short HEAD)
# "/" は問題ありそうなので一旦 "_" に置き換えておく
folder=$(echo $branch | sed -e "s/[/]/_/g")

yarn storybook:build

# コンテンツはbranchesディレクトリ配下におく
aws s3 sync $STORYBOOK_PATH "s3://$S3_FOLDER/branches/$folder" \
  --delete \
  --acl public-read

※ acl が public-read だが後述するセキュリティーで制限している

ブランチのデータ

S3上のフォルダー一覧をbranches.txtとして書き出す。
不要な文字列を切り取る。

aws s3 ls "s3://$S3_FOLDER/branches/" | \
  sed -e "s/ PRE //g" | \
  sed -e 's/[ /]//g' > tmp/branches.txt

ブランチ一覧の表示用ページ

ブランチ一覧を表示するhtmlファイルもアップロード。
htmlファイルはS3にあれば動作するがgitで管理したいので毎回アップロードしておく。

htmlの中身は同じディレクトリのbranches.txt をajaxで読み込んで
一覧のリンクを表示するのみ。

aws s3 sync js/.storybook/s3 \
  "s3://$S3_FOLDER" \
  --exclude "*" \
  --include "index.html" \
  --acl public-read

Storybookの一覧

各リンクからStorybookが見れる。

セキュリティー

ACLをpublicにしているがバケットポリシーで社内からしか見れないようにIP制限する。

バケットポリシージェネレーター：
https://awspolicygen.s3.amazonaws.com/policygen.html

後始末

ビルドしたコンテンツの削除処理はS3に任せる。

バケット → 管理 → ライフサイクルルールの追加

名前とスコープ：
ライフサイクル名は分かりやすいのを入力。

prefixはバケットを除いたディレクトリのパス
my-bucket/storybook/branches の場合はstorybook/branches にする。

移行：
何もしない

有効期限：
現行バージョン をチェック
オブジェクトの現行バージョンを失効する をチェック
日数を90にする。

これでコンテンツが作成されてから90日後に消去される。

はまったポイント

S3の静的サイトホスティングのパスが分かりづらい。
htmlファイルなどのコンテンツの詳細にあるリンクは遷移できない。

バケット名 → プロパティ → Static website hosting → エンドポイント を使う必要がる。

先ず始めてみるならこれだけで十分だがSSLやドメインの設定はCloud Frontで行う。

お疲れ様です。@dayoshixです。

ここ1年ほど仕事でvscodeを使ってVue.jsアプリを書いています。
今、vscodeに入れているプラグインの中からVue.js開発に関連していて便利だと思ったプラグインとかツールをまとめてみました。

ESLint

eslintを使用する場合は入れておきましょう。
後述するVeturを使用し単一ファイルコンポーネント(.vue)内のJSにeslintを効かせたい場合にも必要となります。

ESLint

Vetur

単一ファイルコンポーネントでVue.jsを書いている場合はほぼ必須のpluginです。
これがないとシンタックスハイライトや、HTMLやJSなど文脈に合わせたコード補間などが効かないので黙って入れることになります。

色々な事ができるのでドキュメントを一通り参照することをお勧めします。

中でもSetupページにある単一コンポーネントファイル内のJSにESLintを効かせるvscodeの設定は先に紹介したESLintプラグインを入れている場合は設定しておくとeslint-plugin-vueのEssentialなルールセットでチェックしてくれるので便利です。

また、ES Moduleのパス指定でWebpackのaliasを使用している場合、通常設定ではコードジャンプが効かなくなってしまうのですが、ここで紹介されているPath mappingをやっておくとコードジャンプが効くようになるので参考にすると良いでしょう。

Vetur

Bookmarks

単一ファイルコンポーネントを編集する際、コードが長くなればなるほど<template>、<script>、<style>の行ききが煩わしくなる事があります。
そういう場合に行単位でブックマークが出来てショートカットキーで移動できるこのプラグインが便利です。

Bookmarks

Vue Peek

vscodeの標準機能である参照先のコードをその場でのぞき見できるpeekを単一ファイルコンポーネントで行えるようになります。
peekをよく使う人は入れておくと便利かもしれません。

Vue Peek

その他

vscodeとは関係ありませんがVue.js開発に便利な物も紹介します。

Vue.js devtools

Vue.js開発を便利にするWebブラウザエクステンションで、Vue.js開発をする場合に最初に入れるべき物と言えます。
Vueコンポーネントのinspectionや状態、Vuexストアのmutationごとの状態などを参照する事が出来ます。

Vue CLI 3

Vue.jsアプリのベストプラクティスを適用したっぽいプロジェクト雛形を作成出来たり、Vue.jsのpluginやライブラリなどをアプリに組み込んで来れたり、色々できる開発補助ツールです。

これで作ったプロジェクト雛形と同等のレベルのものを一人で作るには膨大な時間と労力が必要なので特別な理由がない限り利用したいところ。

vue-devtools

総括

まとめてみるとVue CLI 3でいい感じのプロジェクトの雛形が出来て、vscodeにVeturを入れて、ChromeにVue.js devtoolsを入れるだけで快適な開発環境を手に入れる事が出来て今Vue.jsでWebフロントエンドを始める人は恵まれているなぁと思った。😌

はじめに

こんにちは、モチベーションクラウドの開発にフリーのエンジニアとして参画している@HayatoKamonoです。

この記事は、「モチベーションクラウド Advent Calendar 2018」8日目の記事となります。

概要

モチベーションクラウドの開発チームでは2018年10月から改善期間と称して、開発に関するガイドラインやルール作りをはじめとする、様々な改善活動に取り組んでいます。

その改善活動の一環として作成した「コンポーネント設計・実装ガイドライン」を今回は説明を交えながらご紹介して行きたいと思います。

目次

• Componentの粒度に関して
• Container ComponentとPresentational Component
• コンポーネントの共通化に関して
• コンポーネント実装時の細かな決め事
• CSSに関して
• まとめ

Componentの粒度に関して

これまではフロントエンド開発チームの中で「どの粒度でコンポーネントを切るか？」に関して共通の方針が存在していなかったため、人によって実装するコンポーネントの粒度がバラバラでした。

ただでさえ、Vueの場合、単一ファイルコンポーネントでコンポーネント実装を行うと、どうしても１ファイル内のコードが長くなりがちなので、色々な責務を一つのコンポーネントに押し込んでしまうと、何スクロールもしないと１ファイル内のコード全体を読み通すことが出来ないようなコンポーネントが簡単に出来上がってしまいます。

実際に、そのような産物もチラホラ・・・

そこで、フロントエンド開発チームでは、「コンポーネントの粒度」に関しての方針を決め、ガイドラインに入れることにしました。

Atomic Design

コンポーネントはAtomic Designを参考にし、以下の粒度を意識して実装するという方針に決めました。

• atoms
• molecules
• organisms
• templates
• pages

とはいえ、方針だけ決めても実際に運用に乗らなければ意味がありません。

Atomic Designは「実際に運用してみると難しい」というような話は度々、ネット上の記事で見かけたり、実際に聴いたりもします。

私自身、Atomic Designを参考にしてコンポーネント実装を行なった経験が以前ありましたが、自分の経験としても、「このコンポーネントはatomsなのか、moleculesなのか？」等と判断に迷うことが度々ありました。

また、チームの中にはAtomic Designでのコンポーネント実装を経験している人もいれば、そうでない人もいたので、チームのみんなで「何がどの粒度に該当するのか？」について、サンプルコードや既存のコンポーネントをベースに認識合わせを行なうことにしました。

大事にしたこと

Atomic Designの解釈について大事にしたことは「このチームにおいて、どう解釈するか？」です。なので、チーム内のみんなが納得感を持てれば、それが他のAtomic Designを取り入れている現場の解釈と異なっていてもOKということです。

atoms

• これ以上分割出来ない最小単位の機能を持つ
• (例)formのlabel、button、inputなど
• atomは他のatomを自身の範囲内に含むこともある

molecules

• 意味のある単位でatomを組み合わせて作られた集合体
• (例) フォームのラベル、テキストボックス、ボタンを組み合わせた検索ボックス
• moleculeは他のmoleculeを自身の範囲内に含むこともある

organisms

• 意味のある単位でatom、moleculeを組み合わせて作られた集合体
• (例) ロゴ、検索ボックス、ナビゲーションリンクを組み合わせたヘッダー
• organismsは他のorganismsを自身の範囲内に含むこともある
• 必要に応じてContainer Componentを通じて、VuexのstoreやVue Routerのrouteにアクセスする

templates

• レイアウトに責務を持つ
• 特定のレイアウトを適用したいコンポーネントの中で使われる(pagesレベルのコンポーネントに限定しない)
• 多くの場合、slotsを含む

pages

• atom、molecules, organisms, templatesの集合体
• 単一のURLに対応する
• 必要に応じてContainer Componentを通じて、VuexのstoreやVue Routerのrouteにアクセスする

共通方針

また、全てのレベルのコンポーネントに共通する方針として、コンポーネント自身にCSSのpositionやコンポーネントの外側へのmarginを持たさず、コンポーネントを使う側でそれらは指定するということも共通の認識として持つようにしました。

Container ComponentとPresentational Component

Reactコミュニティーでは、Dan Abramovの「Presentational and Container Components」で有名になった「Container Component」と「Presentational Component」を分けて実装するパターンがお馴染みです。

モチベーションクラウドのフロントエンド開発チームには、私自身も含め、React経験者がチラホラおり、2018年の8月、9月頃から、Container ComponentとPresentational Componentを分けようという動きが生まれました。

しかし、React未経験の開発メンバーにしっかりとコードをもとに、Container ComponentとPresentational Componentの違いを説明・共有出来ていなかったこともあり、Container Componentの認識が人によって異なるという状況が生まれていました。

結果、Container Componentの中にPresentationに関するコードが含まれてしまったりと、結局、ContainerとPresentationalで分離されていないコンポーネントが出来上がってしまうことにもなりました。

そこで、改めて、今回の改善期間の中で作成した「コンポーネント設計・実装ガイドライン」の中に、Container ComponentとPresentational Componentの説明をサンプルコードを交えて組み入れ、再度、認識の擦り合わせを行うようにしました。

目的の共有

そもそも、Container ComponentとPresentational Componentに分けることによって、どんなメリットがあるのかすら共有出来ていなかった為、その辺も含め、ガイドラインに組み込むようにしました。

可読性・保守性の向上

データや振る舞いに関心を持つContainer Componentと、見た目に関心を持つPresentational Componentに分離することで、どこに何が書かれているかが分かりやすくなり、アプリケーションのコードの理解がしやすくなるし、既存コードに機能追加や修正を行なう際には、どこに何を追加・変更すれば良いかが分かりやすくなる。また、１ファイル内のコード量も減るため、コードの見通しも良くなる。

再利用性の向上

Container ComponentとPresentational Componentに分けることで、Presentional Componentが特定のVuex側で持っている状態に依存しなくなり、他の異なるデータソースに差し替えても使い回しが出来るようになる。また、同様にContainer Component自体も同じデータや振る舞いに関心を持つPresentational Componentに対して、使い回しが効くようになる。

テスト容易性の向上

Container ComponentとPresentational Componentを分けることで、Presentational Componentのみを簡単に単体テスト出来るようになったり、リグレッションテストが出来るようになる。

並行作業の容易性向上

Container ComponentとPresentational Componentに分けることで、一人はAPIの繋ぎこみや振る舞いに関するロジックの実装、もう一人はコンポーネントのマークアップやスタイリングを行なうというように、ファイルのコンフリクトを気にせず、並行作業がしやすくなる。

Storybookの追加容易性の向上

Container ComponentとPresentational Componentを分けることで、Vuexのモックを用意するなどせずに、簡単にStorybookにコンポーネントを追加することが出来るようになる。

Presentational Component

特徴

• 見た目に責務を持つ
• VuexのstoreやVue Routerのrouteなどのアプリケーションの状態に依存せず、他のVueアプリケーションにも流用できる。
• 必要なデータがどのように読み込まれるか、また、どのように変更されるかを指定しない
• コンポーネント自身の状態は滅多に持たない。（仮に状態を持つとしても、それはUIに関する状態のみ）

状態を持たせない

Presentational Componentは親からpropsを通して、必要なデータを受け取り、自身を描画するだけのものです。本来のPresentational Componentの特徴としては、UIに関する状態であれば、その状態を持っても良いとあります。

しかし、私たちのチームで別途、作成したVuexのガイドラインでは「パフォーマンスに影響があるなどの特別な理由がない限り、全ての状態をVuexに寄せる」という方針があるため、Presentational Componentが状態を持つことはありません。

仮にVuex側で状態を持たせない方が良い場合は、後述するContainer Component側に持たせます。

サンプルコード

<template>
  <div>
    <h1 v-if="isOpen">Hello World</h1>
    <p>{{ message }}</p>
    <button @click="handleClick">toggle</button>
  </div>
</template>

<script>
export default {
  name: "HelloWorld",
  props: {
    message: {
      type: String,
      default: "I am not controlled"
    },
    isOpen: {
      type: Boolean,
      default: false
    }
  },
  methods: {
    handleClick() {
      this.$emit("click");
    }
  }
};
</script>

Functional Component

いわゆる、Leaf Componentと呼ばれるコンポーネントのように、ループ処理の中で同じコンポーネントが描画されるような場合には、Functional ComponentとしてPresentational Componentを実装することも検討します。

Functional Componentは単なる関数でインスタンスを持たないため、描画コストを少なく抑えることが可能です。

Container Component

特徴

• データや振る舞いに責務を持つ
• データや振る舞いをPresentational Componentや他のContainer Componentに提供する
• VuexのstoreやVue Routerのrouteを参照しても良い（しなくても良い）
• 通常、DOMのマークアップやCSSスタイルを持たない。(仮にDOMを持つとしても、それはラッパー用のdivタグなど)

サンプルコード

// Presentational Component
import SamplePage from "./SamplePage.vue";

/* 
  以下の`connect`は、Presentational Componentを引数に取り、そのコンポーネントが関心を持つ、
  VuexのmoduleのデータとVue Routerのメソッドへのアクセスを与えたContainer Componentを返す高階関数
*/
const connect = WrappedComponent => {
  return {
    name: `${WrappedComponent.name}Container`,
    computed: {
      count() {
        return this.$store.state.count;
      }
    },
    methods: {
      handlePageChange({ to }) {
        this.$router.push(to);
      }
    },
    render(createElement) {
      return createElement(WrappedComponent, {
        props: {
          count: this.count
        },
        on: {
          pageChange: this.onChangePage
        }
      });
    }
  };
};

/*
  次の2行は以下のコードをContainerの説明の為に、より明示的にしたもの
  export default connect(SamplePage);
*/
const SamplePageContainer = connect(SamplePage);
export default SamplePageContainer;

export { SamplePage };

コンポーネントの共通化に関して

現状、フロントエンド開発チームが抱える１つの課題として、似たようなコンポーネントが複数存在していたり、同じような処理が複数のコンポーネントに散らばっていたりする状況が多々あるというものです。

この状態に至った背景としては、開発の進め方や開発者同士の連携不足に原因があったり、コンポーネント分割やコンポーネント共通化に関する考え方・方法に対する理解不足に原因があるようでしたが、今回作成した「コンポーネント実装・設計ガイドライン」では、共通化の方法論について実際にサンプルコードをもとに共有・認識の擦り合わせを行なうようにしました。

共通化の手法

共通化を実現する方法としては、「継承」であったり、Vueの「Mixin」がありますが、継承は親と子が密結合な関係になってしまいますし、「Mixin」もまた暗黙の依存関係が生まれてしまいます。(※Reactも以前はMixinをサポートしていましたが、Mixinは暗黙の依存関係を生むため廃止しています。)

そのため、Reactコミュニティーではお馴染みのHigher Order Componentを用いたり、Reactコミュニティーで用いられるRender PropsやRender Childrenパターンと同様のことを実現するVueのScoped Slotsを用いて、データや振る舞いの共通化を行います。

ここでは、Higher Order ComponentとScoped Slotsを用いてContainer Componentを実装する簡易的な例を掲載します。

Higher Order Componentを用いた例

以下は、仮にクライアント側で認証を行うSPAであると仮定した場合に必要になりそうな、クライアント認証用のロジックやデータを提供するHigher Order Componentの例です。

Higher Order Componentは引数にComponentを取り、別のComponentを返す高階関数です。

Higher Order Component側

const requireAuth = WrappedComponent => {
  return {
    name: `${WrappedComponent.name}-protected`,
    computed: {
      isAuthenticated() {
        return this.$store.state.isAuthenticated;
      }
    },
    created() {
      // JWTトークンが存在、または、失効しているかどうかをチェック
      // トークンが無い、または、失効していたらログインページへリダイレクト
    },
    render(createElement) {
      return createElement(WrappedComponent, {
        props: {
          isAuthenticated: this.isAuthenticated
        }
      });
    }
  };
};

export default requireAuth;

使う側の例

// router.js

export default new Router({
  mode: "history",
  base: process.env.BASE_URL,
  routes: [
    {
      path: "/",
      name: "home",
      component: requireAuth(HomePage)
    },
    {
      path: "/about",
      name: "about",
      component: requireAuth(AboutPage)
    }
  ]
});

Scoped Slotsを用いた例

以下は、マウスの位置情報を提供するContainer Componentの例です。

Container Component側

export default {
  name: "MouseMoveTracker",
  data() {
    return {
      mousePosition: {
        x: 0,
        y: 0
      }
    };
  },
  methods: {
    handleMouseMove({ clientX, clientY }) {
      this.mousePosition.x = clientX;
      this.mousePosition.y = clientY;
    }
  },
  mounted() {
    this.$refs.wrapper.addEventListener("mousemove", this.onMouseMove);
  },
  beforeDestroy() {
    this.$refs.wrapper.removeEventListener("mousemove", this.onMouseMove);
  },
  render(createElement) {
    return createElement(
      "div",
      {
        ref: "wrapper"
      },
      [
        this.$scopedSlots.default({
          mousePosition: this.mousePosition
        })
      ]
    );
  }
};

使う側

<template>
  <div id="app">
    <MouseMoveTrakcer>
      <template slot-scope="{ mousePosition }">
        <SampleComponent :position="mousePosition" />
      </template>
    </MouseMoveTrakcer>
  </div>
</template>

<script>
import SampleComponent from "./components/SampleComponent";
import MouseMoveTrakcer from "./components/trackMouseMove";

export default {
  name: "App",
  components: {
    SampleComponent,
    MouseMoveTrakcer
  }
};
</script>

Container Componentにラップされる側

※ マウスの位置情報に関心があるコンポーネントであると仮定。

<template>
  <div>
    <p>X: {{ position.x }}</p>
    <p>Y: {{ position.y }}</p>
  </div>
</template>

<script>
export default {
  name: "SampleComponent",
  props: {
    position: {
      type: Object,
      required: true
    }
  }
};
</script>

コンポーネント実装時の細かな決め事

他にも命名規則やデータ型毎の初期値など、コンポーネント実装時のルールとして定めました。

また、これまでは「JavaScript Standard Style」を適用するESLintプラグインは導入していましたが、Vue用のESLintプラグインは導入していなかったため、まずは、ルールが緩め目の「vue/essensial」を導入し、自分たちでガイドラインを決めなくても良いものに関しては、VueのESLintプラグインが提供してくれるルールに乗っかることにしました。

イベントハンドラーとイベント名の命名規則

これまで特にイベントハンドラーやイベント名にルールがなかったため、例えば、人によってはイベントハンドラー名をhandleXXXのようにhandleで始めたり、onXXXのようにonで始めたりと、名前の付け方がバラバラでした。

そのため、一貫性を持たせコードの見通しを良くするためにも、以下のように命名規則の基本方針を固めました。

イベントハンドラー名

イベントハンドラー名はhandleCancelのようにhandleで始めます。 また、イベントが発生した対象をイベントハンドラ名に含める必要がある場合は、handleModalCloseのように、「on + 名詞 + 動詞」のように命名します。

methods: {
  // Good
  handleCancel () {
  } 
  // Good
  handleModalClose () {
  } 
  // Good
  handleKeyPress () {
  }
  // Good
  handleMouseMove () {
  } 

  // Bad
  onCancel () {
  }
  // Bad
  onCloseModal () {
  }
  // Bad
  onPressKey () {
  }
  // Bad
  onMoveMouse () {
  }
}

イベント名

emitするイベント名は、命名規則に沿ったメソッド名からhandleを取り除いた文字列とします。

methods: {
  handleCancel () {
    this.$emit('cancel')
  } 
  handleModalClose () {
    this.$emit('modalClose')
  } 
  handleKeyPress () {
    this.$emit('keyPress')
  }
  handleMouseMove () {
    this.$emit('mouseMove')
  } 
}

各データ型の初期値

コンポーネントのdataやpropsで持つデータ型の初期値に関して、個々の開発者によって認識がバラバラだったため、初期値としてより適切な値がある場合はそちらを優先することとしながら、基本的な方針として各データ型の初期値についてまとめることにしました。

※ Object型の初期値を{}としている理由は、後でobjectに追加したkeyの値がリアクティブになるため

propsのガイドライン

これまで、propsの定義に関しては最低限、propの型の指定はされていましたが、人によって、必須のpropにrequired: trueの指定がされていなかったり、default値の指定がされていなかったりと緩い状態になっていたため、VueのESLint Pluginでチェックが走るものもありますが、以下のように方針を固めました。

必須のpropsにはrequiredをtrueにする

props: {
  name: {
    type: String,
    required: true
  }
}

任意のpropsにはdefaultを設定する

props: {
  isOpen: {
    type: Boolean,
    default: false
  }
}

データ型を指定する

props: {
  name: {
    type: String
  },
  count: {
    type: Number
  },
  isOpen: {
    type: Boolean
  },
  item: {
    type: Object
  },
  mode: {
    type: String
  },
  selectedIds: {
    type: Array
  },
  date: {
    type: Date
  },
  customFunction: {
    type: Function
  }
}

propsの検証

propsで受け取る値が特定の条件に当てはまる場合は、propsの値にバリデーションを適用します。

以下はバリデーションの一例です。

props: {
  name: {
    type: String,
    validator (value) {
      return value.length > 0
    }
  },
  count: {
    type: Number,
    validator (value) {
      return value >= 0
    }
  },
  item: {
    type: Object,
    validator (obj) {
      const EXPECTED_KEY = 0
      const EXPECTED_VALUE_TYPE = 1
      const expectedPairs = [
        ['name', 'string'],
        ['count', 'number']
      ]
      const pairs = Object.entries(obj);

      return pairs.every(([KEY, VALUE], index) => {
        return KEY === expectedPairs[index][EXPECTED_KEY] && typeof VALUE === expectedPairs[index][EXPECTED_VALUE_TYPE]
      })
    }
  },
  mode: {
    type: String,
    validator (value) {
      const modes = ['easy', 'difficult']
      return modes.includes(value)
    }       
  },
  selectedIds: {
    type: Array,
    validate (values) {
      return values.every(value => typeof value === 'string')
    }
  },
  date: {
    type: Date,
    validate (value) {
      return value >= new Date(2000, 01, 01)
    }
  }
}

CSSに関して

前提として、モチベーションクラウドのフロントエンド開発においては、styled-componentsのようなCSS-in-JSは使っておらず、Scoped CSSの環境下でSassを利用し、CSSを書いています。

Scopeが切られた環境ということもあり、フロントエンド開発チームにはBEM記法は行わず、また、他に細かなルールを決めるということもしておらず、個々の開発者にCSSの書き方は委ねるといったスタンスでおりました。

一応、クラス名はclass-nameのようにハイフンで区切ったケバブケースにするという簡単な決まり事はありましたが、やはり、これだけでは、次第に辛いところが出てきました。

そのため、追加で「最低限、これだけは守ろう！」といった方針をガイドラインに組み込むことにしました。

要素型セレクターは使わない

pやulなど、要素セレクターは使用しません。代わりにclassセレクターを使用します。

BAD

<template>
  <div class="sample-component">
    <div>
      <p>Hello World</p>
    </div>
  </div>
</template>

<style lang="scss" scoped>
  div {
    ...プロパティを定義
    & > p {
      ...プロパティを定義
    }   
  }
</style>

GOOD

<template>
  <div class="sample-component">
    <div class="box">
      <p class="message">Hello World</p>
    </div>
  </div>
</template>

<style lang="scss" scoped>
  .box {
    ...プロパティを定義
    & > .message {
      ...プロパティを定義
    }   
  }
</style>

ケバブケースのクラス名を&や変数展開で繋がない

ケバブケースのクラス名を&や#{}を用いた変数展開で繋ぐと検索性や可読性を損ねるため、これらをクラス名の連結を目的として使用しません。

BAD

<template>
  <div class="sample-component">
    <div class="box">
      <p class="box-description is-large">
        <span class="box-warning>"Alert Message</span>
      </p>
    </div>
    <ul class="product-list">
      <li class="product-list-item">A</li>
      <li class="product-list-item">B</li>
      <li class="product-list-item">C</li>
    </ul>
  </div>
</template>

<style lang="scss" scoped>
  .box {
    $box: #{&};
    ...プロパティを定義
    &-description {
      ...プロパティを定義
      &.is-large {
        ...プロパティを定義
        #{$box}-warning {
          ...プロパティを定義
        } 
      }
    }
  }
  .product-list {
    ...プロパティを定義
    &-item {
      ...プロパティを定義
    }
  }
</style>

GOOD

<template>
  <div class="sample-component">
    <div class="box">
      <p class="description is-large">
        <span class="warning>"Alert Message</span>
      </p>
    </div>
    <ul class="product-list">
      <li class="item">A</li>
      <li class="item">B</li>
      <li class="item">C</li>
    </ul>
  </div>
</template>

<style lang="scss" scoped>
  .box {
    ...プロパティを定義
    .description {
      ...プロパティを定義
      &.is-large {
        ...プロパティを定義
        .box-warning {
          ...プロパティを定義
        } 
      }
    }
  }
  .product-list {
    ...プロパティを定義
    .item {
      ...プロパティを定義
    }
  }
</style>

まとめ

今回作成した「コンポーネント設計・実装ガイドライン」には、この記事の中では触れていないものもありますが、主要な部分に関しては共有出来たと思います。

ガイドラインは実際に運用出来ないと意味がないので、今後、新たにコードを書く際、既存のコードをリファクタリングする際、コードレビューを行なう際に、こちらのガイドラインで決めたことを適用して行きたいと思います。

また、ガイドラインは育てていくものでもあるので、実際に運用に乗せながら、試行錯誤をしつつ、必要に応じて追加・修正を行なって行きたいと思います。

関連記事

こちらの記事はモチベーションクラウド Advent Calendar 2018に投稿した記事です。

他にも、以下の記事をモチベーションクラウド Advent Calendar 2018に投稿しています。
- Vueを用いた開発プロジェクト用にカスタムジェネレーターを作ってみる
- Vueを用いた開発プロジェクト用に「コンポーネント設計・実装ガイドライン」を作った話
- Vuexを用いた開発プロジェクト用にガイドラインを作成した話

はじめに

こんにちは、モチベーションクラウドの開発にフリーのエンジニアとして参画している@HayatoKamonoです。

この記事は、「モチベーションクラウド Advent Calendar 2018」9日目の記事となります。

概要

モチベーションクラウドの開発チームでは2018年10月から改善期間と称して、開発に関するガイドラインやルール作りをはじめとする、様々な改善活動に取り組んでいます。

私が所属しているフロントエンド開発チームでは、すでに別記事でご紹介している「WebAPI設計ガイドライン」であったり、「コンポーネント設計・実装ガイドライン」を作成しました。

他にも作成したガイドラインはありますが、今回はモチベーションクラウドのフロントエンド開発で「状態管理パターン + ライブラリ」として導入しているVuexの利用に関するチーム内のガイドラインをサンプルコードや説明を交えながらご紹介出来ればと思います。

目次

• Storeの構造について
• 原則としてVuexで全ての状態を管理する
• Vuexのヘルパー関数を利用する
• ComponentからStoreのcommitを実行しない
• module間の依存関係を作らない
• moduleのactionをグローバルに登録しない

Storeの構造について

全モジュールにおいてnamespaceを切る

const modules = {
  namespaced: true,
  modules: {
    moduleA: {
      namespaced: true,
      // 略
    },
    moduleB: {
      namespaced: true,
      // 略
    }
  }
}

元々、モチベーションクラウドのフロントエンドアプリケーションではVuexのnamespaceは切っておりませんでした。

そのため、コンポーネント側からVuexのStore側にdispatchするイベント名の重複、衝突を防ぐために、１つのファイルでイベント名を定数管理し、それらの定数化されたイベント名をコンポーネント側やStoreのmodule側で読み込んで利用する方法を採用しておりました。

しかし、開発が進むに連れて、今後、アプリケーションの規模が更に大きくなった場合を考えると、名前空間をこのような泥臭いやり方で管理し続けるのは「辛い」、「不安」と言った声がチーム内で挙がってくるようになりました。

そこで、今回、Vuexのガイドラインを作成するにあたって、「namespaceを全モジュールで切るべきか、部分的に切るべきか？」をチーム内で議論し、意見が割れるところもありましたが、最終的には全モジュールでnamespaceを切るという方針に固まりました。

それに伴い、今後はイベント名を定数で管理し、毎回、利用する箇所で定数を読み込むといったことは辞め、イベント名を直接文字列で扱って行くことにもなりました。

実際、毎回、新たにdispatchするイベント名が登場する度に、定数管理するファイルにそのイベント用の定数を追加し、そして、その定数を利用する箇所で読み込まなければいけないという作業は冗長でストレスを伴うものであったため、この苦行から解放されるのはとても良いことだと思います。

ドメインとUIで状態を分けて管理する

Store内のmoduleをまず、ドメインに関する状態を管理するmoduleと、UIに関する状態を管理するmoduleで大きく２つに分けることにしました。

そして、それら２つのmodule下に更に付随するmoduleを展開していくといったmoduleの管理方法です。

サンプルコード

const modules = {
  namespaced: true,
  modules: {
    domain: {
      namespaced: true,
      modules: {
        users: { 
          // 略
        },
        organizations: { 
          // 略
        },
      }
    },
    ui: { 
      namespaced: true,
      modules: {
        common: {
          // 略
        },
        operations: {
          // 略
        }
      }
    }
  }
}

APIを通してサーバーサイドから取得するデータは必要に応じて、加工や正規化をして、domain以下のモジュールでそれぞれ管理します。

また、breadcrumbやmodalの状態のようなページ共通で持っておくことが好ましい状態は、ui以下のcommonモジュール内で管理し、、その他のページ固有のUIに関する状態はui以下にそのページ用のモジュールを置いて、そちらで管理します。

原則としてVuexで全ての状態を管理する

これまでフロントエンド開発チームにおいて、Vuex側で管理する状態と管理しない状態についての共通の方針が存在していなかったため、各開発者によって状態を管理する場所がバラバラでした。

そこで、今回、Vuex利用に関するガイドラインを作成するにあたり、これについても、チーム内で議論しました。

普通に考えると、「ドメインに関する状態はVuexのStoreで持ち、また、ページ遷移後も保持しておきたいようなUIに関する状態をVuexのStoreで持つ」、そして、「それ以外のUIに関する状態をコンポーネント側で持つ」、というのが自然かなと思いますが、最終的にチーム内で合意に至ったのは「パフォーマンスが懸念されるなどの特別な理由がない限り、原則として全ての状態をVuexのStoreで管理する」という方針です。

この決定に至った理由としては以下が挙げられます。

• Time Travel Debuggingが可能になるため、デバッグがしやすくなる
• テストがしやすくなる
• 複数人による開発の中で状態管理に一貫性が生まれる

個人的には、このようにVuexやReduxなどの状態管理ライブラリに全ての状態を寄せるという開発は初めてなので、やってみないと分からないところもありますが、実際に運用していくうちに「パフォーマンスの懸念」以外の理由で他にも、コンポーネント側で状態を持たせた方が良いケースが出てくるかもしれません。

その際は随時、チーム内で議論して、柔軟にガイドラインに調整をかけて行ければ良いと思っています。

dispatchするaction payloadの型

Storeのdispatchメソッドの第２引数に渡す値の型に関しても、今回のガイドライン作成を機に以下のように方針を固めました。

interface ActionPayload = {
  payload?: any,
  meta?: object,
  error?: boolean
}

元々、私自身がReact、Reduxを用いた開発の際には、Flux Standard Actionを取り入れているので、そのまま、Flux Standard Actionを参考にガイドラインに組み込みました。

サンプルコード

this.$store.dispatch('fetchUsers')

this.$store.dispatch('postUser', {
  payload: { id: 1, name: 'foo' },
  meta: { delay: 3000 }
})

this.$store.dispatch(validationFailed, {
  payload: { message: 'hello' },
  error: true
})

Vuexのヘルパー関数を利用する

Storeのmoduleのstateやactionを参照する方法は複数ありますが、それらを参照する際にはVuexのヘルパー関数を必ず利用するという制限を設けることにしました。