4.x API

express.json([options])

これは Express の組み込みミドルウェア関数です。JSON ペイロードを持つ受信リクエストを解析し、body-parser に基づいています。

JSON のみを解析し、Content-Type ヘッダーが type オプションと一致するリクエストのみを対象とするミドルウェアを返します。このパーサーは、ボディの任意の Unicode エンコーディングを受け入れ、gzip および deflate エンコーディングの自動インフレをサポートします。

解析されたデータを含む新しい body オブジェクトは、ミドルウェアの後（つまり req.body）に request オブジェクトに設定されます。解析するボディがない場合、Content-Type が一致しなかった場合、またはエラーが発生した場合は、空のオブジェクト（{}）が設定されます。

次の表に、オプションの options オブジェクトのプロパティを示します。

express.raw([options])

これは Express の組み込みミドルウェア関数です。受信リクエストペイロードを Buffer に解析し、body-parser に基づいています。

すべてのボディを Buffer として解析し、Content-Type ヘッダーが type オプションと一致するリクエストのみを対象とするミドルウェアを返します。このパーサーは、ボディの任意の Unicode エンコーディングを受け入れ、gzip および deflate エンコーディングの自動インフレをサポートします。

解析されたデータを含む新しい body Buffer は、ミドルウェアの後（つまり req.body）に request オブジェクトに設定されます。解析するボディがない場合、Content-Type が一致しなかった場合、またはエラーが発生した場合は、空のオブジェクト（{}）が設定されます。

次の表に、オプションの options オブジェクトのプロパティを示します。

express.Router([options])

新しい ルーター オブジェクトを作成します。

var router = express.Router([options])

オプションの options パラメーターは、ルーターの動作を指定します。

アプリケーションと同様に、ミドルウェアと HTTP メソッドルート（get、put、post など）を router に追加できます。

詳細については、ルーターを参照してください。

express.static(root, [options])

これは Express の組み込みミドルウェア関数です。静的ファイルを提供し、serve-static に基づいています。

root 引数は、静的アセットを提供するためのルートディレクトリを指定します。関数は、req.url と指定された root ディレクトリを組み合わせることによって、提供するファイルを決定します。ファイルが見つからない場合、404 応答を送信する代わりに、next() を呼び出して次のミドルウェアに進み、スタックとフォールバックを可能にします。

次の表に、options オブジェクトのプロパティを示します。また、以下の例も参照してください。

詳細については、Express での静的ファイルの提供 および ミドルウェアの使用 - 組み込みミドルウェア を参照してください。

dotfiles

このオプションの可能な値は次のとおりです。

• “allow” - ドットファイルの特別な処理は行いません。
• “deny” - ドットファイルのリクエストを拒否し、403 で応答し、next() を呼び出します。
• “ignore” - ドットファイルが存在しないかのように動作し、404 で応答し、next() を呼び出します。

注意：デフォルト値では、ドットで始まるディレクトリ内のファイルは無視されません。

fallthrough

このオプションがtrueの場合、不正なリクエストや存在しないファイルへのリクエストなどのクライアントエラーが発生すると、このミドルウェアは単にnext()を呼び出し、スタック内の次のミドルウェアを起動します。falseの場合、これらのエラー（404エラーを含む）はnext(err)を起動します。

このオプションをtrueに設定すると、複数の物理ディレクトリを同じWebアドレスにマッピングしたり、存在しないファイルをルートで埋めたりできます。

このミドルウェアを単一のファイルシステムディレクトリとして厳密に設計されたパスにマウントしている場合は、falseを使用すると、オーバーヘッドを削減するために404エラーをショートカットできます。このミドルウェアは、すべてのメソッドに応答します。

setHeaders

このオプションでは、カスタムレスポンスヘッダーを設定する関数を指定します。ヘッダーの変更は同期的に行われる必要があります。

関数の署名は次のとおりです。

fn(res, path, stat)

引数

• res、レスポンスオブジェクト。
• path、送信されるファイルパス。
• stat、送信されるファイルのstatオブジェクト。

express.staticの例

以下は、詳細なオプションオブジェクトを使用してexpress.staticミドルウェア関数を使用する例です。

var options = {
  dotfiles: 'ignore',
  etag: false,
  extensions: ['htm', 'html'],
  index: false,
  maxAge: '1d',
  redirect: false,
  setHeaders: function (res, path, stat) {
    res.set('x-timestamp', Date.now())
  }
}

app.use(express.static('public', options))

express.text([options])

これは、Expressに組み込まれているミドルウェア関数です。受信リクエストのペイロードを文字列に解析し、body-parserに基づいています。

すべてのボディを文字列として解析し、Content-Typeヘッダーがtypeオプションに一致するリクエストのみを対象とするミドルウェアを返します。このパーサーは、ボディの任意のUnicodeエンコーディングを受け入れ、gzipおよびdeflateエンコーディングの自動インフレをサポートします。

ミドルウェアの後に、解析されたデータを含む新しいbody文字列がrequestオブジェクト（つまり、req.body）に設定されます。または、解析するボディがないか、Content-Typeが一致しなかったか、エラーが発生した場合は、空のオブジェクト（{}）が設定されます。

次の表に、オプションの options オブジェクトのプロパティを示します。

express.urlencoded([options])

これは、Expressに組み込まれているミドルウェア関数です。URLエンコードされたペイロードを持つ受信リクエストを解析し、body-parserに基づいています。

URLエンコードされたボディのみを解析し、Content-Typeヘッダーがtypeオプションに一致するリクエストのみを対象とするミドルウェアを返します。このパーサーは、ボディのUTF-8エンコーディングのみを受け入れ、gzipおよびdeflateエンコーディングの自動インフレをサポートします。

ミドルウェアの後に、解析されたデータを含む新しいbodyオブジェクトがrequestオブジェクト（つまり、req.body）に設定されます。または、解析するボディがないか、Content-Typeが一致しなかったか、エラーが発生した場合は、空のオブジェクト（{}）が設定されます。このオブジェクトには、キーと値のペアが含まれます。値は、文字列または配列（extendedがfalseの場合）または任意の型（extendedがtrueの場合）にすることができます。

次の表に、オプションの options オブジェクトのプロパティを示します。

app.locals

app.localsオブジェクトには、アプリケーション内のローカル変数であるプロパティがあり、res.renderでレンダリングされたテンプレートで利用できます。

console.dir(app.locals.title)
// => 'My App'

console.dir(app.locals.email)
// => 'me@myapp.com'

設定されると、app.localsプロパティの値はアプリケーションのライフサイクル全体を通じて保持されます。これは、リクエストのライフサイクルに対してのみ有効なres.localsプロパティとは対照的です。

アプリケーション内でレンダリングされたテンプレートでローカル変数にアクセスできます。これは、テンプレートにヘルパー関数を提供するだけでなく、アプリケーションレベルのデータを提供する場合にも役立ちます。ローカル変数は、ミドルウェアでreq.app.locals（req.appを参照）を介して利用できます。

app.locals.title = 'My App'
app.locals.strftime = require('strftime')
app.locals.email = 'me@myapp.com'

app.mountpath

app.mountpathプロパティには、サブアプリがマウントされた1つ以上のパスパターンが含まれています。

var express = require('express')

var app = express() // the main app
var admin = express() // the sub app

admin.get('/', function (req, res) {
  console.log(admin.mountpath) // /admin
  res.send('Admin Homepage')
})

app.use('/admin', admin) // mount the sub app

reqオブジェクトのbaseUrlプロパティに似ていますが、req.baseUrlは一致したURLパスを返すのに対し、一致したパターンを返します。

サブアプリが複数のパスパターンにマウントされている場合、app.mountpathは次の例に示すように、マウントされているパターンのリストを返します。

var admin = express()

admin.get('/', function (req, res) {
  console.dir(admin.mountpath) // [ '/adm*n', '/manager' ]
  res.send('Admin Homepage')
})

var secret = express()
secret.get('/', function (req, res) {
  console.log(secret.mountpath) // /secr*t
  res.send('Admin Secret')
})

admin.use('/secr*t', secret) // load the 'secret' router on '/secr*t', on the 'admin' sub app
app.use(['/adm*n', '/manager'], admin) // load the 'admin' router on '/adm*n' and '/manager', on the parent app

app.on('mount', callback(parent))

mountイベントは、サブアプリが親アプリにマウントされるときにサブアプリで発生します。親アプリはコールバック関数に渡されます。

var admin = express()

admin.on('mount', function (parent) {
  console.log('Admin Mounted')
  console.log(parent) // refers to the parent app
})

admin.get('/', function (req, res) {
  res.send('Admin Homepage')
})

app.use('/admin', admin)

app.all(path, callback [, callback ...])

このメソッドは、すべてのHTTP動詞に一致することを除いて、標準のapp.METHOD()メソッドに似ています。

引数

例

次のコールバックは、GET、POST、PUT、DELETE、またはその他のHTTPリクエストメソッドを使用するかどうかに関係なく、/secretへのリクエストに対して実行されます。

