v0.21

コントローラ

はじめに

コントローラはリクエスト処理ロジックを集約されたクラスに整理します。dframeworkはルートが一致した際に適切なコントローラクラスを自動的に検出してインスタンス化します。開発者が手動でコントローラをインスタンス化する必要はありません。

コントローラの記述

コントローラはデフォルトエクスポートを持つクラスです。各メソッドはルートアクションに対応します。すべてのメソッドはasyncである必要があります。

1// controllers/app/IndexController.js
2export default class IndexController {
3 async index() {
4 return render('auth.index');
5 }
6
7 async register() {
8 return render('auth.register');
9 }
10}

cliを使用してコントローラのスタブを生成できます。

1dstrn make:controller app/IndexController

ディレクトリ構造と命名規則

コントローラはcontrollersディレクトリ内に配置されサブディレクトリに整理できます。サブディレクトリとクラス名はルート定義文字列に直接反映されます。

controllers/app/HomeController.jsにあるコントローラはapp.HomeController@methodとして参照されます。controllers/auth/AuthController.jsにあるコントローラはauth.AuthController@methodとして参照されます。ルート直下のcontrollers/LocaleController.jsにあるコントローラはLocaleController@methodとして参照されます。

1Route.get('/home', 'app.HomeController@home');
2Route.post('/register', 'auth.AuthController@register');
3Route.get('/locale/:locale', 'LocaleController@set');

省略可能な引数

コントローラメソッドは引数としてreqとresを受け取ります。どちらも省略可能です。メソッドが実際に使用するもののみを宣言します。メソッドがリクエストをまったく必要としない場合は完全に省略できます。

1export default class IndexController {
2 async index() {
3 return render('auth.index');
4 }
5
6 async user(req) {
7 const targetUser = await User.find(req.params.id);
8 return render('app.user.profile', { targetUser });
9 }
10}

レスポンスの返却

コントローラはフレームワークが公開するグローバルヘルパーを使用してレスポンスを返します。レスポンスオブジェクトのメソッドを直接呼び出すことはありません。

1export default class PreferencesController {
2 async index() {
3 const preferences = await UserPreference.getAllForUser(Auth.user().id);
4 return json({ success: true, preferences });
5 }
6
7 async update(req) {
8 await UserPreference.setForUser(Auth.user().id, req.params.key, req.body.value);
9 return json({ success: true });
10 }
11
12 async destroy() {
13 return status(500).json({ success: false, message: 'failed to reset preference' });
14 }
15}

利用可能なレスポンスヘルパーはrender()、json()、redirect()、back()、abort()、status()、cookie()、stream()です。コントローラメソッドは常にこれらのヘルパーのいずれかを返す必要があります。レスポンスヘルパーのみがステータスコード、コンテンツタイプ、ビューのコンパイルを管理するため素のモデルインスタンスやプレーンオブジェクトを直接返さないでください。

NOTE

手動で`status()`を設定するよりも通常は`abort(statusCode, message)`ヘルパーを使用することが推奨されます。`abort()`はコンテキストを認識します。リクエストがajax経由で行われた場合はjsonエラーペイロードを自動的に返します。標準的なブラウザリクエストの場合は適切なhtmlエラーページ(404や500など)をレンダリングします。

1export default class UserController {
2 async show(req) {
3 const user = await User.find(req.params.id);
4 if (!user) {
5 // aborts with a 404, returning json for ajax requests or a 404 view for standard requests
6 return abort(404, 'user not found');
7 }
8 return render('app.user.profile', { user });
9 }
10}
IMPORTANT

`redirect(url, code = 302, force = false)`ヘルパーはオープンリダイレクト脆弱性に対して厳格に保護されています。クロスオリジンやプロトコル相対urlへのリダイレクトを拒否し代わりにエラーをスローします(ローカル開発環境を除く)。さらにspaも認識します。リクエストがdSPAルーターからのものである場合標準の302ヘッダーの代わりにjson命令を返します。`force`ブール値を`true`に設定するとクライアント側でspaルーターに強制的なハードリロードを実行させます。

1export default class AuthController {
2 async logout(req) {
3 await Auth.logout();
4 // safely redirects to the home page, instructing the spa router to handle it
5 return redirect('/home');
6 }
7}

リクエストへのアクセス

ルートパラメータ

ルート定義で:がプレフィックスとして付けられたurlセグメントは抽出されreq.paramsで利用できます。

1export default class IndexController {
2 async user(req) {
3 const targetUser = await User.find(req.params.id);
4 return render('app.user.profile', { targetUser });
5 }
6}

クエリ文字列

クエリ文字列の値はプレーンオブジェクトとしてreq.queryで利用できます。フレームワークは初回アクセス時にクエリ文字列を遅延解析します。

1export default class SearchController {
2 async index(req) {
3 const { q, sort } = req.query;
4 const results = await Track.where('title', q).get();
5 return json({ results });
6 }
7}

リクエストボディ

解析されたリクエストボディはreq.bodyで利用できます。フレームワークはコントローラメソッドが呼び出される前に更新系リクエストのjsonおよびフォームエンコードされたボディを自動的に解析します。

