v0.21

ルーティング

はじめに

ルートはroutesディレクトリ内で定義します。dframeworkは手動でのインポートを必要とせず起動時にそのディレクトリ内のすべての.jsファイルを自動的に検出して読み込みます。各ルートファイル内では内部ルーターインスタンスへ直接プロキシするグローバルなRouteファサードを利用できます。

基本的なルート

最もシンプルなルートはurlパスと処理を担当するメソッドを指すコントローラ文字列を受け取ります。

1// routes/web.js
2Route.get('/dashboard', 'app.IndexController@dashboard');
3Route.post('/register', 'auth.AuthController@register');
4Route.put('/profile', 'app.UserProfileController@update');
5Route.patch('/profile/avatar', 'app.UserProfileController@updateAvatar');
6Route.delete('/session', 'auth.AuthController@logout');

利用可能なメソッド

ルーターは標準的なhttp動詞をサポートしています。

1Route.get(path, handler);
2Route.post(path, handler);
3Route.put(path, handler);
4Route.patch(path, handler);
5Route.delete(path, handler);
6Route.head(path, handler);

ルートパラメータ

動的なurlセグメントには先頭にコロンを付与します。ルーターはこれらの値を抽出およびデコードしコントローラ内のreq.paramsで利用できるようにします。

1Route.get('/user/:id', 'app.IndexController@user');
2Route.get('/admin/:entity/:id/edit', 'admin.AdminController@editForm');
1// controllers/app/IndexController.js
2export default class IndexController {
3 async user(req) {
4 const user = await User.find(req.params.id);
5 return json({ user });
6 }
7}

パラメータの制約

ルート定義で.where()メソッドを使用してルートパラメータの形式を制約できます。.where()メソッドはパラメータ名と正規表現パターン文字列、数値、または制約オブジェクトを受け取ります。数値の制約は完全一致の正規表現へと自動的にコンパイルされます:

1Route.get('/user/:id', 'app.IndexController@user').where('id', '[0-9]+');
2Route.get('/user/:name', 'app.IndexController@show').where('name', '[a-zA-Z]+');
3
4// 数値は完全一致の正規表現にコンパイルされます
5Route.get('/special/:id', 'app.IndexController@special').where('id', 42);
6
7// 複数パラメータのオブジェクト構文
8Route.get('/posts/:year/:slug', 'app.PostController@show').where({
9 year: '^[0-9]{4}$',
10 slug: '^[a-z0-9-]+$'
11});

名前付きルート

ルート定義の後に.name()をチェーンすることでルートに名前を付けます。名前付きルートを使用するとパスをハードコードすることなくプログラム上でurlを生成できます。

1Route.get('/dashboard', 'app.IndexController@dashboard').name('dashboard');
2Route.get('/user/:id', 'app.IndexController@user').name('app.user.profile');

名前付きルートからurlを生成するにはグローバルなroute()ヘルパーを使用します。

1const dashboardUrl = route('dashboard');
2const profileUrl = route('app.user.profile', { id: 42 });

ルートグループ

グループを使用すると個別の定義で繰り返すことなく複数のルート間でプレフィックスやミドルウェアなどの属性を共有できます。

プレフィックス

1Route.group({ prefix: '/faq' }, (faq) => {
2 faq.get('/', 'app.IndexController@faq').name('app.faq');
3 faq.get('/tos', 'app.IndexController@faq_tos').name('app.faq.tos');
4 faq.get('/privacy', 'app.IndexController@faq_privacy').name('app.faq.privacy');
5});

ミドルウェア

1Route.group({ middleware: ['AuthMiddleware@requireAuth'] }, (auth) => {
2 auth.get('/home', 'app.HomeController@home').name('app.home');
3 auth.get('/library', 'app.IndexController@library').name('app.library');
4});

複合属性

プレフィックス、ミドルウェア、shield、csrfオプションは単一のグループ定義内でまとめて設定できます。

1Route.group({
2 prefix: '/admin',
3 middleware: ['AuthMiddleware@requireAuth', 'AdminMiddleware@requireAdmin'],
4 shield: true,
5 csrf: true
6}, (admin) => {
7 admin.get('/', 'admin.AdminController@index').name('admin.index');
8 admin.get('/:entity', 'admin.AdminController@list').name('admin.list');
9 admin.post('/:entity', 'admin.AdminController@store').name('admin.store');
10});

シールドとcsrfのグループ単位での無効化

