プロジェクト開発のベスト・プラクティス(Part2)
Jul 29, 2017 · 8 min read
前回の続きになります。
また、前のページでは
- Git Workflow
- Git commit message
- Documentation
- Environments
- Testing
について、まとめています。
今回は以下の内容を見ていきます。
- Structure and Naming as to folder
- Code style
- Logging
- Api
- Licensing
Structure and Naming
- 役割ではなく、機能/ページ/コンポーネントをそれぞれがまとまって、ファイルの整理がされている。また、テストファイルが実装したコードファイルの横に置いてある。
→テストを含んだ機能ごとのモジュールをまとめていると、navigationが楽になります。 - 追加のテストファイルを別のテストフォルダに入れる。
- ./configフォルダを使用し、異なる環境に異なる設定ファイルを作成しない
→設定ファイルを別の目的(データベース、APIなど)に分解したとき、configのような非常に分かりやすい名前のフォルダに置くことは理にかなったものになります - スクリプトを./scriptsフォルダに入れてください。これには、bashスクリプトとノードスクリプトが含まれます。
→2つ以上のスクリプト、プロダクションビルド、開発ビルド、データベースフィーダ、データベース同期などなど、省略したスクリプトの有用性は多岐にわたります。 - ビルド出力を./buildフォルダに置きます。 .gitignoreにbuild /を追加します。
- ファイル名とディレクトリ名にはPascalCase ‘’ camelCaseを使用してください。 PascalCaseはコンポーネント名に対してのみ使用します。
- 理想的には、ディレクトリ名は、index.jsのデフォルトエクスポートの名前と一致する必要があります。
Code style
- 新しいprojectには、現代的な構文のJSをしようする。
→transpilerを使って新しい文法を変換することができる - build processにコードスタイルのチェックを含みます。
→ビルドを中断することは、コードにコードスタイルを適用する1つの方法です。client/server側、両方にスタイルの適用を行います。 - ESLintを使用します。
特におすすめなのが、AirBnBスタイルのスタイルガイドです。 - ESLintでは、flow typeのスタイルチェックを使用します。
- .eslintignoreファイルを作ります
- pull requestを行う前に、eslintのdisable commentを取り除きます。
- タスクのサイズに応じて、// TODO:コメントを使用するか、チケットを開きます。
→小さなタスク(関数のリファクタリングやコメントの更新など)について自分や他の人に思い出させることができます。大規模なタスクの場合は、lintルールで強制される// TODO(#3456)を使用し、番号をオープンチケットにします。 - 関数名は、動詞または動詞句であり、その意図を伝える必要があります。
→ソースコードを読むのが自然になります。
ステップダウンルールに従って、関数をファイルに整理します。
Logging
- クライアント側でのログをproductionに使うのを避ける。
→コードスタイルで、console.log()があったらwarningを投げる用に設定します。 - 読みやすいloggngを作ります。理想的には、productionで使用するlogging libraryを使用します
→winston node-bunyanなど
API
- RESTFUL InterfaceのAPIを作ることは、チームメンバーとクライアントが簡単に、また一貫したAPI使用につながります。
- 主には、リソース思考設計に従います。リソースは、resource, collection, and URL
- resource
→recourceはデータをもち、nest構造を持って、methodsでデータを暑かったものです。 - collection
→resourceが集まったもの - URL
→resource or collectionのオンライン上のURL - URLにはkebab-caseを使用します。
クエリ文字列またはリソースフィールドのパラメータにcamelCaseを使用します。
URLのリソース名には複数のkebab-caseを使用します。
コレクションを指すURLには、複数形の名詞を使用します。 - URLは常にcollectionで始まり、識別子で終わります
/students/245743
/airports/kjfk- URlに動詞を使うことは避け、名詞を使う
- response typeはたいていjson形式なのでcamelCaseに従って、プロパティ名をつける
CRUD機能はHTTP methodを使用して説明する
- GET resourceのrepresentaionをとってくる
- POST 新しいresourcesをつくる
- PUT 既存のresourceを更新
- PATCH 新しく供給された部分のresourceのみを更新
- DELETE 既存のresourceを削除
response message must be self-descriptive
レスポンスデータは、それを見ただけで説明がわかるようなものが望ましいものになります。
{
"code": 1234,
"message" : "Something bad happened",
"description" : "More details"
}//add error message
{
"code" : 2314,
"message" : "Validation Failed",
"errors" : [
{
"code" : 1233,
"field" : "email",
"message" : "Invalid email"
},
{
"code" : 1234,
"field" : "password",
"message" : "No password provided"
}
]
}
注:セキュリティ例外メッセージは可能な限り一般的なものにしておいてください。
たとえば、「不正なパスワード」と言うのではなく、「無効なユーザー名またはパスワード」と返信することで、ユーザー名が正しく、パスワードのみが間違っていることをユーザーに知らせないようにできます。
またreponse statusを次の8つで表します。
- 200 ok応答はGET/PUT/POST要求が成功
- 201 POSTメソッドを使用して新しいインスタンスが作成されると、201が返される
- 304 変更されていない。この場合、受信者が既にキャッシュされたrepresentationをもっていたとき
- 400 要求が処理されていない。サーバーがクライアントの要求内容を理解できない時
- 401 要求に必要な資格情報などが不足していて、再要求が必要な、許可されない時
- 403 サーバーがその要求を承認しない時
- 404 Not Found 要求されたリソースが見つからない時
- 500 内部サーバーエラー。要求は通るが、サーバー側が予期しない状況によって実行が出来ないとき
ほとんどのAPIプロバイダは、小さなサブセットのHTTPステータスコードを使用されています。
- responseのtotal numberを返します。
limitoffsetパラメーターの使用を許可します
→データ量の制限は、userの利便性を増します。- ページ作成、フィルタリング、および並べ替えは、すべてのリソースに対して最初からサポートする必要はありません。フィルタリングとソートを提供するリソースを文書化します。
以下は基本的なセキュリティのベスト・プラクティスです。
- URL: Get/user/12?id=等の基本認証を使わない
→トークンはクリアテキストでそのまま渡されるので、安全性0になります。
トークンは、すべてのリクエストでAuthorizationヘッダーを使用して送信する必要があります。 - Authorizationは短時間だけ有効なものにします。
HTTPのリクエストをTLS無しで行うものには、403を返します。 - Rate limitingを導入する
→過度な要求回数を制限します - HTTPヘッダーを適切に設定すると、Webアプリケーションをロックして保護するのに役立ちます。
- ReST APIで交換されるすべてのデータは、APIによって検証されなければなりません。
- JSONをシリアル化する。
→適切なJSONシリアライザを使用して、ユーザーが入力したデータを適切にエンコードして、ブラウザ上でユーザーが入力したものが実行されるのを防ぐことが不可欠です。 - コンテントタイプを検証して、大概はapplication/*jsonを使用する。
- API Referenceを READMEに加える。
- コードサンプルを用いてAPIのAuthenticationを記述する。
- URLの構造、request typeを説明します。
Licensing
- 使用する権利を持つリソースを使用していることを確認します。
- ライブラリを使用する場合は、MIT、Apache、BSDのいずれかを探すのを忘れないでください。
- ただし、それらを変更した場合は、ライセンスの詳細を調べてください。
- 著作権で保護されている画像や動画の使用は、法的な問題を引き起こします。
参考リンク
- flow
flow(type-checker)のインストール - どんな時にtype-checkをJSに導入すればいいのか
- swagger API blueprint
API設計のツール
