「Zephyr」の版間の差分

提供: Eospedia
移動: 案内検索
(開発のワークフロー)
(サーバサイドアプリケーション)
行85: 行85:
 
[[https://github.com/expressjs/express Express]]というNode.jsのWebアプリケーションフレームワークを使って開発されている。
 
[[https://github.com/expressjs/express Express]]というNode.jsのWebアプリケーションフレームワークを使って開発されている。
 
サーバサイドアプリケーションで開発するものは、
 
サーバサイドアプリケーションで開発するものは、
* APIエンドポイント(REST APIのアクセスポイント)
+
* APIエンドポイントの開発(REST APIのアクセスポイント)
* 特定の処理を行うクラスの作成や既存クラスの拡張
+
* クラスの開発(特定の処理を行うクラスの作成や既存クラスの拡張)
 
の二通りがある。
 
の二通りがある。
  
行100: 行100:
 
app.jsはExpressを使って書かれたサーバサイドアプリケーションの本体で、main関数のような部分です。各種設定ファイルの読み込み、APIエンドポイントの登録(ルーティングの追加)、クラスのインスタンス化、Webサーバの起動などが行われている。
 
app.jsはExpressを使って書かれたサーバサイドアプリケーションの本体で、main関数のような部分です。各種設定ファイルの読み込み、APIエンドポイントの登録(ルーティングの追加)、クラスのインスタンス化、Webサーバの起動などが行われている。
  
=== APIエンドポイントの追加 ===
+
=== APIエンドポイントの開発 ===
 +
==== 追加 ====
 
 APIエンドポイントを追加するときは、既存のものにならってapiディレクトリ以下にソースコードを追加してください。
 
 APIエンドポイントを追加するときは、既存のものにならってapiディレクトリ以下にソースコードを追加してください。
 
この部分には、httpメソッド(GET, POST, PUT, DELETEなど)のハンドリングを行うコードを書きます。
 
この部分には、httpメソッド(GET, POST, PUT, DELETEなど)のハンドリングを行うコードを書きます。
行117: 行118:
 
[[https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop Postman]]や[[https://addons.mozilla.org/ja/firefox/addon/restclient/ RESTClient]]のようなツールを使って、APIエンドポイントだけを独立してテストするのがオススメです。
 
[[https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop Postman]]や[[https://addons.mozilla.org/ja/firefox/addon/restclient/ RESTClient]]のようなツールを使って、APIエンドポイントだけを独立してテストするのがオススメです。
  
=== APIエンドポイント一覧 ====
+
==== APIエンドポイント一覧 ====
 2016/3/23現在
+
 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ファイルの最下部では、<br />
 +
module.exports = ******;
 +
と記述することで、他のソースコードでrequireすると利用できるようになります。<br />
 +
 
 +
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のモジュールシステム」等で調べてください。
 +
 
 +
==== テスト ====
 +
 
 +
==== クラス一覧 ====
 +
 2016年3月現在
  
 
== フロントエンドアプリケーション ===
 
== フロントエンドアプリケーション ===

2016年3月27日 (日) 16:38時点における版

概要

 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コマンドで実行権限を付与すればよい。詳しくは、[tj/commander.js]を参照。

サーバサイドアプリケーション

概要

 Webを通じてEosコマンドの実行をするためのアプリケーションである。全ての操作は、REST APIを通じて行う仕様となっている(一部、コンソールへの出力メッセージを通信する部分のみWeb Socketを利用している)。 [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の設計(どのようにエンドポイントを作るか、エンドポイントの命名など)については、[Web API: The Good Parts]や[Webを支える技術 -HTTP、URI、HTML、そしてREST]が参考になります。

テスト

 作成したエンドポイントは、単独でのテストが可能です。[Postman]や[RESTClient]などの、ブラウザの拡張機能を使うことで、任意のエンドポイントに対して、任意のhttpメソッドで実行することができます。様々なパラメータを与えたときに、意図通りのレスポンスが返ってくるかどうかテストできます。
APIエンドポイントのテスト方法として、フロントエンドアプリケーションからアクセスしてみて試す方法があります。 ブラウザ上で動作するJavaScriptをテスト用に書き(フロントエンドアプリケーションに組み込んで)、特定のAPIエンドポイントにメソッドを実行して、Google Chromeデベロッパツール等でレスポンスを確認する、といった方法です。 これは、実際に動くアプリケーションに近いので、やりたくなる方法ではありますが、よくない方法です。 バグがあったときに、テスト用に書いたコードとAPIエンドポイントのコードのどちらにバグがあるのか判断するのが難しくなるからです。 実際に動くフロントエンドアプリケーションにテストコードを組み込むのも同様の理由でよくない方法です。 さらに、実際に動くフロントエンドのコードが汚くなる温床となるので、避けたほうがよいでしょう。 [Postman]や[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のモジュールの仕組みを利用した技巧的な方法を利用しています。 詳しくは、[Node.js : exports と module.exports の違い(解説編)]や「CommonJS」、「RequireJS」、「Node.jsのモジュールシステム」等で調べてください。

テスト

 

クラス一覧

 2016年3月現在

フロントエンドアプリケーション =

=

ドキュメントAPI

参考にしたWebサイト

AngularJS と TypeScript

AngularJS

Webpack

AngularJS と Webpack

TypeScriptとWebpack

TypeScript

問題点

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

解決策のアイデア

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