1export default class PreferencesController {
2 async update(req) {
3 const { key } = req.params;
4 const { value } = req.body;
5 await UserPreference.setForUser(Auth.user().id, key, value);
6 return json({ success: true, key, value });
7 }
8}

ファイルアップロード

リクエストがmultipart/form-dataとして送信された場合フレームワークはファイルを解析してreq.filesで利用可能にします。req.filesの各キーはファイルオブジェクトの配列です。またreq.file(key)を使用して最初のファイルを直接取得したりreq.hasFile(key)を使用してファイルがアップロードされたかを確認したりすることもできます。

1import { Storage } from 'dframework';
2
3export default class UserProfileController {
4 async updateProfileImage(req) {
5 if (!req.hasFile('profileImage')) {
6 return status(422).json({ error: 'no image provided' });
7 }
8 const image = req.file('profileImage');
9 const path = await Storage.disk('public').put(`user_assets/${Auth.user().id}/${image.originalFilename}`, image);
10 return json({ success: true, path });
11 }
12}

クッキー

受信したクッキーはプレーンオブジェクトとしてreq.cookiesで利用できます。フレームワークは初回アクセス時にcookieヘッダーを遅延解析します。

1export default class LocaleController {
2 async set(req) {
3 const preferred = req.cookies.locale;
4 return json({ preferred });
5 }
6}

ページネーション

dframeworkはクエリ文字列パラメータからアクティブなページ番号を自動的に読み取ります。任意のモデルクエリで.paginate()を呼び出すとリクエストコンテキストから現在のページを解決しPaginatorインスタンスを返します:

1export default class AdminController {
2 async list() {
3 const users = await User.where('active', 1).paginate(20);
4 return json(users);
5 }
6}

json(users)経由で返されるとペジネーターはレコードとページネーションメタデータの両方を含むクリーンなレスポンスにシリアライズされます。

Paginatorインスタンスはsnake_caseとcamelCaseの両方でのプロパティアクセス、ループ内での直接反復、およびヘルパーメソッドをサポートしています:

同一ページ上で複数の異なるコレクションをページネーションするにはカスタムページパラメータ名を指定します:

1const users = await User.paginate(10, 'user_page');
2const logs = await AuditLog.paginate(10, 'log_page');

バリデーション

グローバルなvalidate()ヘルパーは任意のコントローラメソッド内で利用可能です。ファイルアップロードを検証する場合はリクエストボディオブジェクトまたは完全なreqオブジェクトのいずれかを渡します。利用可能なルールの完全な一覧についてはバリデーションドキュメントを参照してください。

1export default class UserProfileController {
2 async updateUsername(req) {
3 const validation = validate(req.body, {
4 username: 'required|string|min:3|max:20'
5 });
6
7 if (validation.fails()) {
8 return status(422).json({ success: false, errors: validation.errors() });
9 }
10
11 // proceed with update
12 }
13
14 async updateProfileImage(req) {
15 const validation = validate(req, {
16 profileImage: 'file_required|file_size:8mb|file_max_count:1'
17 });
18
19 if (validation.fails()) {
20 return status(422).json({ success: false, errors: validation.errors() });
21 }
22
23 // proceed with upload
24 }
25}

モデルとサービスの使用

コントローラは通常ファイルの先頭でモデルとサービスをインポートします。フレームワークはlocal環境でコントローラをホットリロードするためこれらのインポートはファイル変更ごとに再評価されます。

1import Track from '../../models/Track.js';
2import User from '../../models/User.js';
3
4export default class HomeController {
5 async home(req) {
6 const leaderboard = await User.orderBy('current_rank', 'ASC').limit(5).get();
7 const popularTracks = await Track.where('is_popular', 1).limit(5).get();
8
9 return render('app.home.index', { leaderboard, popularTracks });
10 }
11}

プライベートメソッド

コントローラはプレーンなクラスであるためルートハンドラーと並んで非asyncのヘルパーメソッドを定義できます。フレームワークはルート定義に一致するメソッドのみを呼び出します。クラス上のその他のメソッドは開発者のロジック専用のプライベートなものとなります。

1export default class PreferencesController {
2 async update(req) {
3 const validation = this.validatePreference(req.params.key, req.body.value);
4 if (validation.fails()) {
5 return status(422).json({ success: false, errors: validation.errors() });
6 }
7 await UserPreference.setForUser(Auth.user().id, req.params.key, req.body.value);
8 return json({ success: true });
9 }
10
11 validatePreference(key, value) {
12 return validate({ value }, { value: this.getValidationRules(key) });
13 }
14
15 getValidationRules(key) {
16 const rules = {
17 'audio.normalize_volume': 'boolean',
18 'display.fps_counter': 'boolean',
19 };
20 return rules[key] || 'required';
21 }
22}

ホットリロード

local環境ではフレームワークはファイル変更を検知するためにcontrollersディレクトリを監視します。コントローラファイルを保存するとフレームワークはサーバーを再起動することなく次のリクエスト時にそれを自動的に再インポートします。この動作を有効にするために特別な設定を行う必要はありません。