webhookエンドポイント、公開api、またはサードパーティからのコールバック用にはグループ内のすべてのルートでshieldおよびcsrf検証を無効化できます:

1Route.group({ prefix: '/webhooks', csrf: false, shield: false }, (hooks) => {
2 hooks.post('/stripe', 'StripeController@handle');
3 hooks.post('/github', 'GitHubController@handle');
4});

流暢なチェーン可能ビルダーを使用することもできます:

1Route.prefix('/webhooks')
2 .shield(false)
3 .csrf(false)
4 .group((hooks) => {
5 hooks.post('/stripe', 'StripeController@handle');
6 });

グループはネスト可能です。内側のグループは親からshieldおよびcsrfの設定を継承し必要に応じて明示的に上書きできます。

1Route.group({ middleware: ['AuthMiddleware@requireAuth'] }, (auth) => {
2 auth.group({ prefix: '/api/preferences' }, (prefs) => {
3 prefs.get('/', 'app.PreferencesController@index').name('api.preferences.index');
4 prefs.put('/:key', 'app.PreferencesController@update').name('api.preferences.update');
5 });
6});

ミドルウェアの実行順序

ルートが1つ以上のグループ内に存在する場合実行時のミドルウェアスタックは外側グループのミドルウェア, 内側グループのミドルウェア, ルートレベルのミドルウェア, コントローラとなります。グループミドルウェアは登録時に宣言順でルート自身のハンドラーチェーンの先頭に追加されるためネストされたグループは自身のミドルウェアより前に親のミドルウェアを実行します。

1Route.group({ middleware: [a] }, (g1) => {
2 g1.group({ middleware: [b] }, (g2) => {
3 g2.middleware(c).get('/path', 'Ctrl@index');
4 });
5});
6// runtime stack for GET /path: [a, b, c, Ctrl@index]

next()を呼び出さずにレスポンスを返すミドルウェア(リクエストを拒否する組み込みのRateLimiterなど)はチェーンの後続処理をショートサーキットします。コントローラは実行されず後続のミドルウェアも一切実行されません。これはグループとその内部のルートの両方にRateLimiterを適用する場合に特に重要です。2つのリミッターは協調動作しません。それぞれが独自のウィンドウとカウントを追跡し先に上限に達した方が優先されます。また両方の層で同一のRateLimiterインスタンスを再利用するとリクエストごとの加算が2倍になります(そのため実質的な制限値はmax / 2となります)。詳細な連携モデルについてはセキュリティドキュメントのレイヤードレートリミッターセクションを参照してください。

ドメインとポートによるルーティング

dframeworkはドメイン別およびポート別のルート登録をサポートしています。グループ属性またはチェーン可能なビルダーメソッドのいずれかを使用して特定のホスト、サブドメイン、ポートにルートを制限できます。

ドメインルーティング

特定のホストまたはサブドメインにルートを制限するにはRoute.group()にdomainオプションを渡すかRoute.domain()を呼び出します。

1Route.group({ domain: 'admin.example.com' }, (admin) => {
2 admin.get('/dashboard', 'admin.AdminController@index').name('admin.dashboard');
3});
4
5Route.domain('api.example.com', (api) => {
6 api.get('/v1/users', 'api.UserController@index').name('api.users');
7});

ポートルーティング

portオプションまたはRoute.port()を使用して特定のリスニングポートにルートを制約することもできます。ポートの一致判定はhostヘッダーまたはローカルサーバーソケットポートをチェックします。

1Route.group({ port: 8080 }, (metrics) => {
2 metrics.get('/health', 'app.HealthController@check');
3});
4
5Route.port(9090, (internal) => {
6 internal.get('/metrics', 'app.MetricsController@export');
7});

チェーン可能なビルダー

.domain()、.port()、.basicAuth()、.middleware()は完全にチェーン可能なビルダーでありエンドポイントやグループを登録する前に任意の順序で構成できます。

1Route.domain('shop.example.com').get('/cart', 'shop.CartController@index');
2
3Route.basicAuth('admin', 'secret')
4 .port(8080)
5 .get('/metrics', 'app.MetricsController@export');
6
7Route.domain('secure.example.com')
8 .port(8443)
9 .middleware('AuthMiddleware@requireAuth')
10 .get('/data', 'app.DataController@show');
11
12Route.domain('admin.example.com')
13 .port(8080)
14 .group({ prefix: '/v1' }, (v1) => {
15 v1.get('/users', 'admin.UserController@index');
16 });

パラメータ付きドメイン