app.all('/secret', function (req, res, next) {
  console.log('Accessing the secret section ...')
  next() // pass control to the next handler
})

app.all()メソッドは、特定のパスプレフィックスまたは任意の合致に対する「グローバル」ロジックのマッピングに役立ちます。たとえば、他のすべてのルート定義の先頭に以下を配置すると、その時点からのすべてのルートで認証が必要になり、ユーザーが自動的にロードされます。これらのコールバックはエンドポイントとして機能する必要がないことに注意してください。loadUserはタスクを実行し、next()を呼び出して後続のルートのマッチングを続行できます。

app.all('*', requireAuthentication, loadUser)

または、同等の

app.all('*', requireAuthentication)
app.all('*', loadUser)

別の例は、ホワイトリスト化された「グローバル」機能です。例は上記の例に似ていますが、「/api」で始まるパスのみを制限します。

app.all('/api/*', requireAuthentication)

app.delete(path, callback [, callback ...])

指定されたコールバック関数を使用して、指定されたパスへのHTTP DELETEリクエストをルーティングします。詳細については、ルーティングガイドを参照してください。

引数

例

app.delete('/', function (req, res) {
  res.send('DELETE request to homepage')
})

app.disable(name)

ブール設定nameをfalseに設定します。ここで、nameはアプリ設定テーブルのプロパティの1つです。ブールプロパティに対してapp.set('foo', false)を呼び出すことは、app.disable('foo')を呼び出すことと同じです。

例:

app.disable('trust proxy')
app.get('trust proxy')
// => false

app.disabled(name)

ブール設定nameが無効（false）の場合（nameはアプリ設定テーブルのプロパティの1つ）、trueを返します。

app.disabled('trust proxy')
// => true

app.enable('trust proxy')
app.disabled('trust proxy')
// => false

app.enable(name)

ブール設定nameをtrueに設定します。ここで、nameはアプリ設定テーブルのプロパティの1つです。ブールプロパティに対してapp.set('foo', true)を呼び出すことは、app.enable('foo')を呼び出すことと同じです。

app.enable('trust proxy')
app.get('trust proxy')
// => true

app.enabled(name)

設定nameが有効（true）の場合（nameはアプリ設定テーブルのプロパティの1つ）、trueを返します。

app.enabled('trust proxy')
// => false

app.enable('trust proxy')
app.enabled('trust proxy')
// => true

app.engine(ext, callback)

指定されたテンプレートエンジンcallbackをextとして登録します。

デフォルトでは、Expressはファイル拡張子に基づいてエンジンをrequire()します。たとえば、「foo.pug」ファイルをレンダリングしようとすると、Expressは内部で次を呼び出し、パフォーマンスを向上させるために後続の呼び出しでrequire()をキャッシュします。

app.engine('pug', require('pug').__express)

このメソッドは、すぐに.__expressを提供しないエンジン、またはテンプレートエンジンに別の拡張子を「マッピング」する場合に使用します。

たとえば、EJSテンプレートエンジンを「.html」ファイルにマッピングするには

app.engine('html', require('ejs').renderFile)

この場合、EJSはExpressが期待するのと同じ署名を持つ.renderFile()メソッド（(path, options, callback)）を提供します。ただし、内部でこのメソッドをejs.__expressとしてエイリアスしているため、「.ejs」拡張機能を使用している場合は何もする必要がないことに注意してください。

一部のテンプレートエンジンはこの規則に従いません。consolidate.jsライブラリは、Nodeテンプレートエンジンをこの規則に従うようにマッピングするため、Expressでシームレスに動作します。

var engines = require('consolidate')
app.engine('haml', engines.haml)
app.engine('html', engines.hogan)

app.get(name)

nameアプリ設定の値を返します。ここで、nameはアプリ設定テーブルの文字列の1つです。例:

app.get('title')
// => undefined

app.set('title', 'My Site')
app.get('title')
// => "My Site"

app.get(path, callback [, callback ...])

指定されたパスへのHTTP GETリクエストを、指定されたコールバック関数で処理します。

引数

詳細については、ルーティングガイドを参照してください。

例

app.get('/', function (req, res) {
  res.send('GET request to homepage')
})

app.listen(path, [callback])

UNIXソケットを起動し、指定されたパスでの接続を待ち受けます。このメソッドは、Nodeのhttp.Server.listen()と同じです。

var express = require('express')
var app = express()
app.listen('/tmp/sock')

app.listen([port[, host[, backlog]]][, callback])

指定されたホストとポートでの接続をバインドして待ち受けます。このメソッドは、Nodeのhttp.Server.listen()と同じです。

portを省略するか、0を指定すると、オペレーティングシステムが任意の未使用ポートを割り当てます。これは自動化されたタスク（テストなど）の場合に便利です。

var express = require('express')
var app = express()
app.listen(3000)

express()によって返されるappは、実際にはJavaScriptのFunctionであり、リクエストを処理するためのコールバックとしてNodeのHTTPサーバーに渡されるように設計されています。これにより、アプリはこれらの（単なるコールバックである）サーバーから継承しないため、同じコードベースでHTTPとHTTPSの両方のバージョンのアプリを簡単に提供できます。

var express = require('express')
var https = require('https')
var http = require('http')
var app = express()

http.createServer(app).listen(80)
https.createServer(options, app).listen(443)

app.listen()メソッドはhttp.Serverオブジェクトを返し、（HTTPの場合）以下の便利なメソッドです。

app.listen = function () {
  var server = http.createServer(this)
  return server.listen.apply(server, arguments)
}

app.METHOD(path, callback [, callback ...])

HTTPリクエストをルーティングします。METHODは、GET、PUT、POSTなどのリクエストのHTTPメソッドを小文字で表します。したがって、実際のメソッドはapp.get()、app.post()、app.put()などです。完全なリストについては、下記のルーティングメソッドを参照してください。

引数

ルーティングメソッド

Expressは、同じ名前のHTTPメソッドに対応する以下のルーティングメソッドをサポートしています。

APIドキュメントには、最も一般的なHTTPメソッドであるapp.get()、app.post()、app.put()、およびapp.delete()のエントリのみが明示的に記載されています。ただし、上記の他のメソッドはまったく同じように機能します。

