2016-03-29T10:10:11Z

Fumifumi: /* フロントエンドアプリケーション */

= 概要 =
　EosコマンドをWebブラウザ上で実行するためのアプリケーションである。
EosはCUIで実行する場合、[[OptionControlFile]]に基づいて実行時引数を解析している。
Zephyrでは、Webブラウザ上で動作するUIパーツを[[OptionControlFile]]を用いることで自動的に生成する。
OptionControlFileはそれぞれのコマンドの[[OptionControlFile]]を事前にJSON形式にパースし、Zephyrプロジェクトディレクトリの特定のディレクトリに格納してある。
Zephyrでは、JSON形式にパースされたOptionControlFileを使って、Webブラウザを通じてEosコマンドを実行するための様々な機能群を提供する。

= 必要なソフトウェア =
以下のソフトウェアを事前にインストールしておく必要がある。
2016年3月現在、以下のバージョンでの動作を確認している。
* Eos
* Node.js v4.2.4
* Ruby 1.9.3p551

= インストール =
== Node.js(v4.2.4)のインストール ==
Node.jsのバージョン管理システムnvmを用いてインストールする。(https://github.com/creationix/nvm)
# nvmのインストール
$ wget -qO- https://raw.githubusercontent.com/creationix/nvm/v0.30.1/install.sh | bash
$ source .bashrc

# Node.js(v4.2.4)のインストール
$ nvm install v4.2.4

# .bashrcに追記
$ echo nvm use 4.2.4 >> ~/.bashrc

== Zephyrのインストール ==
$ git clone git://git.osdn.jp/gitroot/eos/zephyr.git
$ cd zephyr

# 必要なnpmのパッケージをインストール
Zephyrでは、Node.jsのライブラリ管理システム(npm) に登録された様々なライブラリを使って開発されている。
事前にインストールしておく必要がある。
$ npm install

# .bashrcに追記し、PATHを通す
$ echo export PATH=/path/to/zephyr/node_modules/.bin:/path/to/zephyr/bin:\$PATH >> ~/.bashrc
$ echo export ZEPHYR_HOME=/path/to/zephyr >> ~/.bashrc

= 使い方 =
Zephyrディレクトリ中の/user-specific-files/OptionControlFileにJSONファイルが作成されていない場合、Zephyrを起動する前に、OptionControlFileをパースしておく必要がある。

# OptionControlFileのパース場合
$ zephyr parse

# Zephyrの起動
$ zephyr serve

# デバッグモードでの起動
$ zephyr debug

通常の起動、デバッグモードでの起動ともにWebブラウザを開き、アドレスバーにlocalhost:3000を入力し接続すると利用できます。
デバッグモードは、開発者のためのZephyr起動コマンドです。

= ディレクトリ構成 =
　Zephyrのディレクトリ構成を以下に示す。

├── bin　　　　　　　　　zephyrコマンドのバイナリへのシンボリックリンク 
├── cli　　　　　　　　　zephyrコマンドのソースコード 
├── docker　　　　　　　docker用のファイル群(未実装) 
├── front-end　　　　　　Zephyrのフロントエンドアプリケーション
　　　　　　　　　　　　　　(ブラウザ上で動くHTML, CSS, JavaScriptなどで作られたアプリケーション) 
├── node_modules　　　　　npmのライブラリ群 
├── package.json　　　　　Zephyrのパッケージ情報 
├── server　　　　　　　　Zephyrのサーバサイドアプリケーション
　　　　　　　　　　　　　　　(Node.jsで作られたアプリケーション) 
├── test　　　　　　　　　テストコード 
└── user-specific-files　OptionControlFileなど、Zephyrのアプリケーションで利用する静的ファイル 

Zephyrは大きく分けて三つのアプリケーションがある。
zephryコマンド、フロントエンドアプリケーション、サーバサイドアプリケーションで、それぞれcliディレクトリ、front-endディレクトリ、serverディレクトリにアプリケーションのソースコードがある。
Zephyrをインストールすると、zephyrコマンドが使えるようにするために、binディレクトリにcli/zephyr(JavaScriptのソースコード)へのシンボリックリンクを配置している。
インストールの際に、zephyr/binディレクトリをPATHに通すので、zephyrコマンドを実行できるようになる。(Zephyrのインストールを参照)

= 開発のワークフロー =
== CLIアプリケーション ==
　zephyrコマンドの種類を増やしたいときは、cliディレクトリにJavaScriptのソースコードを追加する。CLIアプリケーションはNode.js上で実行される。CommanderというNode.jsでコマンドを開発するためのライブラリをベースに書かれている。 
　新しくzephyrのサブコマンドを開発する場合、cliディレクトリ内にzephyr-***というファイルを作る。この新しく作ったファイルにchmodコマンドで実行権限を付与すればよい。詳しくは、[[https://github.com/tj/commander.js/ tj/commander.js]]を参照。

== サーバサイドアプリケーション ==
=== 概要 ===
　Webを通じてEosコマンドの実行をするためのアプリケーションである。全ての操作は、REST APIを通じて行う仕様となっている（一部、コンソールへの出力メッセージを通信する部分のみWeb Socketを利用している）。
[[https://github.com/expressjs/express Express]]というNode.jsのWebアプリケーションフレームワークを使って開発されている。
サーバサイドアプリケーションで開発するものは、
* APIエンドポイントの開発(REST APIのアクセスポイント)
* クラスの開発(特定の処理を行うクラスの作成や既存クラスの拡張)
の二通りがある。

=== ディレクトリ構成 ===
├── api　　各APIエンドポイントの処理が書かれたソースコード 
├── app.js　main部分 
├── class　各クラスのソースコードが置いてあるディレクトリ 
├── config.js　zephyrに関する設定が書かれたファイル 
├── express.js　expressに関する設定が書かれたファイル 
└── routes.js　　ルーティングが設定されたファイル
　　　　　　　　　　APIエンドポイントの追加などが行われている 

app.jsはExpressを使って書かれたサーバサイドアプリケーションの本体で、main関数のような部分です。各種設定ファイルの読み込み、APIエンドポイントの登録(ルーティングの追加)、クラスのインスタンス化、Webサーバの起動などが行われている。

=== APIエンドポイントの開発 ===
==== 追加 ====
　APIエンドポイントを追加するときは、既存のものにならってapiディレクトリ以下にソースコードを追加してください。
この部分には、httpメソッド(GET, POST, PUT, DELETEなど)のハンドリングを行うコードを書きます。
複雑な処理を書きたいときは、別にクラスを作成しておき、そのクラスで実行を行うようにしてください。
APIエンドポイントの処理では、httpリクエストの処理、エンドポイントでのロジックの実装(必要に応じてクラスを使う)、httpレスポンスの処理を行います。
APIの設計(どのようにエンドポイントを作るか、エンドポイントの命名など)については、[[http://www.amazon.co.jp/Web-API-The-Good-Parts/dp/4873116864 Web API: The Good Parts]]や[[http://www.amazon.co.jp/Webを支える技術-HTTP、URI、HTML、そしてREST-WEB-PRESS-plus/dp/4774142042 Webを支える技術 -HTTP、URI、HTML、そしてREST]]が参考になります。

==== テスト ====
　作成したエンドポイントは、単独でのテストが可能です。[[https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop Postman]]や[[https://addons.mozilla.org/ja/firefox/addon/restclient/ RESTClient]]などの、ブラウザの拡張機能を使うことで、任意のエンドポイントに対して、任意のhttpメソッドで実行することができます。様々なパラメータを与えたときに、意図通りのレスポンスが返ってくるかどうかテストできます。 
APIエンドポイントのテスト方法として、フロントエンドアプリケーションからアクセスしてみて試す方法があります。
ブラウザ上で動作するJavaScriptをテスト用に書き（フロントエンドアプリケーションに組み込んで）、特定のAPIエンドポイントにメソッドを実行して、Google Chromeデベロッパツール等でレスポンスを確認する、といった方法です。
これは、実際に動くアプリケーションに近いので、やりたくなる方法ではありますが、よくない方法です。
バグがあったときに、テスト用に書いたコードとAPIエンドポイントのコードのどちらにバグがあるのか判断するのが難しくなるからです。
実際に動くフロントエンドアプリケーションにテストコードを組み込むのも同様の理由でよくない方法です。
さらに、実際に動くフロントエンドのコードが汚くなる温床となるので、避けたほうがよいでしょう。
[[https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop Postman]]や[[https://addons.mozilla.org/ja/firefox/addon/restclient/ RESTClient]]のようなツールを使って、APIエンドポイントだけを独立してテストするのがオススメです。

==== APIエンドポイント一覧 ====
　2016年3月現在

=== クラスの開発 ===
==== クラスの利用 ====
　クラスを利用する.jsファイルで、requireすることでクラスを利用することができます。
requireすると、exportされたJavaScriptのオブジェクトを利用することができます。
一般的には、requireするごとにメモリが割り当てられるので、別々の参照先を指すことになるので注意が必要です。
例えば、class1.jsで書いたclass1を、api1.js、api2.js使う場合
// api1.js
var class1 = require('/path/to/class1.js');

// api2.js
var class1 = require('/path/to/class2.js');

api1.js内のclass1とapi2.js内のclass1では参照先が異なるので、それぞれ独立しています。

==== クラスの追加 ====
　クラスを追加するときは、既存のものにならってclassディレクトリ以下にソースコードを追加してください。
クラスを記述した.jsファイルの最下部では、 
module.exports = ******;
と記述することで、他のソースコードでrequireすると利用できるようになります。 

2016年3月現在、Eos、DB、WebSocketという三つのクラスでは、どのapiから呼び出すときにも同じオブジェクトを参照したいので、技巧的に同一の参照を取得できるようにしている(デザインパターンのシングルトンで調べてみてください)。

このシングルトン化の方法はNode.jsのモジュールの仕組みを利用した技巧的な方法を利用しています。
詳しくは、[[http://d.hatena.ne.jp/jovi0608/20111226/1324879536 Node.js : exports と module.exports の違い（解説編）]]や「CommonJS」、「RequireJS」、「Node.jsのモジュールシステム」等で調べてください。

==== テスト ====
下記コマンドをzephyrプロジェクトのディレクトリ内で実行することでテストコマンドを実行することができます。
テストコマンドの実行設定については、package.jsonに記述してあります。

$ npm test

テストには、[[http://mochajs.org mocha]]という、JavaScriptのテストランナーと、[[http://chaijs.com chai]]というJavaScriptのテスト用ライブラリを利用しています。テスト用のソースコードは、testディレクトリ以下にソースコードを書いてください。

プロダクションのコードでは、クラスは任意のAPIエンドポイントにリクエストがあったときに、APIエンドポイントの処理の中でrequireされ、使われます。
しかし、クラスの開発の際に、サーバを立ち上げてREST APIを叩いてみてテストするとデバッグが困難であるので、REST APIの部分とは独立させてクラスのみでテストを動かす、というフローで開発すると、効率が良くなります。。
テストコード内では、クラスをインスタンス化し、任意の引数でメソッドを実行したときに、適切な振る舞いをしているかどうかテストします。
詳細は、既存のテストコードを読んだり、「TDD」で検索してください。

==== クラス一覧 ====
　2016年3月現在

== フロントエンドアプリケーション ==
=== 言語、フレームワーク、ライブラリ ===
フロントエンドアプリケーションの開発では、便利に開発できるようにさまざまなツールを導入しています。フロントエンド開発のツールは、同じツールであってもさまざまな使い方ができることが多いので、Zephyrにおいて、それぞれのツールをどのように使っているかを記します。個々のツールがどういったものかについては、本やブログ記事を読む、既存のコードを読むなどして勉強してください。利用しているツールは以下に示します。

開発言語
* TypeScript

フレームワーク
* AngularJS

タスクランナー(C言語でいうmakeのようなもの)
* Webpack
* Gulp

==== TypeScript ====
フロントエンドアプリケーションの開発には、[[http://www.typescriptlang.org TypeScript]]という言語を利用しています。TypeScriptとは、静的型付けのないJavaScriptに静的型付けをすることができるようにした言語です。TypeScriptをコンパイルすると、コンパイラがJavaScriptのコードを生成(トランスパイル)します。JavaScriptはインタプリタなので実行時までエラーチェックできませんが、TypeScriptではコンパイラによって事前にエラーチェックをすることができます。Zephyrにおいて、TypeScriptを採用した理由は以下の通りです。
* 肥大化したアプリケーションの体系化に、TypeScriptのクラス構文を有効であるため。
* TypeScriptはJavaScriptのソースコードを生成するので、少なくともコンパイル後のコードについてはTypeScriptのバージョンアップにより仕様変更があっても、アプリケーション自体は影響を受けない。
TypeScriptの開発には以下が必要となります。
# TypeScriptのソースファイル(.ts)
# TypeScriptのコンパイラ
# TypeScriptの型定義ファイル
# コンパイラに渡すオプション or 設定ファイル
TypeScriptのコンパイラは、npmで事前にインストールしてあります(package.jsonの記述を確認してください)。TypeScriptのソースコードをコンパイル(トランスパイル)するには、コマンドに対してオプションを渡す、もしくは事前に設定ファイルを書いておき設定ファイルと同一のディレクトリでコマンドを実行する、の二通りの方法があります。Zephyrでは、/front-end/tsconfig.jsonに設定を記述しています。TypeScriptでJavaScriptのライブラリ、フレームワークを利用するためには、型定義ファイルが必要となります。有名なJavaScriptのライブラリの型定義ファイルのほとんどは、TSDというTypeScript型定義システムで取得することができます。tsdコマンドを使うことで、型定義ファイルのインストールが可能です。Zephyrでは、/front-end/typingsディレクトリに利用しているJavaScriptのライブラリ(AngularJSやその他関連ライブラリ)の型定義ファイルが置かれています。新しいライブラリを追加するときには、/front-endディレクトリでtsdコマンドを使ってインストールしてください。

==== AngularJS ====
　JavaScriptのフレームワーク、[[https://angularjs.org AngularJS]]を使って開発しています。AngularJSは学習コストが大きいですが、既存のソースコードを読む、書籍やブログを読むなどして勉強してください。Zephyrでは、TypeScriptとAngularJSを使って開発しているので、AngularJSのソース、TypeScriptで使うAngularJSの型定義ファイルがそれぞれnpmとtsdでインストールしています。

　AngularJSはバージョン1系と2系がありますが、Zephyrでは1系を利用しています。また、AngularJSの概念で「$scope」というものがありますが、バージョン1.4以降では「$scope」を使わず「bindToController」を使うことが推奨されています。Zephyrでは、「$scope」を使わずに、「bindToController」を利用しているので注意してください。

==== タスクランナーについて ====
　タスクランナーのWebpack、Gulp.jsで書かれたワークフローは、バグがなければ、既存のコードを書き直さずに、コマンドを叩くだけで継続して利用できると思います。GulpやWebpackは、開発時に発生するさまざまなマニュアル操作(コマンドを叩いてコンパイルする、コンパイルしたコードを任意のディレクトリにコピーする、など)を自動化するのに利用しています。

==== Webpack ====
　[[http://webpack.github.io Webpack]]は、モジュール化を支援するツールです。/front-end/webpack.config.jsにWebpackの設定を記述しています。Zephyrの開発において、Webpackを使って自動化しているのは以下の処理です。
# TypeScriptで書かれたソースコードをJavaScriptにコンパイル(=トランスパイル)する。
# トランスパイルされたJavaScriptのコードを一つのファイルに結合し、bundle.jsに書き出す。

==== Gulpの利用 ====
　[[http://gulpjs.com Gulp]]は、フロントエンドの開発でよく利用されるタスクランナーです。Webpackのみでタスクを記述することもできますが、簡潔に書くことのできるGulpに慣れている、Gulpみので、モジュール管理やTypeScriptのトランスパイルを記述すると面倒、という理由でGulpとWebpackを併用しています。/front-end/gulpfile.jsにGulpの設定を記述しています。Zephyrの開発において、Gulpを使って自動化しているのは以下の処理です。
# TypeScriptのソースコードのトランスパイル(Webpackを利用したタスク)
# htmlファイルをdistディレクトリにコピー
# .sassファイルを.cssファイルにコンパイルし、distディレクトリにコピー
# templateディレクトリにある全てのtemplateファイルをdistディレクトリにコピー
# 1~4のソースコードの変更監視
# デフォルトタスク(= 1~5のタスクを依存関係に考慮し順番に実行する)
　

= ドキュメントAPI =

= 参考にしたWebサイト =
== AngularJS と TypeScript ==
* [http://tech.recruit-mp.co.jp/front-end/post-7730/ 【AngularJS x TypeScript デザインパターン】 Controller と Routing 篇 - AngularJS + TypeScript ＃4]
* [http://qiita.com/armorik83/items/0778d757c46e953f3fdf TypeScriptで書くAngularJSのMVC]
* [http://stackoverflow.com/questions/27803691/how-to-use-angular-ui-bootstrap-modals-in-typescript How to use angular-ui-bootstrap (modals) in typescript?]

== AngularJS ==
* [http://qiita.com/advent-calendar/2015/angularjs AngularJS Advent Calendar 2015]
* [http://qiita.com/armorik83/items/8e1f8003d4be8bb8555e ng-repeatでのフィルタをフックする]
* [http://qiita.com/armorik83/items/5542daed0c408cb9f605 AngularJSモダンプラクティス]

== Webpack ==
* [http://thujikun.github.io/blog/2014/12/07/webpack/ Webpackを使い倒す]
* [http://ameblo.jp/ca-1pixel/entry-11884453208.html RequireJS等はもう古い。WebPackとは？]
* [http://liginc.co.jp/web/js/other-js/148813 WebPackを使ってJavaScriptを効率的に書くチュートリアル【入門編】]

== AngularJS と Webpack ==
* [http://angular-tips.com/blog/2015/06/using-angular-1-dot-x-with-es6-and-webpack/ Using Angular 1.x With ES6 and Webpack]

== TypeScriptとWebpack ==
* [http://www.jbrantly.com/typescript-and-webpack/ TypeScript and webpack]

== TypeScript ==
* [https://html5experts.jp/vvakame/17004/ TypeScript の開発環境構築と周辺ツールの紹介]

= 問題点 =
* UIの機能のコンポーネント化できてない
* メインページのcontrollerにベタ書きしているので、密結合になっている。
* 機能追加や修正に時間を要してしまう。
* ライブラリの管理
* パッケージ管理システムによる管理を整えられていない。
* ユーザに配布する際に、自動で環境を整えることができない。
* 機能追加の際のプロセス・ワークフローを構築できていない。
* 今は自分以外の人が開発しようとすると、ソースを全部読まないといけない。
* 各機能を疎結合にする+開発プロセス決めることで、自分の開発も効率化できる。
* APIドキュメントがない
* JSDoc等を使ってドキュメントが生成されるようにすべき。
* JSDocでドキュメントが作れるように設計することで、システムの見通しもよくなるはず。

== 解決策のアイデア ==
* AngularJSのCommonJS?的な使い方探す(Browserify, Bowerを使う)
* ディレクティブを細かく作る。特に、コマンド実行の部分。
* ページ遷移の際の、REST APIの呼び出しはresolveに押し込む。

Zephyr

Zephyr

2016-03-22T11:19:24Z

Fumifumi: /* ディレクトリ構成 */

Zephyr

2016-03-22T11:13:31Z

Fumifumi: /* ディレクトリ構成 */