ドメイン定義は:paramまたは{param}の構文を使用した動的パラメータプレースホルダーをサポートします。抽出されたドメインパラメータはパスパラメータとともにreq.paramsで自動的に利用可能になります。

1Route.domain(':subdomain.example.com', (tenant) => {
2 tenant.get('/users/:id', 'app.TenantController@showUser');
3});
4
5Route.domain('{tenant}.myapp.com', (app) => {
6 app.get('/settings', 'app.SettingsController@show');
7});
1// GET http://acme.example.com/users/42
2// req.params.subdomain === 'acme'
3// req.params.id === '42'

複数ドメイン間でのルート名の重複

WARNING

`.name()`で登録されたルート名はグローバルルックアップテーブルに保持されます。異なるドメイン上の2つのルートがまったく同一の名前を共有している場合後からの定義が以前のエントリを上書きします。常にルート名に対象ドメインまたはセクション名をプレフィックスとして付与してください(例: `admin.dashboard`や`app.dashboard`)。

1Route.domain('admin.example.com').get('/dashboard', 'AdminController@dash').name('admin.dashboard');
2Route.domain('app.example.com').get('/dashboard', 'AppController@dash').name('app.dashboard');
3
4// route('admin.dashboard') // '//admin.example.com/dashboard'
5// route('app.dashboard') // '//app.example.com/dashboard'