無効なJavaScript変数名に変換されるメソッドをルーティングするには、ブラケット表記を使用します。たとえば、app['m-search']('/', function ...のようにします。

メソッドapp.all()は、どのHTTPメソッドにも由来せず、すべてのHTTPリクエストメソッドに対して、指定されたパスでミドルウェアをロードします。詳細については、app.allを参照してください。

ルーティングの詳細については、ルーティングガイドを参照してください。

app.param([name], callback)

ルートパラメーターにコールバックトリガーを追加します。ここで、nameはパラメーターの名前またはそれらの配列であり、callbackはコールバック関数です。コールバック関数のパラメーターは、リクエストオブジェクト、レスポンスオブジェクト、次のミドルウェア、パラメーターの値、パラメーターの名前の順です。

nameが配列の場合、callbackトリガーは、宣言された順序で、その中で宣言された各パラメーターに対して登録されます。さらに、宣言された最後のパラメーターを除く各パラメーターについて、コールバック内のnextの呼び出しは、次に宣言されたパラメーターのコールバックを呼び出します。最後のパラメーターの場合、nextの呼び出しは、nameが単なる文字列の場合と同じように、現在処理中のルートの次のミドルウェアを呼び出します。

たとえば、ルートパスに:userが存在する場合、ユーザーロードロジックをマッピングして、req.userをルートに自動的に提供したり、パラメーター入力の検証を実行したりできます。

app.param('user', function (req, res, next, id) {
  // try to get the user details from the User model and attach it to the request object
  User.find(id, function (err, user) {
    if (err) {
      next(err)
    } else if (user) {
      req.user = user
      next()
    } else {
      next(new Error('failed to load user'))
    }
  })
})

Paramコールバック関数は、それらが定義されているルーターにローカルです。それらは、マウントされたアプリやルーターによって継承されません。したがって、appで定義されたparamコールバックは、appルートで定義されたルートパラメーターによってのみトリガーされます。

すべてのparamコールバックは、paramが発生するすべてのルートのハンドラーよりも前に呼び出され、次の例に示すように、パラメーターが複数のルートで一致する場合でも、リクエスト-レスポンスサイクルでそれぞれ1回だけ呼び出されます。

app.param('id', function (req, res, next, id) {
  console.log('CALLED ONLY ONCE')
  next()
})

app.get('/user/:id', function (req, res, next) {
  console.log('although this matches')
  next()
})

app.get('/user/:id', function (req, res) {
  console.log('and this matches too')
  res.end()
})

GET /user/42では、以下が出力されます

CALLED ONLY ONCE
although this matches
and this matches too

app.param(['id', 'page'], function (req, res, next, value) {
  console.log('CALLED ONLY ONCE with', value)
  next()
})

app.get('/user/:id/:page', function (req, res, next) {
  console.log('although this matches')
  next()
})

app.get('/user/:id/:page', function (req, res) {
  console.log('and this matches too')
  res.end()
})

GET /user/42/3では、以下が出力されます

CALLED ONLY ONCE with 42
CALLED ONLY ONCE with 3
although this matches
and this matches too

app.param(name, callback)メソッドの動作は、関数のみをapp.param()に渡すことによって完全に変更できます。この関数は、app.param(name, callback)がどのように動作すべきかのカスタム実装です。2つのパラメーターを受け取り、ミドルウェアを返す必要があります。

この関数の最初のパラメーターは、キャプチャする必要があるURLパラメーターの名前であり、2番目のパラメーターは、ミドルウェアの実装を返すために使用される可能性のある任意のJavaScriptオブジェクトです。

関数によって返されるミドルウェアは、URLパラメーターがキャプチャされたときの動作を決定します。

この例では、app.param(name, callback)シグネチャはapp.param(name, accessId)に変更されています。名前とコールバックを受け入れる代わりに、app.param()は名前と数値を受け入れるようになります。

var express = require('express')
var app = express()

// customizing the behavior of app.param()
app.param(function (param, option) {
  return function (req, res, next, val) {
    if (val === option) {
      next()
    } else {
      next('route')
    }
  }
})

// using the customized app.param()
app.param('id', 1337)

// route to trigger the capture
app.get('/user/:id', function (req, res) {
  res.send('OK')
})

app.listen(3000, function () {
  console.log('Ready')
})

この例では、app.param(name, callback)シグネチャは同じままですが、ミドルウェアコールバックの代わりに、ユーザーIDのデータ型を検証するためのカスタムデータ型チェック関数が定義されています。

app.param(function (param, validator) {
  return function (req, res, next, val) {
    if (validator(val)) {
      next()
    } else {
      next('route')
    }
  }
})

app.param('id', function (candidate) {
  return !isNaN(parseFloat(candidate)) && isFinite(candidate)
})

// captures '1-a_6' but not '543-azser-sder'
router.get('/[0-9]+-[[\\w]]*', function (req, res, next) { next() })

// captures '1-a_6' and '543-az(ser"-sder' but not '5-a s'
router.get('/[0-9]+-[[\\S]]*', function (req, res, next) { next() })

// captures all (equivalent to '.*')
router.get('[[\\s\\S]]*', function (req, res, next) { next() })

app.path()

アプリの正規パスである文字列を返します。

var app = express()
var blog = express()
var blogAdmin = express()

app.use('/blog', blog)
blog.use('/admin', blogAdmin)

console.dir(app.path()) // ''
console.dir(blog.path()) // '/blog'
console.dir(blogAdmin.path()) // '/blog/admin'

このメソッドの動作は、マウントされたアプリの複雑なケースでは非常に複雑になる可能性があります。アプリの正規パスを取得するには、req.baseUrlを使用する方が通常は優れています。

app.post(path, callback [, callback ...])

指定されたパスへのHTTP POSTリクエストを、指定されたコールバック関数で処理します。詳細については、ルーティングガイドを参照してください。

引数

例

app.post('/', function (req, res) {
  res.send('POST request to homepage')
})

app.put(path, callback [, callback ...])

指定されたパスへのHTTP PUTリクエストを、指定されたコールバック関数で処理します。

引数

例

app.put('/', function (req, res) {
  res.send('PUT request to homepage')
})

app.render(view, [locals], callback)

callback関数を介して、ビューのレンダリングされたHTMLを返します。ビューのローカル変数を含むオブジェクトであるオプションのパラメーターを受け入れます。res.render()に似ていますが、それ自体でレンダリングされたビューをクライアントに送信することはできません。

app.render('email', function (err, html) {
  // ...
})

app.render('email', { name: 'Tobi' }, function (err, html) {
  // ...
})

app.route(path)

単一ルートのインスタンスを返します。これを使用して、オプションのミドルウェアでHTTP動詞を処理できます。app.route()を使用して、重複するルート名（およびそれによるタイプミスエラー）を回避します。

var app = express()

app.route('/events')
  .all(function (req, res, next) {
    // runs for all HTTP verbs first
    // think of it as route specific middleware!
  })
  .get(function (req, res, next) {
    res.json({})
  })
  .post(function (req, res, next) {
    // maybe add a new event...
  })

app.set(name, value)

設定nameをvalueに割り当てます。任意の値を格納できますが、特定の名前を使用してサーバーの動作を構成できます。これらの特別な名前は、アプリ設定テーブルにリストされています。

ブールプロパティに対してapp.set('foo', true)を呼び出すことは、app.enable('foo')を呼び出すことと同じです。同様に、ブールプロパティに対してapp.set('foo', false)を呼び出すことは、app.disable('foo')を呼び出すことと同じです。

app.get()を使用して、設定の値を取得します。

app.set('title', 'My Site')
app.get('title') // "My Site"

アプリケーション設定

次の表は、アプリケーション設定を示しています。

サブアプリは

• デフォルト値を持つ設定の値を継承しません。サブアプリで値を設定する必要があります。
• デフォルト値のない設定の値を継承します。これらは下の表に明示的に示されています。

例外：サブアプリは、デフォルト値を持っている場合でも、trust proxyの値を継承します（下位互換性のために）。サブアプリは、本番環境（NODE_ENVが「production」の場合）でview cacheの値を継承しません。

app.set('trust proxy', 'loopback')

app.set('trust proxy', 'loopback, 123.123.123.123')

app.set('trust proxy', 'loopback, linklocal, uniquelocal')

app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal'])

app.set('trust proxy', function (ip) {
  if (ip === '127.0.0.1' || ip === '123.123.123.123') return true // trusted IPs
  else return false
})

app.set('etag', function (body, encoding) {
  return generateHash(body, encoding) // consider the function is defined
})

app.use([path,] callback [, callback...])

指定されたミドルウェア関数または関数を指定されたパスにマウントします。リクエストされたパスのベースがpathと一致すると、ミドルウェア関数が実行されます。

引数

説明

ルートは、「/」を使用してそのパスに続く任意のパスにすぐ一致します。例：app.use('/apple', ...)は、「/apple」、「/apple/images」、「/apple/images/news」などに一致します。

pathのデフォルトは「/」なので、パスなしでマウントされたミドルウェアは、アプリへのすべてのリクエストに対して実行されます。
たとえば、このミドルウェア関数は、アプリへのすべてのリクエストに対して実行されます

app.use(function (req, res, next) {
  console.log('Time: %d', Date.now())
  next()
})

ミドルウェア関数は順番に実行されるため、ミドルウェアの包含順序が重要です。

// this middleware will not allow the request to go beyond it
app.use(function (req, res, next) {
  res.send('Hello World')
})

// requests will never reach this route
app.get('/', function (req, res) {
  res.send('Welcome')
})

エラー処理ミドルウェア

エラー処理ミドルウェアは、常に4つの引数を取ります。エラー処理ミドルウェア関数として識別するには、4つの引数を指定する必要があります。nextオブジェクトを使用する必要がない場合でも、シグネチャを維持するために指定する必要があります。そうしないと、nextオブジェクトは通常のミドルウェアとして解釈され、エラーを処理できません。エラー処理ミドルウェアの詳細については、エラー処理を参照してください。

エラー処理ミドルウェア関数は、3つではなく4つの引数、特に(err, req, res, next)のシグネチャを除いて、他のミドルウェア関数と同じ方法で定義します

app.use(function (err, req, res, next) {
  console.error(err.stack)
  res.status(500).send('Something broke!')
})

パスの例

次の表に、ミドルウェアをマウントするための有効なpath値の簡単な例をいくつか示します。

app.use('/abcd', function (req, res, next) {
  next()
})

app.use('/abc?d', function (req, res, next) {
  next()
})

app.use('/ab+cd', function (req, res, next) {
  next()
})

app.use('/ab*cd', function (req, res, next) {
  next()
})

app.use('/a(bc)?d', function (req, res, next) {
  next()
})

app.use(/\/abc|\/xyz/, function (req, res, next) {
  next()
})

app.use(['/abcd', '/xyza', /\/lmn|\/pqr/], function (req, res, next) {
  next()
})

ミドルウェアコールバック関数の例

次の表に、app.use()、app.METHOD()、およびapp.all()へのcallback引数として使用できるミドルウェア関数の簡単な例をいくつか示します。例はapp.use()に関するものですが、app.use()、app.METHOD()、およびapp.all()でも有効です。

app.use(function (req, res, next) {
  next()
})

var router = express.Router()
router.get('/', function (req, res, next) {
  next()
})
app.use(router)

var subApp = express()
subApp.get('/', function (req, res, next) {
  next()
})
app.use(subApp)

var r1 = express.Router()
r1.get('/', function (req, res, next) {
  next()
})

var r2 = express.Router()
r2.get('/', function (req, res, next) {
  next()
})

app.use(r1, r2)

var r1 = express.Router()
r1.get('/', function (req, res, next) {
  next()
})

var r2 = express.Router()
r2.get('/', function (req, res, next) {
  next()
})

app.use([r1, r2])

function mw1 (req, res, next) { next() }
function mw2 (req, res, next) { next() }

var r1 = express.Router()
r1.get('/', function (req, res, next) { next() })

var r2 = express.Router()
r2.get('/', function (req, res, next) { next() })

var subApp = express()
subApp.get('/', function (req, res, next) { next() })

app.use(mw1, [mw2, r1, r2], subApp)

以下に、Expressアプリでexpress.staticミドルウェアを使用する例をいくつか示します。

アプリケーションディレクトリの「public」ディレクトリからアプリの静的コンテンツを提供します

// GET /style.css etc
app.use(express.static(path.join(__dirname, 'public')))

リクエストパスに「/static」がプレフィックスとして付いている場合にのみ静的コンテンツを提供するように、「/static」にミドルウェアをマウントします

// GET /static/style.css etc.
app.use('/static', express.static(path.join(__dirname, 'public')))

静的ミドルウェアの後にロガーミドルウェアをロードすることにより、静的コンテンツリクエストのロギングを無効にします

app.use(express.static(path.join(__dirname, 'public')))
app.use(logger())

複数のディレクトリから静的ファイルを提供しますが、他のディレクトリよりも「./public」を優先します

app.use(express.static(path.join(__dirname, 'public')))
app.use(express.static(path.join(__dirname, 'files')))
app.use(express.static(path.join(__dirname, 'uploads')))

req.app

このプロパティは、ミドルウェアを使用しているExpressアプリケーションのインスタンスへの参照を保持します。

ミドルウェア関数をエクスポートするだけのモジュールを作成し、メインファイルでrequire()するというパターンに従う場合、ミドルウェアはreq.appを介してExpressインスタンスにアクセスできます

例:

// index.js
app.get('/viewdirectory', require('./mymiddleware.js'))

// mymiddleware.js
module.exports = function (req, res) {
  res.send('The views directory is ' + req.app.get('views'))
}

req.baseUrl

ルーターインスタンスがマウントされたURLパス。

req.baseUrlプロパティは、appオブジェクトのmountpathプロパティに似ていますが、app.mountpathは一致したパスパターンを返します。

例:

var greet = express.Router()

greet.get('/jp', function (req, res) {
  console.log(req.baseUrl) // /greet
  res.send('Konichiwa!')
})

app.use('/greet', greet) // load the router on '/greet'

ルーターをロードするためにパスパターンまたはパスパターンのセットを使用する場合でも、baseUrlプロパティはパターンではなく、一致した文字列を返します。次の例では、greetルーターは2つのパスパターンでロードされます。

app.use(['/gre+t', '/hel{2}o'], greet) // load the router on '/gre+t' and '/hel{2}o'

/greet/jpへのリクエストが行われると、req.baseUrlは「/greet」になります。/hello/jpへのリクエストが行われると、req.baseUrlは「/hello」になります。

req.body

リクエストボディで送信されたデータのキーと値のペアが含まれています。デフォルトでは、undefinedであり、express.json()やexpress.urlencoded()などのボディ解析ミドルウェアを使用すると入力されます。

次の例は、ボディ解析ミドルウェアを使用してreq.bodyを設定する方法を示しています。

var express = require('express')

var app = express()

app.use(express.json()) // for parsing application/json
app.use(express.urlencoded({ extended: true })) // for parsing application/x-www-form-urlencoded

app.post('/profile', function (req, res, next) {
  console.log(req.body)
  res.json(req.body)
})

req.cookies

cookie-parserミドルウェアを使用すると、このプロパティはリクエストによって送信されたクッキーを含むオブジェクトになります。リクエストにクッキーが含まれていない場合、デフォルトは{}になります。

// Cookie: name=tj
console.dir(req.cookies.name)
// => 'tj'

クッキーが署名されている場合は、req.signedCookiesを使用する必要があります。

詳細、問題、または懸念事項については、cookie-parserを参照してください。

req.fresh

クライアントのキャッシュでレスポンスがまだ「新しい」場合、trueが返されます。それ以外の場合は、クライアントキャッシュが古くなったため、完全なレスポンスを送信する必要があることを示すためにfalseが返されます。

エンドツーエンドのリロードリクエストを示すために、クライアントがCache-Control: no-cacheリクエストヘッダーを送信すると、このモジュールはこれらのリクエストの処理を透過的にするためにfalseを返します。

キャッシュ検証のしくみの詳細については、HTTP/1.1キャッシング仕様を参照してください。

console.dir(req.fresh)
// => true

req.hostname

Host HTTPヘッダーから派生したホスト名が含まれています。

trust proxy設定がfalseと評価されない場合、このプロパティは代わりにX-Forwarded-Hostヘッダーフィールドから値を取得します。このヘッダーは、クライアントまたはプロキシによって設定できます。

リクエストに複数のX-Forwarded-Hostヘッダーがある場合、最初のヘッダーの値が使用されます。これには、カンマ区切りの値を持つ単一のヘッダーが含まれ、最初の値が使用されます。

// Host: "example.com:3000"
console.dir(req.hostname)
// => 'example.com'

req.ip

リクエストのリモートIPアドレスが含まれています。

trust proxy設定がfalseと評価されない場合、このプロパティの値はX-Forwarded-Forヘッダーの最も左側のエントリから導出されます。このヘッダーは、クライアントまたはプロキシによって設定できます。

console.dir(req.ip)
// => '127.0.0.1'

req.ips

trust proxy設定がfalseと評価されない場合、このプロパティには、X-Forwarded-Forリクエストヘッダーで指定されたIPアドレスの配列が含まれます。それ以外の場合は、空の配列が含まれます。このヘッダーは、クライアントまたはプロキシによって設定できます。

たとえば、X-Forwarded-Forがclient, proxy1, proxy2の場合、req.ipsは["client", "proxy1", "proxy2"]になり、proxy2は最も下流になります。

req.method

リクエストのHTTPメソッドに対応する文字列が含まれています：GET、POST、PUTなど。

req.originalUrl

このプロパティはreq.urlに似ていますが、内部ルーティングの目的でreq.urlを自由に書き換えることができるように、元のリクエストURLを保持します。たとえば、app.use()の「マウント」機能は、マウントポイントを削除するためにreq.urlを書き換えます。

// GET /search?q=something
console.dir(req.originalUrl)
// => '/search?q=something'

req.originalUrlはミドルウェアとルーターオブジェクトの両方で利用でき、req.baseUrlとreq.urlの組み合わせです。次の例を考慮してください

app.use('/admin', function (req, res, next) { // GET 'http://www.example.com/admin/new?sort=desc'
  console.dir(req.originalUrl) // '/admin/new?sort=desc'
  console.dir(req.baseUrl) // '/admin'
  console.dir(req.path) // '/new'
  next()
})

req.params

このプロパティは、名前付きルート「パラメーター」にマップされたプロパティを含むオブジェクトです。たとえば、ルート/user/:nameがある場合、「name」プロパティはreq.params.nameとして使用できます。このオブジェクトのデフォルトは{}です。

// GET /user/tj
console.dir(req.params.name)
// => 'tj'

ルート定義に正規表現を使用すると、キャプチャグループはreq.params[n]を使用して配列で提供されます。ここで、nはn番目のキャプチャグループです。このルールは、/file/*のような文字列ルートを使用した名前のないワイルドカード一致に適用されます。

// GET /file/javascripts/jquery.js
console.dir(req.params[0])
// => 'javascripts/jquery.js'

req.paramsのキーを変更する必要がある場合は、app.paramハンドラーを使用します。変更は、ルートパスですでに定義されているパラメーターにのみ適用できます。

ミドルウェアまたはルートハンドラーでreq.paramsオブジェクトに加えられた変更はすべてリセットされます。

req.path

リクエスト URL のパス部分を含みます。

// example.com/users?sort=desc
console.dir(req.path)
// => '/users'

req.protocol

リクエストプロトコル文字列（http または (TLS リクエストの場合は) https）を含みます。

trust proxy 設定が false と評価されない場合、このプロパティは X-Forwarded-Proto ヘッダーフィールドの値（存在する場合）を使用します。このヘッダーはクライアントまたはプロキシによって設定できます。

console.dir(req.protocol)
// => 'http'

req.query

このプロパティは、ルート内の各クエリ文字列パラメータのプロパティを含むオブジェクトです。クエリパーサー が無効に設定されている場合は、空のオブジェクト {} になります。それ以外の場合は、構成されたクエリパーサーの結果になります。

このプロパティの値は、アプリケーションのニーズに合わせて動作するように クエリパーサーアプリケーション設定 で構成できます。非常に人気のあるクエリ文字列パーサーは qs モジュールであり、これがデフォルトで使用されます。qs モジュールは多くの設定で高度に構成可能であり、デフォルトとは異なる設定を使用して req.query を設定することが望ましい場合があります。

var qs = require('qs')
app.set('query parser', function (str) {
  return qs.parse(str, { /* custom options */ })
})

その他のカスタマイズオプションについては、クエリパーサーアプリケーション設定のドキュメントを確認してください。

req.res

このプロパティは、このリクエストオブジェクトに関連する レスポンスオブジェクトへの参照を保持します。

req.route

現在一致しているルート（文字列）を含みます。例：

app.get('/user/:id?', function userIdHandler (req, res) {
  console.log(req.route)
  res.send('GET')
})

前のスニペットからの出力例

{ path: '/user/:id?',
  stack:
   [ { handle: [Function: userIdHandler],
       name: 'userIdHandler',
       params: undefined,
       path: undefined,
       keys: [],
       regexp: /^\/?$/i,
       method: 'get' } ],
  methods: { get: true } }

req.secure

TLS 接続が確立されている場合は true であるブール値プロパティ。以下と同等です。

console.dir(req.protocol === 'https')
// => true

req.signedCookies

cookie-parser ミドルウェアを使用すると、このプロパティには、リクエストによって送信された署名付きクッキーが、署名なしで、すぐに使用できる状態で含まれます。署名付きクッキーは、開発者の意図を示すために別のオブジェクトに存在します。そうでないと、悪意のある攻撃が req.cookie の値（偽造が容易）に対して行われる可能性があります。クッキーに署名しても、クッキーが「隠される」または暗号化されるわけではないことに注意してください。単に改ざんを防ぐだけです（署名に使用される秘密鍵はプライベートであるため）。