route(name, params)を使用してドメインバインドされたルートのurlを生成する場合フレームワークは提供されたparamsオブジェクトから任意のドメインパラメータを埋め込みプロトコル相対絶対url(//admin.example.com/dashboardなど)を自動的に返します。

インラインミドルウェアチェーン

単一のコントローラ文字列の代わりにハンドラーとして配列を渡すことができます。フレームワークは最後の要素より前のすべてのエントリをミドルウェアとして扱い最後の要素をコントローラとして処理します。

1Route.post('/approve', ['AuthMiddleware@requireAuth', 'auth.AuthController@approvePost']).name('approve.post');

グループを使用せずにルート定義の前または後に.middleware()を呼び出すことで単一のルートにミドルウェアを適用することもできます。

1// prefixed builder
2Route.middleware(authLimiter).post('/register', 'auth.AuthController@register');
3
4// or chained directly on the route definition
5Route.post('/register', 'auth.AuthController@register').middleware(authLimiter);

ルート修飾子

すべてのルート定義は特定のルート上でフレームワークの動作を制御するいくつかの修飾子を公開するチェーン可能オブジェクトを返します。

csrf

csrf検証はすべてのpost、put、patch、deleteルートでデフォルトで有効になっています。.csrf(false)をチェーンすることで特定のルートに対して無効化できます。

1Route.post('/magic/:token', 'auth.AuthController@magicConsume').csrf(false);
2
3Route.csrf(false, (hooks) => {
4 hooks.post('/stripe/webhook', 'StripeController@handle');
5});

シールド

shieldセキュリティシステムがアクティブな場合受信したミューテーションリクエストを検証します。.shield(false)をチェーンするかルートをRoute.shield(false, callback)で囲むことでルートを除外できます。

1Route.post('/magic/:token', 'auth.AuthController@magicConsume').shield(false);
2
3Route.shield(false, (publicApi) => {
4 publicApi.post('/api/external', 'ExternalController@handle');
5});

ルートレベルミドルウェア

任意のルート定義に直接.middleware()をチェーンしてルートレベルミドルウェアをアタッチできます。ミドルウェア文字列、ミドルウェアの配列、またはRateLimiterインスタンスを受け付けます。複数の.middleware()呼び出しを順番にチェーンすることもできます。

1Route.get('/profile', 'ProfileController@show').middleware('AuthMiddleware@requireAuth');
2
3Route.post('/orders', 'OrderController@store').middleware(['AuthMiddleware@requireAuth', orderLimiter]);
4
5Route.get('/settings', 'SettingsController@index')
6 .middleware('AuthMiddleware@requireAuth')
7 .middleware('TwoFactorMiddleware@require2fa');

ログ

リクエストとレスポンスのロギングはlocal環境では自動的に行われます。本番環境で特定のルートのロギングを強制するには.log()をチェーンします。

1Route.post('/api/playback/track', 'app.PlaybackController@get_track').name('api.playback.track').log();

ビュー

.views()修飾子はルートコンパイラに対してこのルートがレンダリングするビューテンプレートを正確に伝えます。本番ビルド中にコンパイラはそれらのテンプレートを解析してコンパイルされたハンドラーが実際に必要とするセッションデータ、ロケール検出、リクエストボディ解析を特定します。明示的なビュー名の指定は静的解析ステップにおける曖昧さを排除する最適化ヒントとなります。

動的なビュー名(変数を介したレンダリングなど)はコンパイラによって静的に検査できません。パフォーマンスが重要なルートでは動的なビュー名は推奨されません。動的ビューのレンダリングが必要な場合はコンパイラが翻訳タグ、レイアウト依存関係、ミドルウェアの要件を検出できるように考えられるすべてのビュー名を指定して.views(['template.name'])を提供する必要があります。

1Route.get('/dashboard', 'app.IndexController@dashboard').name('dashboard').views(['app.home.index']);

プロファイル

.profile()修飾子を使用するとコンパイラがルートの静的解析から導出した動作プロファイルを上書きできます。解析された値を置き換えるキーを持つオブジェクトを渡します。これは自動解析によって誤ったまたは最適ではないコンパイル済みハンドラーが生成されるルートに対する高度なエスケープハッチです。

利用可能なプロファイルキーは以下の通りです:

1Route.get('/feed', 'app.FeedController@index').profile({ needsSession: true, needsFlash: true });

.csrf(false)と.shield(false)の両方が指定された変更系ルート(POST、PUT、PATCH、DELETE)では、本番用のルートコンパイラは静的解析によってボディへのアクセス(req.body、req.files、req.file()、req.hasFile()、req.input()、req.all()、または validate())が検出された場合にのみリクエストボディをパースします。reqをModelのメソッドに直接渡すパターン(await Post.createFromRequest(req))、bodyやfilesの前にネストされた分割代入を行うパターン(async update({ params: { id }, body }))、または.input()や.all()を呼び出す前にreqをローカル変数にエイリアスするパターン(const r = req; r.input('name'))といった間接的な書き方は解析器がボディアクセスとして認識しないため推奨されません。csrfとshieldを無効にしたルートでこれらのパターンを意図的に使用する場合は、.profile({ needsBody: true })を指定してボディのパースを明示的に強制してください:

1Route.post('/api/posts/:id', 'ApiPostController@update')
2 .csrf(false)
3 .shield(false)
4 .profile({ needsBody: true });
NOTE

ローカル開発環境では変更系ルートは常に無条件でリクエストボディをパースします(不正なjsonの場合は`400`、`app.maxBodySize`を超えるペイロードの場合は`413`を返します)。一方、本番環境では`.csrf(false)`と`.shield(false)`が指定されておりボディへのアクセスも`.profile({ needsBody: true })`もないコンパイル済みルートはボディのパースを完全にスキップするため、それらのエンドポイントに不正なjsonやサイズ超過のボディが送信されても自動的な`400`または`413`レスポンスは返されません。

ベーシック認証

.basicAuth()をチェーンして特定のルートをhttpベーシック認証で保護できます。明示的な認証情報、カスタムバリデータコールバック、カスタムrealmを含むオプションオブジェクトを受け入れるかconfig/auth.js(auth.basic)で設定されたデフォルト値を使用します。

1Route.get('/secret', 'app.SecretController@show').basicAuth('admin', 'secret');
2Route.get('/admin', 'app.AdminController@index').basicAuth();
3Route.get('/users', 'app.UserController@index').basicAuth(async (user, pass) => user === 'admin' && pass === 'secret');

コントローラ文字列の構文

コントローラ文字列はdirectory.ControllerName@methodの規則に従います。ディレクトリセグメントはcontrollers/内のサブディレクトリにマッピングされます。controllers/app/IndexController.jsにあるコントローラはapp.IndexController@indexとして参照されます。controllers/auth/AuthController.jsにあるコントローラはauth.AuthController@registerとして参照されます。

1Route.get('/dashboard', 'app.IndexController@dashboard');
2Route.post('/register', 'auth.AuthController@register');

サブディレクトリがなくcontrollers/ルートに直接配置されたコントローラの場合はディレクトリプレフィックスを完全に省略します。

1Route.get('/locale/:locale', 'LocaleController@set');

複数のルートファイル

routesディレクトリ内で必要に応じてルートを複数のファイルに分割できます。フレームワークはその場所で見つかったすべての.jsファイルを自動的に読み込みます。読み込みの順序はファイルシステムのソート順に従います。

1// routes/web.js (http routes)
2// routes/wire.js (socket routes)