署名付きクッキーが送信されない場合、プロパティはデフォルトで {} になります。

// Cookie: user=tobi.CP7AWaXDfAKIRfH49dQzKJx7sKzzSoPq7/AcBBRVwlI3
console.dir(req.signedCookies.user)
// => 'tobi'

詳細、問題、または懸念事項については、cookie-parserを参照してください。

req.stale

リクエストが「古い」かどうかを示し、req.fresh の反対です。詳細については、req.fresh を参照してください。

console.dir(req.stale)
// => true

req.subdomains

リクエストのドメイン名のサブドメインの配列。

// Host: "tobi.ferrets.example.com"
console.dir(req.subdomains)
// => ['ferrets', 'tobi']

デフォルトが 2 のアプリケーションプロパティ subdomain offset は、サブドメインセグメントの開始を決定するために使用されます。この動作を変更するには、app.set を使用して値を変更します。

req.xhr

リクエストの X-Requested-With ヘッダーフィールドが “XMLHttpRequest” である場合、つまり、リクエストが jQuery などのクライアントライブラリによって発行された場合、true であるブール値プロパティ。

console.dir(req.xhr)
// => true

req.accepts(types)

リクエストの Accept HTTP ヘッダーフィールドに基づいて、指定されたコンテンツタイプが許容可能かどうかを確認します。このメソッドは、最適な一致を返します。または、指定されたコンテンツタイプがどれも許容できない場合は false を返します (この場合、アプリケーションは 406 "Not Acceptable" で応答する必要があります)。

type の値は、単一の MIME タイプ文字列（"application/json" など）、"json" などの拡張子名、カンマ区切りのリスト、または配列にできます。リストまたは配列の場合、メソッドは (もしあれば) *最適な* 一致を返します。

// Accept: text/html
req.accepts('html')
// => "html"

// Accept: text/*, application/json
req.accepts('html')
// => "html"
req.accepts('text/html')
// => "text/html"
req.accepts(['json', 'text'])
// => "json"
req.accepts('application/json')
// => "application/json"

// Accept: text/*, application/json
req.accepts('image/png')
req.accepts('png')
// => false

// Accept: text/*;q=.5, application/json
req.accepts(['html', 'json'])
// => "json"

詳細、問題、または懸念がある場合は、accepts を参照してください。

req.acceptsCharsets(charset [, ...])

リクエストの Accept-Charset HTTP ヘッダーフィールドに基づいて、指定された文字セットの最初に受け入れられた文字セットを返します。指定された文字セットのいずれも受け入れられない場合は、false を返します。

詳細、問題、または懸念がある場合は、accepts を参照してください。

req.acceptsEncodings(encoding [, ...])

リクエストの Accept-Encoding HTTP ヘッダーフィールドに基づいて、指定されたエンコーディングの最初に受け入れられたエンコーディングを返します。指定されたエンコーディングのいずれも受け入れられない場合は、false を返します。

詳細、問題、または懸念がある場合は、accepts を参照してください。

req.acceptsLanguages([lang, ...])

リクエストの Accept-Language HTTP ヘッダーフィールドに基づいて、指定された言語の最初に受け入れられた言語を返します。指定された言語のいずれも受け入れられない場合は、false を返します。

lang 引数が指定されていない場合、req.acceptsLanguages() は、HTTP Accept-Language ヘッダーからすべての言語を Array として返します。

詳細、問題、または懸念がある場合は、accepts を参照してください。

Express (4.x) ソース: request.js 179行目

Accepts (1.3) ソース: index.js 195行目

req.get(field)

指定された HTTP リクエストヘッダーフィールドを返します (大文字と小文字を区別しない一致)。Referrer フィールドと Referer フィールドは交換可能です。

req.get('Content-Type')
// => "text/plain"

req.get('content-type')
// => "text/plain"

req.get('Something')
// => undefined

req.header(field) としてエイリアスされます。

req.is(type)

着信リクエストの "Content-Type" HTTP ヘッダーフィールドが type パラメータで指定された MIME タイプと一致する場合、一致するコンテンツタイプを返します。リクエストに本文がない場合は、null を返します。それ以外の場合は false を返します。

// With Content-Type: text/html; charset=utf-8
req.is('html')
// => 'html'
req.is('text/html')
// => 'text/html'
req.is('text/*')
// => 'text/*'

// When Content-Type is application/json
req.is('json')
// => 'json'
req.is('application/json')
// => 'application/json'
req.is('application/*')
// => 'application/*'

req.is('html')
// => false

詳細、問題、または懸念がある場合は、type-is を参照してください。

req.param(name [, defaultValue])

パラメータ name が存在する場合、その値を返します。

// ?name=tobi
req.param('name')
// => "tobi"

// POST name=tobi
req.param('name')
// => "tobi"

// /user/tobi for /user/:name
req.param('name')
// => "tobi"

ルックアップは次の順序で実行されます

• req.params
• req.body
• req.query

オプションで、パラメータがいずれのリクエストオブジェクトにも見つからない場合に、デフォルト値を設定するために defaultValue を指定できます。

req.range(size[, options])

Range ヘッダーパーサー。

size パラメータは、リソースの最大サイズです。

options パラメータは、次のプロパティを持つことができるオブジェクトです。

範囲の配列が返されるか、解析エラーを示す負の数が返されます。

• -2 は、不正なヘッダー文字列を示します
• -1 は、満たされない範囲を示します

// parse header from request
var range = req.range(1000)

// the type of the range
if (range.type === 'bytes') {
  // the ranges
  range.forEach(function (r) {
    // do something with r.start and r.end
  })
}

res.app

このプロパティは、ミドルウェアを使用しているExpressアプリケーションのインスタンスへの参照を保持します。

res.app は、リクエストオブジェクトの req.app プロパティと同じです。

res.headersSent

アプリがレスポンスの HTTP ヘッダーを送信したかどうかを示すブール値プロパティ。

app.get('/', function (req, res) {
  console.dir(res.headersSent) // false
  res.send('OK')
  console.dir(res.headersSent) // true
})

res.locals

res.render でレンダリングされたテンプレートでアクセスできる変数を設定するには、このプロパティを使用します。res.locals に設定された変数は、単一のリクエスト/レスポンスサイクル内で利用でき、リクエスト間で共有されません。

リクエスト間のテンプレートレンダリングで使用するためにローカル変数を保持するには、代わりに app.locals を使用します。

このプロパティは、リクエストパス名、認証されたユーザー、ユーザー設定などのリクエストレベルの情報を、アプリケーション内でレンダリングされたテンプレートに公開するのに役立ちます。

app.use(function (req, res, next) {
  // Make `user` and `authenticated` available in templates
  res.locals.user = req.user
  res.locals.authenticated = !req.user.anonymous
  next()
})

res.append(field [, value])

指定された value を HTTP レスポンスヘッダー field に追加します。ヘッダーがまだ設定されていない場合は、指定された値でヘッダーを作成します。value パラメータは、文字列または配列にすることができます。

注: res.append() の後に res.set() を呼び出すと、以前に設定されたヘッダー値がリセットされます。

res.append('Link', ['<https://127.0.0.1/>', '<https://127.0.0.1:3000/>'])
res.append('Set-Cookie', 'foo=bar; Path=/; HttpOnly')
res.append('Warning', '199 Miscellaneous warning')

res.attachment([filename])

HTTP レスポンスの Content-Disposition ヘッダーフィールドを “attachment” に設定します。filename が指定されている場合、res.type() を介して拡張子名に基づいて Content-Type を設定し、Content-Disposition "filename=" パラメータを設定します。

res.attachment()
// Content-Disposition: attachment

res.attachment('path/to/logo.png')
// Content-Disposition: attachment; filename="logo.png"
// Content-Type: image/png

res.cookie(name, value [, options])

クッキー name を value に設定します。value パラメータは、JSON に変換された文字列またはオブジェクトにすることができます。

options パラメータは、次のプロパティを持つことができるオブジェクトです。

例:

res.cookie('name', 'tobi', { domain: '.example.com', path: '/admin', secure: true })
res.cookie('rememberme', '1', { expires: new Date(Date.now() + 900000), httpOnly: true })

res.cookie を複数回呼び出すことで、単一のレスポンスで複数のクッキーを設定できます。例:

res
  .status(201)
  .cookie('access_token', 'Bearer ' + token, {
    expires: new Date(Date.now() + 8 * 3600000) // cookie will be removed after 8 hours
  })
  .cookie('test', 'test')
  .redirect(301, '/admin')

encode オプションを使用すると、クッキー値のエンコードに使用する関数を選択できます。非同期関数はサポートしていません。

使用例: 組織内の別のサイトにドメイン全体のクッキーを設定する必要がある場合。この別のサイト（管理下にはない）は、URIエンコードされたクッキー値を使用していません。

// Default encoding
res.cookie('some_cross_domain_cookie', 'http://mysubdomain.example.com', { domain: 'example.com' })
// Result: 'some_cross_domain_cookie=http%3A%2F%2Fmysubdomain.example.com; Domain=example.com; Path=/'

// Custom encoding
res.cookie('some_cross_domain_cookie', 'http://mysubdomain.example.com', { domain: 'example.com', encode: String })
// Result: 'some_cross_domain_cookie=http://mysubdomain.example.com; Domain=example.com; Path=/;'

maxAgeオプションは、現在の時刻からの相対的なミリ秒単位で "expires" を設定するための便利なオプションです。以下は、上記の2番目の例と同等です。

res.cookie('rememberme', '1', { maxAge: 900000, httpOnly: true })

valueパラメータとしてオブジェクトを渡すことができます。その場合、JSONとしてシリアライズされ、bodyParser()ミドルウェアによって解析されます。

res.cookie('cart', { items: [1, 2, 3] })
res.cookie('cart', { items: [1, 2, 3] }, { maxAge: 900000 })

cookie-parserミドルウェアを使用する場合、このメソッドは署名付きクッキーもサポートします。signedオプションをtrueに設定するだけです。すると、res.cookie()はcookieParser(secret)に渡された秘密鍵を使用して値を署名します。

res.cookie('name', 'tobi', { signed: true })

後で、この値にreq.signedCookieオブジェクトを通じてアクセスできます。

res.clearCookie(name [, options])

nameで指定されたクッキーをクリアします。optionsオブジェクトの詳細については、res.cookie()を参照してください。

res.cookie('name', 'tobi', { path: '/admin' })
res.clearCookie('name', { path: '/admin' })

res.download(path [, filename] [, options] [, fn])

pathにあるファイルを「添付ファイル」として転送します。通常、ブラウザはユーザーにダウンロードを促します。デフォルトでは、Content-Dispositionヘッダーの「filename=」パラメータはpath引数から派生しますが、filenameパラメータで上書きできます。pathが相対パスの場合、プロセスの現在の作業ディレクトリまたは、提供されている場合はrootオプションに基づいて決定されます。

次の表に、optionsパラメータの詳細を示します。

このメソッドは、転送が完了したとき、またはエラーが発生したときに、コールバック関数fn(err)を呼び出します。コールバック関数が指定され、エラーが発生した場合、コールバック関数は、リクエスト-レスポンスサイクルを終了するか、次のルートに制御を渡すことで、明示的にレスポンス処理を処理する必要があります。

res.download('/report-12345.pdf')

res.download('/report-12345.pdf', 'report.pdf')

res.download('/report-12345.pdf', 'report.pdf', function (err) {
  if (err) {
    // Handle error, but keep in mind the response may be partially-sent
    // so check res.headersSent
  } else {
    // decrement a download credit, etc.
  }
})

res.end([data] [, encoding])

レスポンス処理を終了します。このメソッドは実際にはNodeコア、具体的にはhttp.ServerResponseのresponse.end()メソッドから来ています。

データを伴わずにレスポンスをすばやく終了するために使用します。データで応答する必要がある場合は、代わりにres.send()やres.json()などのメソッドを使用してください。

res.end()
res.status(404).end()

res.format(object)

リクエストオブジェクトに存在する場合、Accept HTTPヘッダーでコンテンツネゴシエーションを実行します。品質値で順序付けられた許容可能なタイプに基づいて、リクエストのハンドラーを選択するためにreq.accepts()を使用します。ヘッダーが指定されていない場合、最初のコールバックが呼び出されます。一致が見つからない場合、サーバーは406 "Not Acceptable" で応答するか、defaultコールバックを呼び出します。

コールバックが選択されると、Content-Type応答ヘッダーが設定されます。ただし、res.set()やres.type()などのメソッドを使用して、コールバック内でこれを変更できます。

次の例では、Acceptヘッダーフィールドが "application/json" または "*/json" に設定されている場合、{ "message": "hey" }で応答します（ただし、"*/ *" の場合は、応答は "hey" になります）。

res.format({
  'text/plain': function () {
    res.send('hey')
  },

  'text/html': function () {
    res.send('<p>hey</p>')
  },

  'application/json': function () {
    res.send({ message: 'hey' })
  },

  default: function () {
    // log the request and respond with 406
    res.status(406).send('Not Acceptable')
  }
})

正規化されたMIMEタイプに加えて、これらのタイプにマッピングされた拡張子名を使用して、少し冗長ではない実装を行うこともできます。

res.format({
  text: function () {
    res.send('hey')
  },

  html: function () {
    res.send('<p>hey</p>')
  },

  json: function () {
    res.send({ message: 'hey' })
  }
})

res.get(field)

fieldで指定されたHTTP応答ヘッダーを返します。一致は大文字と小文字を区別しません。

res.get('Content-Type')
// => "text/plain"

res.json([body])

JSON応答を送信します。このメソッドは、JSON.stringify()を使用してJSON文字列に変換されたパラメータである（正しいcontent-typeを持つ）レスポンスを送信します。

パラメータは、オブジェクト、配列、文字列、ブール値、数値、またはnullなどの任意のJSON型にすることができ、他の値をJSONに変換するためにも使用できます。

res.json(null)
res.json({ user: 'tobi' })
res.status(500).json({ error: 'message' })

res.jsonp([body])

JSONPサポート付きのJSON応答を送信します。このメソッドは、JSONPコールバックサポートを選択することを除いて、res.json()と同じです。

res.jsonp(null)
// => callback(null)

res.jsonp({ user: 'tobi' })
// => callback({ "user": "tobi" })

res.status(500).jsonp({ error: 'message' })
// => callback({ "error": "message" })

デフォルトでは、JSONPコールバック名は単純にcallbackです。jsonp callback name設定でこれを上書きします。

以下は、同じコードを使用したJSONP応答の例です

// ?callback=foo
res.jsonp({ user: 'tobi' })
// => foo({ "user": "tobi" })

app.set('jsonp callback name', 'cb')

// ?cb=foo
res.status(500).jsonp({ error: 'message' })
// => foo({ "error": "message" })

res.links(links)

パラメータのプロパティとして提供されたlinksを結合して、応答のLink HTTPヘッダーフィールドを設定します。

たとえば、次の呼び出しは

res.links({
  next: 'http://api.example.com/users?page=2',
  last: 'http://api.example.com/users?page=5'
})

次の結果が得られます

Link: <http://api.example.com/users?page=2>; rel="next",
      <http://api.example.com/users?page=5>; rel="last"

res.location(path)

応答のLocation HTTPヘッダーを指定されたpathパラメータに設定します。

res.location('/foo/bar')
res.location('http://example.com')
res.location('back')

"back"のpath値には特別な意味があり、リクエストのRefererヘッダーで指定されたURLを参照します。Refererヘッダーが指定されていない場合は、"/"を参照します。

res.redirect([status,] path)

指定されたpathから派生したURLに、指定されたstatus（HTTPステータスコードに対応する正の整数）を使用してリダイレクトします。指定しない場合、statusはデフォルトで "302 Found" になります。

res.redirect('/foo/bar')
res.redirect('http://example.com')
res.redirect(301, 'http://example.com')
res.redirect('../login')

リダイレクトは、別のサイトにリダイレクトするための完全修飾URLにすることができます。

res.redirect('http://google.com')

リダイレクトは、ホスト名のルートに対して相対的に行うことができます。たとえば、アプリケーションがhttp://example.com/admin/post/newにある場合、以下はURL http://example.com/adminにリダイレクトされます。

res.redirect('/admin')

リダイレクトは、現在のURLに対して相対的に行うことができます。たとえば、http://example.com/blog/admin/（末尾のスラッシュに注意）から、以下はURL http://example.com/blog/admin/post/newにリダイレクトされます。

res.redirect('post/new')

http://example.com/blog/admin（末尾のスラッシュなし）からpost/newにリダイレクトすると、http://example.com/blog/post/newにリダイレクトされます。

上記のような動作がわかりにくい場合は、パスセグメントをディレクトリ（末尾にスラッシュ付き）とファイルと考えると、理解できるようになります。

パス相対リダイレクトも可能です。http://example.com/admin/post/newにいた場合、以下はhttp://example.com/admin/postにリダイレクトされます。

res.redirect('..')

backリダイレクトは、リクエストをリファラにリダイレクトし、リファラがない場合はデフォルトで/になります。

res.redirect('back')

res.render(view [, locals] [, callback])

viewをレンダリングし、レンダリングされたHTML文字列をクライアントに送信します。オプションのパラメータ

• locals、ビューのローカル変数を定義するプロパティを持つオブジェクト。
• callback、コールバック関数。提供された場合、このメソッドは発生する可能性のあるエラーとレンダリングされた文字列の両方を返しますが、自動応答は実行しません。エラーが発生した場合、このメソッドは内部的にnext(err)を呼び出します。

view引数は、レンダリングするビューファイルのファイルパスである文字列です。これは絶対パス、またはviews設定に対する相対パスにすることができます。パスにファイル拡張子が含まれていない場合、view engine設定によってファイル拡張子が決定されます。パスにファイル拡張子が含まれている場合、Expressは指定されたテンプレートエンジンのモジュールを（require()経由で）ロードし、ロードされたモジュールの__express関数を使用してレンダリングします。

詳細については、Expressでのテンプレートエンジンの使用を参照してください。

// send the rendered view to the client
res.render('index')

// if a callback is specified, the rendered HTML string has to be sent explicitly
res.render('index', function (err, html) {
  res.send(html)
})

// pass a local variable to the view
res.render('user', { name: 'Tobi' }, function (err, html) {
  // ...
})

res.req

res.send([body])

HTTP応答を送信します。

bodyパラメータには、Bufferオブジェクト、String、オブジェクト、Boolean、またはArrayを指定できます。例:

res.send(Buffer.from('whoop'))
res.send({ some: 'json' })
res.send('<p>some html</p>')
res.status(404).send('Sorry, we cannot find that!')
res.status(500).send({ error: 'something blew up' })

このメソッドは、単純な非ストリーミング応答のために多くの便利なタスクを実行します。たとえば、自動的にContent-Length HTTP応答ヘッダーフィールドを割り当て（以前に定義されていない場合）、自動HEADおよびHTTPキャッシュの新鮮度サポートを提供します。

パラメータがBufferオブジェクトの場合、このメソッドは、以下に示すように以前に定義されていない限り、Content-Type応答ヘッダーフィールドを "application/octet-stream" に設定します。

res.set('Content-Type', 'text/html')
res.send(Buffer.from('<p>some html</p>'))

パラメータがStringの場合、メソッドはContent-Typeを "text/html" に設定します。

res.send('<p>some html</p>')

パラメータがArrayまたはObjectの場合、ExpressはJSON表現で応答します。

res.send({ user: 'tobi' })
res.send([1, 2, 3])

res.sendFile(path [, options] [, fn])

指定されたpathにあるファイルを転送します。ファイル名の拡張子に基づいてContent-Type応答HTTPヘッダーフィールドを設定します。オプションオブジェクトでrootオプションが設定されていない限り、pathはファイルへの絶対パスである必要があります。

次の表に、optionsパラメータの詳細を示します。

このメソッドは、転送が完了したとき、またはエラーが発生したときに、コールバック関数fn(err)を呼び出します。コールバック関数が指定され、エラーが発生した場合、コールバック関数は、リクエスト-レスポンスサイクルを終了するか、次のルートに制御を渡すことで、明示的にレスポンス処理を処理する必要があります。

以下は、すべての引数を使用して res.sendFile を使用する例です。

app.get('/file/:name', function (req, res, next) {
  var options = {
    root: path.join(__dirname, 'public'),
    dotfiles: 'deny',
    headers: {
      'x-timestamp': Date.now(),
      'x-sent': true
    }
  }

  var fileName = req.params.name
  res.sendFile(fileName, options, function (err) {
    if (err) {
      next(err)
    } else {
      console.log('Sent:', fileName)
    }
  })
})

以下の例は、res.sendFile を使用して、ファイル配信をきめ細かく制御する方法を示しています。

app.get('/user/:uid/photos/:file', function (req, res) {
  var uid = req.params.uid
  var file = req.params.file

  req.user.mayViewFilesFrom(uid, function (yes) {
    if (yes) {
      res.sendFile('/uploads/' + uid + '/' + file)
    } else {
      res.status(403).send("Sorry! You can't see that.")
    }
  })
})

詳細情報や問題点、懸念事項がある場合は、send を参照してください。

res.sendStatus(statusCode)

レスポンスの HTTP ステータスコードを statusCode に設定し、登録されているステータスメッセージをテキストレスポンスボディとして送信します。不明なステータスコードが指定された場合、レスポンスボディはコード番号のみになります。

res.sendStatus(404)

HTTP ステータスコードの詳細

res.set(field [, value])

レスポンスの HTTP ヘッダー field を value に設定します。複数のフィールドを一度に設定するには、パラメーターとしてオブジェクトを渡します。

res.set('Content-Type', 'text/plain')

res.set({
  'Content-Type': 'text/plain',
  'Content-Length': '123',
  ETag: '12345'
})

res.header(field [, value]) というエイリアスもあります。

res.status(code)

レスポンスの HTTP ステータスを設定します。これは Node の response.statusCode のチェーナブルエイリアスです。

res.status(403).end()
res.status(400).send('Bad Request')
res.status(404).sendFile('/absolute/path/to/404.png')

res.type(type)

指定された type によって決定される MIME タイプに Content-Type HTTP ヘッダーを設定します。type に "/" 文字が含まれている場合は、Content-Type を type の正確な値に設定します。それ以外の場合は、ファイル拡張子と見なされ、MIME タイプは express.static.mime.lookup() メソッドを使用してマッピングで検索されます。

res.type('.html')
// => 'text/html'
res.type('html')
// => 'text/html'
res.type('json')
// => 'application/json'
res.type('application/json')
// => 'application/json'
res.type('png')
// => 'image/png'

res.vary(field)

Vary レスポンスヘッダーに、まだない場合はフィールドを追加します。

res.vary('User-Agent').render('docs')

router オブジェクトは、ミドルウェアとルートの独立したインスタンスです。これは、ミドルウェアとルーティング機能のみを実行できる「ミニアプリケーション」と考えることができます。すべての Express アプリケーションには、組み込みのアプリルーターがあります。

ルーター自体はミドルウェアのように動作するため、app.use() の引数として、または別のルーターの use() メソッドの引数として使用できます。

トップレベルの express オブジェクトには、新しい router オブジェクトを作成する Router() メソッドがあります。

ルーターオブジェクトを作成したら、アプリケーションと同じように、ミドルウェアと HTTP メソッドルート（get、put、post など）を追加できます。例:

// invoked for any requests passed to this router
router.use(function (req, res, next) {
  // .. some logic here .. like any other middleware
  next()
})

// will handle any request that ends in /events
// depends on where the router is "use()'d"
router.get('/events', function (req, res, next) {
  // ..
})

このようにして、ルートをファイルやミニアプリに分離して、特定のルート URL にルーターを使用できます。

// only requests to /calendar/* will be sent to our "router"
app.use('/calendar', router)

router.all(path, [callback, ...] callback)

このメソッドは、すべての HTTP メソッド（動詞）に一致する点を除いて、router.METHOD() メソッドとまったく同じです。

このメソッドは、特定のパスプレフィックスまたは任意の照合に対する「グローバル」ロジックをマッピングする場合に非常に便利です。たとえば、他のすべてのルート定義の先頭に次のルートを配置した場合、その時点からのすべてのルートで認証が必要になり、ユーザーが自動的にロードされます。これらのコールバックはエンドポイントとして機能する必要はないことに注意してください。loadUser はタスクを実行してから、next() を呼び出して後続のルートとの照合を継続できます。

router.all('*', requireAuthentication, loadUser)

または、同等の

router.all('*', requireAuthentication)
router.all('*', loadUser)

もう 1 つの例は、ホワイトリストに登録された「グローバル」機能です。ここでの例は以前とよく似ていますが、「/api」で始まるパスのみを制限します。

router.all('/api/*', requireAuthentication)

router.METHOD(path, [callback, ...] callback)

router.METHOD() メソッドは、Express のルーティング機能を提供します。ここで、METHOD は HTTP メソッド（GET、PUT、POST など）の 1 つであり、小文字で指定します。したがって、実際のメソッドは router.get()、router.post()、router.put() などです。

複数のコールバックを指定でき、すべて同じように扱われ、ミドルウェアとまったく同じように動作します。ただし、これらのコールバックは next('route') を呼び出して、残りのルートコールバックをバイパスする場合があります。このメカニズムを使用して、ルートの事前条件を実行し、一致したルートの処理を進める理由がない場合に後続のルートに制御を渡すことができます。

次のスニペットは、可能な限り最も単純なルート定義を示しています。Express は、パス文字列を正規表現に変換し、着信リクエストのマッチングに内部的に使用します。クエリ文字列は、これらのマッチングを実行する際には考慮されません。たとえば、「GET /」は次のルートに一致し、「GET /?name=tobi」も同様です。

router.get('/', function (req, res) {
  res.send('hello world')
})

また、正規表現を使用することもできます。これは、非常に具体的な制約がある場合に役立ちます。たとえば、次のものは「GET /commits/71dbb9c」と「GET /commits/71dbb9c..4c084f9」の両方に一致します。

router.get(/^\/commits\/(\w+)(?:\.\.(\w+))?$/, function (req, res) {
  var from = req.params[0]
  var to = req.params[1] || 'HEAD'
  res.send('commit range ' + from + '..' + to)
})

router.param(name, callback)

ルートパラメーターにコールバックトリガーを追加します。ここで、name はパラメーターの名前であり、callback はコールバック関数です。name は技術的にはオプションですが、このメソッドを省略して使用することは Express v4.11.0 以降では非推奨となっています（下記を参照）。

コールバック関数のパラメーターは次のとおりです。

• req、リクエストオブジェクト。
• res、レスポンスオブジェクト。
• next、次のミドルウェア関数を示します。
• name パラメーターの値。
• パラメーターの名前。

たとえば、ルートパスに:userが存在する場合、ユーザーロードロジックをマッピングして、req.userをルートに自動的に提供したり、パラメーター入力の検証を実行したりできます。

router.param('user', function (req, res, next, id) {
  // try to get the user details from the User model and attach it to the request object
  User.find(id, function (err, user) {
    if (err) {
      next(err)
    } else if (user) {
      req.user = user
      next()
    } else {
      next(new Error('failed to load user'))
    }
  })
})

パラメーターコールバック関数は、定義されているルーターにローカルです。それらは、マウントされたアプリまたはルーターによって継承されません。したがって、router で定義されたパラメーターコールバックは、router ルートで定義されたルートパラメーターでのみトリガーされます。

パラメーターコールバックは、次の例に示すように、パラメーターが複数のルートで一致した場合でも、リクエスト/レスポンスサイクルで 1 回だけ呼び出されます。

router.param('id', function (req, res, next, id) {
  console.log('CALLED ONLY ONCE')
  next()
})

router.get('/user/:id', function (req, res, next) {
  console.log('although this matches')
  next()
})

router.get('/user/:id', function (req, res) {
  console.log('and this matches too')
  res.end()
})

GET /user/42では、以下が出力されます

CALLED ONLY ONCE
although this matches
and this matches too

router.param(name, callback) メソッドの動作は、関数のみを router.param() に渡すことで完全に変更できます。この関数は、router.param(name, callback) がどのように動作するかを示すカスタム実装であり、2 つのパラメーターを受け取り、ミドルウェアを返す必要があります。

この関数の最初のパラメーターは、キャプチャする必要があるURLパラメーターの名前であり、2番目のパラメーターは、ミドルウェアの実装を返すために使用される可能性のある任意のJavaScriptオブジェクトです。

関数によって返されるミドルウェアは、URLパラメーターがキャプチャされたときの動作を決定します。

この例では、router.param(name, callback) シグネチャは router.param(name, accessId) に変更されています。router.param() は、名前とコールバックを受け取る代わりに、名前と数値を受け取るようになります。

var express = require('express')
var app = express()
var router = express.Router()

// customizing the behavior of router.param()
router.param(function (param, option) {
  return function (req, res, next, val) {
    if (val === option) {
      next()
    } else {
      res.sendStatus(403)
    }
  }
})

// using the customized router.param()
router.param('id', '1337')

// route to trigger the capture
router.get('/user/:id', function (req, res) {
  res.send('OK')
})

app.use(router)

app.listen(3000, function () {
  console.log('Ready')
})

この例では、router.param(name, callback) シグネチャは同じままですが、ミドルウェアコールバックの代わりに、ユーザー ID のデータ型を検証するためのカスタムデータ型チェック関数が定義されています。

router.param(function (param, validator) {
  return function (req, res, next, val) {
    if (validator(val)) {
      next()
    } else {
      res.sendStatus(403)
    }
  }
})

router.param('id', function (candidate) {
  return !isNaN(parseFloat(candidate)) && isFinite(candidate)
})

router.route(path)

オプションのミドルウェアを使用して HTTP 動詞を処理するために使用できる単一のルートのインスタンスを返します。router.route() を使用して、ルート名の重複を回避し、それによって入力エラーを回避します。

上記の router.param() の例に基づいて、次のコードは router.route() を使用してさまざまな HTTP メソッドハンドラーを指定する方法を示しています。

var router = express.Router()

router.param('user_id', function (req, res, next, id) {
  // sample user, would actually fetch from DB, etc...
  req.user = {
    id: id,
    name: 'TJ'
  }
  next()
})

router.route('/users/:user_id')
  .all(function (req, res, next) {
    // runs for all HTTP verbs first
    // think of it as route specific middleware!
    next()
  })
  .get(function (req, res, next) {
    res.json(req.user)
  })
  .put(function (req, res, next) {
    // just an example of maybe updating the user
    req.user.name = req.params.name
    // save user ... etc
    res.json(req.user)
  })
  .post(function (req, res, next) {
    next(new Error('not implemented'))
  })
  .delete(function (req, res, next) {
    next(new Error('not implemented'))
  })

このアプローチでは、単一の /users/:user_id パスを再利用し、さまざまな HTTP メソッドのハンドラーを追加します。

router.use([path], [function, ...] function)

指定されたミドルウェア関数（または複数関数）を、オプションのマウントパス path で使用します。path のデフォルトは「/」です。

このメソッドは app.use() と似ています。簡単な例とユースケースを以下に説明します。詳細については、app.use() を参照してください。

ミドルウェアは配管パイプのようなものです。リクエストは、最初に定義されたミドルウェア関数から始まり、一致するパスごとにミドルウェアスタックを「下って」処理されます。

var express = require('express')
var app = express()
var router = express.Router()

// simple logger for this router's requests
// all requests to this router will first hit this middleware
router.use(function (req, res, next) {
  console.log('%s %s %s', req.method, req.url, req.path)
  next()
})

// this will only be invoked if the path starts with /bar from the mount point
router.use('/bar', function (req, res, next) {
  // ... maybe some additional /bar logging ...
  next()
})

// always invoked
router.use(function (req, res, next) {
  res.send('Hello World')
})

app.use('/foo', router)

app.listen(3000)

「マウント」パスは削除され、ミドルウェア関数には表示されません。この機能の主な効果は、マウントされたミドルウェア関数が「プレフィックス」パス名に関係なく、コード変更なしで動作できることです。

router.use() でミドルウェアを定義する順序は非常に重要です。それらは順番に呼び出されるため、順序によってミドルウェアの優先順位が決まります。たとえば、通常、ロガーは最初に使用するミドルウェアであり、すべてのリクエストがログに記録されるようにします。

var logger = require('morgan')
var path = require('path')

router.use(logger())
router.use(express.static(path.join(__dirname, 'public')))
router.use(function (req, res) {
  res.send('Hello')
})

次に、静的ファイルのログ記録リクエストを無視するが、logger() の後に定義されたルートとミドルウェアのログ記録を続行するとします。express.static() の呼び出しを先頭に移動して、ロガーミドルウェアを追加する前に移動するだけです。

router.use(express.static(path.join(__dirname, 'public')))
router.use(logger())
router.use(function (req, res) {
  res.send('Hello')
})

もう 1 つの例は、複数のディレクトリからファイルを提供し、「./public」を他のディレクトリよりも優先することです。

router.use(express.static(path.join(__dirname, 'public')))
router.use(express.static(path.join(__dirname, 'files')))
router.use(express.static(path.join(__dirname, 'uploads')))

router.use() メソッドは、名前付きパラメーターもサポートしているため、他のルーターのマウントポイントで、名前付きパラメーターを使用したプリロードのメリットを得ることができます。

注：これらのミドルウェア関数は特定のルーターを介して追加されますが、それらがいつ実行されるかは、（ルーターではなく）アタッチされているパスによって定義されます。したがって、あるルーターを介して追加されたミドルウェアは、そのルートが一致する場合、他のルーターでも実行される可能性があります。たとえば、このコードは、同じパスにマウントされた 2 つの異なるルーターを示しています。

var authRouter = express.Router()
var openRouter = express.Router()

authRouter.use(require('./authenticate').basic(usersdb))

authRouter.get('/:user_id/edit', function (req, res, next) {
  // ... Edit user UI ...
})
openRouter.get('/', function (req, res, next) {
  // ... List users ...
})
openRouter.get('/:user_id', function (req, res, next) {
  // ... View user ...
})

app.use('/users', authRouter)
app.use('/users', openRouter)

認証ミドルウェアは authRouter を介して追加されましたが、両方のルーターが /users にマウントされているため、openRouter によって定義されたルートでも実行されます。この動作を回避するには、ルーターごとに異なるパスを使用してください。