Express 3.x はもはやメンテナンスされていません

3.x の既知および未知のセキュリティとパフォーマンスの問題は、最後の更新（2015年8月1日）以降対処されていません。最新バージョンの Express を使用することを強くお勧めします。

3.x API

express()

Express アプリケーションを作成します。 express() 関数は、_express_ モジュールによってエクスポートされるトップレベル関数です。

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

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

app.listen(3000)

アプリケーション

app.set(name, value)

設定 _name_ を _value_ に割り当てます。

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

app.get(name)

設定 _name_ の値を取得します。

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

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

app.enable(name)

設定 _name_ を _true_ に設定します。

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

app.disable(name)

設定 _name_ を _false_ に設定します。

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

app.enabled(name)

設定 _name_ が有効になっているかどうかを確認します。

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

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

app.disabled(name)

設定 _name_ が無効になっているかどうかを確認します。

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

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

app.configure([env], callback)

_env_ が app.get('env') つまり process.env.NODE_ENV と一致する場合、条件付きで _callback_ を呼び出します。このメソッドはレガシーな理由で残されており、事実上、以下のスニペットに示すように _if_ ステートメントです。これらの関数は、app.set() やその他の構成メソッドを使用するために _必要ありません_。

// all environments
app.configure(function () {
  app.set('title', 'My Application')
})

// development only
app.configure('development', function () {
  app.set('db uri', 'localhost/dev')
})

// production only
app.configure('production', function () {
  app.set('db uri', 'n.n.n.n/prod')
})

事実上、以下の糖衣構文です

// all environments
app.set('title', 'My Application')

// development only
if (app.get('env') === 'development') {
  app.set('db uri', 'localhost/dev')
}

// production only
if (app.get('env') === 'production') {
  app.set('db uri', 'n.n.n.n/prod')
}

app.use([path], function)

指定されたミドルウェア _function_ を、オプションのマウント _path_（デフォルトは "/"）で使用します。

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

// simple logger
app.use(function (req, res, next) {
  console.log('%s %s', req.method, req.url)
  next()
})

// respond
app.use(function (req, res, next) {
  res.send('Hello World')
})

app.listen(3000)

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

ルートは、そのパスの直後に「/」または「.」が続くパスと一致します。たとえば、app.use('/apple', ...) は _/apple_、_/apple/images_、_/apple/images/news_、_/apple.html_、_/apple.html.txt_ などと一致します。

具体的な例として、express.static() ミドルウェアを使用して ./public 内のファイルを配信するという典型的なユースケースを取り上げます。

// GET /javascripts/jquery.js
// GET /style.css
// GET /favicon.ico
app.use(express.static(path.join(__dirname, 'public')))

たとえば、すべての静的ファイルに "/static" というプレフィックスを付けたい場合は、「マウント」機能を使用してこれをサポートできます。マウントされたミドルウェア関数は、req.url にこのプレフィックスが含まれていない限り呼び出され _ません_。その時点で、関数が呼び出されるときに削除されます。これはこの関数にのみ影響し、後続のミドルウェアは、それらもマウントされていない限り、"/static" が含まれた req.url を認識します。

// GET /static/javascripts/jquery.js
// GET /static/style.css
// GET /static/favicon.ico
app.use('/static', express.static(path.join(__dirname, 'public')))

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

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

ここで、静的ファイルのリクエストのログ記録を無視したいが、logger() の後に定義されたルートとミドルウェアのログ記録を続行したい場合は、単に static() を上に移動します。

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

別の具体的な例として、複数のディレクトリからファイルを配信し、「./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')))

設定

Express の動作を変更するために、以下の設定が提供されています。

env 環境モード。デフォルトは process.env.NODE_ENV または "development"
trust proxy リバースプロキシのサポートを有効にします。デフォルトでは無効になっています。
jsonp callback name ?callback= のデフォルトのコールバック名を変更します。
json replacer JSON 置換コールバック。デフォルトは null です。
json spaces フォーマット用の JSON レスポンススペース。開発環境ではデフォルトで 2、本番環境では 0 です。
case sensitive routing 大文字と小文字の区別を有効にします。デフォルトでは無効になっており、"/Foo" と "/foo" は同じものとして扱われます。
strict routing 厳密なルーティングを有効にします。デフォルトでは、"/foo" と "/foo/" はルーターによって同じものとして扱われます。
view cache ビューテンプレートのコンパイルキャッシュを有効にします。本番環境ではデフォルトで有効になっています。
view engine 省略された場合に使用するデフォルトのエンジン拡張子
views ビューディレクトリパス。デフォルトは "process.cwd() + '/views'" です。

app.engine(ext, callback)

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

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

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

.__express を提供していないエンジン、または異なる拡張子をテンプレートエンジンに「マッピング」したい場合は、このメソッドを使用できます。たとえば、EJS テンプレートエンジンを ".html" ファイルにマッピングします。

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

この場合、EJS は Express が期待するシグネチャ (path, options, callback) と同じシグネチャを持つ .renderFile() メソッドを提供します。ただし、このメソッドは内部で ejs.__express としてエイリアスされているため、".ejs" 拡張子を使用している場合は何もする必要はありません。

一部のテンプレートエンジンはこの規則に従っていません。consolidate.js ライブラリは、node の一般的なすべてのテンプレートエンジンをこの規則に従うようにマッピングするために作成されたため、Express 内でシームレスに動作させることができます。

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

app.param([name], callback)

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

以下のスニペットは、_callback_ がミドルウェアとよく似ていることを示しています。したがって、非同期操作をサポートしますが、ここでは _id_ という名前のパラメータの追加値を提供します。次に、ユーザーを読み込もうとし、req.user を割り当てます。そうでない場合は、next(err) にエラーを渡します。

app.param('user', function (req, res, next, id) {
  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'))
    }
  })
})

または、_callback_ のみを渡すこともできます。その場合、app.param() API を変更できます。たとえば、express-params は、パラメータを特定の正規表現に制限できる次のコールバックを定義します。

この例は少し高度で、2 番目の引数が正規表現かどうかをチェックし、「user」パラメータの例とよく似た動作をするコールバックを返します。

app.param(function (name, fn) {
  if (fn instanceof RegExp) {
    return function (req, res, next, val) {
      var captures
      if ((captures = fn.exec(String(val)))) {
        req.params[name] = captures
        next()
      } else {
        next('route')
      }
    }
  }
})

このメソッドを使用して、パラメータを効果的に検証したり、解析してキャプチャグループを提供したりできるようになりました。

app.param('id', /^\d+$/)

app.get('/user/:id', function (req, res) {
  res.send('user ' + req.params.id)
})

app.param('range', /^(\w+)\.\.(\w+)?$/)

app.get('/range/:range', function (req, res) {
  var range = req.params.range
  res.send('from ' + range[1] + ' to ' + range[2])
})

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

app.VERB() メソッドは Express でルーティング機能を提供します。ここで、**VERB** は app.post() などの HTTP 動詞の 1 つです。複数のコールバックを指定できます。すべてが同等に扱われ、ミドルウェアと同様に動作します。唯一の例外は、これらのコールバックが next('route') を呼び出して残りのルートコールバックをバイパスできることです。このメカニズムを使用して、ルートで事前条件を実行し、ルートと一致する理由がない場合に後続のルートに制御を渡すことができます。

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

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

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

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

リソースの読み込み、検証の実行などを行うミドルウェアを再利用するのに役立つ、複数のコールバックを渡すこともできます。

app.get('/user/:id', user.load, function () {
  // ...
})

これらのコールバックは配列内にも渡すことができ、これらの配列は渡されるときに単純にフラット化されます。

var middleware = [loadForum, loadThread]

app.get('/forum/:fid/thread/:tid', middleware, function () {
  // ...
})

app.post('/forum/:fid/thread/:tid', middleware, function () {
  // ...
})

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

このメソッドは app.VERB() メソッドと同様に機能しますが、すべての HTTP 動詞と一致します。

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

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

または、それと同等の

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

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

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

app.locals

アプリケーションローカル変数は、アプリケーション内でレンダリングされるすべてのテンプレートに提供されます。これは、テンプレートにヘルパー関数を提供したり、アプリケーションレベルのデータを提供したりするのに便利です。

app.locals.title = 'My App'
app.locals.strftime = require('strftime')

app.locals オブジェクトは JavaScript の Function で、オブジェクトと共に呼び出されると、プロパティを自身にマージし、既存のオブジェクトをローカル変数として公開する簡単な方法を提供します。

app.locals({
  title: 'My App',
  phone: '1-250-858-9990',
  email: 'me@myapp.com'
})

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

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

app.locals オブジェクトが最終的に Javascript の関数オブジェクトであることの結果として、name、apply、bind、call、arguments、length、constructor など、既存の（ネイティブの）名前付きプロパティを独自の変数名に再利用してはいけません。

app.locals({ name: 'My App' })

console.log(app.locals.name)
// => return 'app.locals' in place of 'My App' (app.locals is a Function !)
// => if name's variable is used in a template, a ReferenceError will be returned.

ネイティブの名前付きプロパティの完全なリストは、多くの仕様書に記載されています。JavaScript の仕様書では、元のプロパティが導入されており、その中には最新のエンジンでまだ認識されているものもあります。EcmaScript の仕様書では、それを基に構築され、プロパティのセットが正規化され、新しいプロパティが追加され、非推奨のプロパティが削除されています。興味があれば、関数とオブジェクトのプロパティを確認してください。

デフォルトでは、Express はアプリケーションレベルのローカル変数 settings を1つだけ公開します。

app.set('title', 'My App')
// use settings.title in a view

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

レンダリングされた文字列で応答するコールバックを使用して、view をレンダリングします。これは res.render() のアプリケーションレベルのバリアントであり、それ以外は同じように動作します。

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

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

app.routes

app.routes オブジェクトは、関連付けられた HTTP 動詞によってマッピングされたすべての定義済みルートを格納します。このオブジェクトは、イントロスペクション機能に使用できます。たとえば、Express はこれを内部でルーティングだけでなく、デフォルトの

OPTIONS

動作を提供するためにも使用します。ただし、app.options() が使用されている場合は例外です。アプリケーションまたはフレームワークは、このオブジェクトからルートを削除するだけでルートを削除することもできます。

console.log(app.routes) の出力

{ get:
   [ { path: '/',
       method: 'get',
       callbacks: [Object],
       keys: [],
       regexp: /^\/\/?$/i },
     { path: '/user/:id',
       method: 'get',
       callbacks: [Object],
       keys: [{ name: 'id', optional: false }],
       regexp: /^\/user\/(?:([^\/]+?))\/?$/i } ],
  delete:
   [ { path: '/user/:id',
       method: 'delete',
       callbacks: [Object],
       keys: [Object],
       regexp: /^\/user\/(?:([^\/]+?))\/?$/i } ] }

app.listen()

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

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

express() によって返される app は、実際には JavaScript の Function であり、リクエストを処理するためのコールバックとして Node の HTTP サーバーに渡されるように設計されています。これにより、アプリは HTTP サーバーや HTTPS サーバーを継承するのではなく、単なるコールバックであるため、同じコードベースでアプリの 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() メソッドは、単に便宜上定義されたメソッドです。HTTPS を使用する場合、または両方を提供する場合は、上記のテクニックを使用してください。

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

リクエスト

req オブジェクトは、Node 自身の request オブジェクトの拡張バージョンであり、すべての組み込みフィールドとメソッドをサポートしています。

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.query

このプロパティは、解析されたクエリ文字列を含むオブジェクトで、デフォルトで {} です。

// GET /search?q=tobi+ferret
console.dir(req.query.q)
// => 'tobi ferret'

// GET /shoes?order=desc&shoe[color]=blue&shoe[type]=converse
console.dir(req.query.order)
// => 'desc'

console.dir(req.query.shoe.color)
// => 'blue'

console.dir(req.query.shoe.type)
// => 'converse'

req.body

このプロパティは、解析されたリクエスト本文を含むオブジェクトです。この機能は bodyParser() ミドルウェアによって提供されますが、他の本文解析ミドルウェアもこの規則に従う場合があります。このプロパティは、bodyParser() が使用されている場合、デフォルトで {} です。

// POST user[name]=tobi&user[email]=tobi@learnboost.com
console.log(req.body.user.name)
// => "tobi"

console.log(req.body.user.email)
// => "tobi@learnboost.com"

// POST { "name": "tobi" }
console.log(req.body.name)
// => "tobi"

req.files

このプロパティは、アップロードされたファイルのオブジェクトです。この機能は bodyParser() ミドルウェアによって提供されますが、他の本文解析ミドルウェアもこの規則に従う場合があります。このプロパティは、bodyParser() が使用されている場合、デフォルトで {} です。

たとえば、**file** フィールドの名前が「image」で、ファイルがアップロードされた場合、req.files.image には次の File オブジェクトが含まれます。

{ size: 74643,
  path: '/tmp/8ef9c52abe857867fd0a4e9a819d1876',
  name: 'edge.png',
  type: 'image/png',
  hash: false,
  lastModifiedDate: Thu Aug 09 2012 20:07:51 GMT-0700 (PDT),
  _writeStream:
   { path: '/tmp/8ef9c52abe857867fd0a4e9a819d1876',
     fd: 13,
     writable: false,
     flags: 'w',
     encoding: 'binary',
     mode: 438,
     bytesWritten: 74643,
     busy: false,
     _queue: [],
     _open: [Function],
     drainable: true },
  length: [Getter],
  filename: [Getter],
  mime: [Getter] }

bodyParser() ミドルウェアは、内部で node-formidable モジュールを利用し、同じオプションを受け入れます。この例として、formidable オプションの keepExtensions があります。デフォルトは **false** で、この場合は「.png」拡張子がなく「/tmp/8ef9c52abe857867fd0a4e9a819d1876」というファイル名が返されます。これを有効にするには、他のオプションと同様に bodyParser() に渡します。

app.use(express.bodyParser({ keepExtensions: true, uploadDir: '/my/files' }))

req.param(name)

パラメータ 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

明確にするために、req.body、req.params、req.query への直接アクセスを優先する必要があります。ただし、各オブジェクトからの入力を本当に受け入れる場合は例外です。

req.route

ルートの元のパス文字列、生成された正規表現など、いくつかのプロパティを含む、現在一致している Route です。

app.get('/user/:id?', function (req, res) {
  console.dir(req.route)
})

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

{ path: '/user/:id?',
  method: 'get',
  callbacks: [ [Function] ],
  keys: [ { name: 'id', optional: true } ],
  regexp: /^\/user(?:\/([^\/]+?))?\/?$/i,
  params: [ id: '12' ] }

req.cookies

このオブジェクトを使用するには、cookieParser() ミドルウェアが必要です。ユーザーエージェントによって送信された Cookie が含まれています。Cookie が送信されない場合、デフォルトで {} です。

// Cookie: name=tj
console.log(req.cookies.name)
// => "tj"

req.signedCookies

このオブジェクトを使用するには、cookieParser(secret) ミドルウェアが必要です。ユーザーエージェントによって送信された、署名済みで、使用できる状態の Cookie が含まれています。署名付き Cookie は、開発者の意図を示すために別のオブジェクトに存在します。そうでない場合、req.cookie 値（なりすまししやすい）に悪意のある攻撃が仕掛けられる可能性があります。Cookie に署名しても、「隠された」状態になったり、暗号化されたりするわけではないことに注意してください。これは、改ざんを防ぐだけです（署名に使用される秘密鍵は非公開であるため）。署名付き Cookie が送信されない場合、デフォルトで {} です。

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

req.get(field)

大文字と小文字を区別しないリクエストヘッダー field を取得します。「Referrer」フィールドと「Referer」フィールドは交換可能です。

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

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

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

p req.header(field) のエイリアスです。

req.accepts(types)

指定された types が受け入れ可能かどうかを確認し、true の場合は最適な一致を返し、そうでない場合は undefined を返します。その場合は、406「Not Acceptable」で応答する必要があります。

type 値は、「application/json」などの単一の MIME タイプ文字列、「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')
// => undefined

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

req.accepted

品質の高い順に並べ替えられた、受け入れられたメディアタイプの配列を返します。

[ { value: 'application/json',
    quality: 1,
    type: 'application',
    subtype: 'json' },
   { value: 'text/html',
     quality: 0.5,
     type: 'text',
     subtype: 'html' } ]

req.is(type)

受信リクエストに「Content-Type」ヘッダーフィールドが含まれているかどうか、およびそれが指定された MIME type と一致するかどうかを確認します。

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

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

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

req.ip

リモートアドレス、または「trust proxy」が有効になっている場合はアップストリームアドレスを返します。

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

req.ips

「trust proxy」が true の場合、「X-Forwarded-For」IP アドレスリストを解析して配列を返します。そうでない場合は、空の配列が返されます。

たとえば、値が「client, proxy1, proxy2」の場合、「proxy2」が最も下流にある ["client", "proxy1", "proxy2"] という配列を受け取ります。

req.path

リクエスト URL のパス名を返します。

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

req.host

「Host」ヘッダーフィールドからホスト名（ポート番号なし）を返します。

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

req.fresh

リクエストが最新かどうかを確認します。つまり、最終更新日時や ETag がまだ一致しており、リソースが「最新」であることを示します。

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

req.stale

リクエストが古くなっているかどうかを確認します。つまり、最終更新日時や ETag が一致しておらず、リソースが「古い」ことを示します。

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

req.xhr

リクエストが「X-Requested-With」ヘッダーフィールドを「XMLHttpRequest」（jQuery など）に設定して発行されたかどうかを確認します。

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

req.protocol

TLS でリクエストされた場合は、プロトコル文字列「http」または「https」を返します。「trust proxy」設定が有効になっている場合、「X-Forwarded-Proto」ヘッダーフィールドが信頼されます。HTTPS を提供するリバースプロキシの背後で実行している場合は、これを有効にすることができます。

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

req.secure

TLS 接続が確立されているかどうかを確認します。これは、次の省略形です。

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

req.subdomains

サブドメインを配列として返します。

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

req.originalUrl

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

// GET /search?q=something
console.log(req.originalUrl)
// => "/search?q=something"

req.acceptedLanguages

品質の高い順に並べ替えられた、受け入れられた言語の配列を返します。

Accept-Language: en;q=.5, en-us
// => ['en-us', 'en']

req.acceptedCharsets

品質の高い順に並べ替えられた、受け入れられた文字セットの配列を返します。

Accept-Charset: iso-8859-5;q=.2, unicode-1-1;q=0.8
// => ['unicode-1-1', 'iso-8859-5']

req.acceptsCharset(charset)

指定された charset が受け入れ可能かどうかを確認します。

req.acceptsLanguage(lang)

指定された lang が受け入れ可能かどうかを確認します。

req.res

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

レスポンス

res オブジェクトは、Node 自身の response オブジェクトの拡張バージョンであり、すべての組み込みフィールドとメソッドをサポートしています。

res.status(code)

Node の res.statusCode= のチェーン可能なエイリアスです。

res.status(404).sendfile('path/to/404.png')

res.set(field, [value])

ヘッダー field を value に設定するか、オブジェクトを渡して複数のフィールドを一度に設定します。

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

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

res.header(field, [value]) のエイリアスです。

res.get(field)

大文字と小文字を区別しないレスポンスヘッダー field を取得します。

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

Cookie name を value に設定します。これは、文字列または JSON に変換されたオブジェクトにすることができます。path オプションのデフォルトは「/」です。

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

maxAge オプションは、「expires」を現在の時刻を基準とした相対時刻（ミリ秒単位）に設定するための便利なオプションです。以下は、前の例と同等です。

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

オブジェクトを渡すことができ、JSON としてシリアル化されます。これは bodyParser() ミドルウェアによって自動的に解析されます。

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

署名付き Cookie もこのメソッドでサポートされています。単に signed オプションを渡します。指定された場合、res.cookie() は express.cookieParser(secret) に渡された秘密鍵を使用して値に署名します。

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

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

res.clearCookie(name, [options])

Cookie name をクリアします。path オプションのデフォルトは「/」です。

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

res.redirect([status], url)

指定された url にリダイレクトします。オプションの status コードは、デフォルトで 302「Found」です。

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

Express は、いくつかの形式のリダイレクトをサポートしています。最初は、別のサイトにリダイレクトするための完全修飾 URI です。

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

2 番目の形式は、パス名相対リダイレクトです。たとえば、http://example.com/admin/post/new にいる場合、/admin への次のリダイレクトは http://example.com/admin に移動します。

res.redirect('/admin')

この次のリダイレクトは、アプリケーションのマウントポイントに対して相対的です。たとえば、ブログアプリケーションが /blog にマウントされている場合、理想的にはマウントされた場所を認識していないため、/admin/post/new のリダイレクトでは単に http://example.com/admin/post/new が返されますが、次のマウント相対リダイレクトでは http://example.com/blog/admin/post/new が返されます。

res.redirect('admin/post/new')

パス名相対リダイレクトも可能です。例えば、http://example.com/admin/post/new にいる場合、以下のリダイレクトは http//example.com/admin/post に移動します。

res.redirect('..')

最後の特殊ケースは back リダイレクトで、Referer（または Referrer）に戻ります。Referer がない場合はデフォルトで / にリダイレクトします。

res.redirect('back')

res.location

location ヘッダーを設定します。

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

res.redirect() と同じ種類の urls を使用できます。

例えば、アプリケーションが /blog にマウントされている場合、以下は location ヘッダーを /blog/admin に設定します。

res.location('admin')

res.charset

文字セットを割り当てます。デフォルトは「utf-8」です。

res.charset = 'value'
res.send('<p>some html</p>')
// => Content-Type: text/html; charset=value

res.send([body|status], [body])

レスポンスを送信します。

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

このメソッドは、Content-Length を自動的に割り当てる（事前に定義されていない場合）、自動的に *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])

最後に、前述のボディなしで Number が指定された場合、レスポンスボディ文字列が自動的に割り当てられます。例えば、200 はテキスト「OK」で応答し、404 は「Not Found」で応答します。

res.send(200)
res.send(404)
res.send(500)

res.json([status|body], [body])

JSON レスポンスを送信します。このメソッドは、オブジェクトまたは配列が渡された場合、res.send() と同じですが、オブジェクトではないもの（null、undefined など）を明示的に JSON に変換するために使用できます。ただし、これらは厳密には有効な JSON ではありません。

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

res.jsonp([status|body], [body])

JSONP をサポートする JSON レスポンスを送信します。このメソッドは res.json() と同じですが、JSONP コールバックサポートをオプトインします。

res.jsonp(null)
// => null

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

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

デフォルトでは、JSONP コールバック名は単に callback ですが、jsonp コールバック名設定で変更できます。以下は、同じコードを使用した JSONP レスポンスの例です。

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

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

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

res.type(type)

Content-Type を type の MIME ルックアップに設定します。または、「/」が存在する場合、Content-Type は単にこのリテラル値に設定されます。

res.type('.html')
res.type('html')
res.type('json')
res.type('application/json')
res.type('png')

res.contentType(type) のエイリアスです。

res.format(object)

リクエストの Accept ヘッダーフィールドが存在する場合、コンテンツネゴシエーションを実行します。このメソッドは、品質値で順序付けられた許容可能なタイプの配列である req.accepted を使用します。それ以外の場合は、最初のコールバックが呼び出されます。一致するものがない場合、サーバーは 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' })
  }
})

正規化された MIME タイプに加えて、これらのタイプにマップされた拡張子を使用することもできます。これにより、実装が少し簡潔になります。

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

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

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

res.attachment([filename])

Content-Disposition ヘッダーフィールドを「attachment」に設定します。filename が指定されている場合、Content-Type は res.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.sendfile(path, [options], [fn]])

指定された path のファイルを転送します。

ファイル名の拡張子に基づいて、Content-Type レスポンスヘッダーフィールドを自動的にデフォルト設定します。コールバック fn(err) は、転送が完了したとき、またはエラーが発生したときに呼び出されます。

オプション

maxAge ミリ秒単位、デフォルトは 0
root 相対ファイル名のルートディレクトリ

このメソッドは、次の例に示すように、ファイル配信のきめ細かいサポートを提供します。

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.send(403, 'Sorry! you cant see that.')
    }
  })
})

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

path のファイルを「添付ファイル」として転送します。通常、ブラウザはユーザーにダウンロードを促します。Content-Disposition の「filename=」パラメータ（ブラウザダイアログに表示されるパラメータ）は、デフォルトで path に設定されていますが、オーバーライド filename を指定できます。

エラーが発生した場合、または転送が完了した場合、オプションのコールバック fn が呼び出されます。このメソッドは、res.sendfile() を使用してファイルを転送します。

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, keep in mind the response may be partially-sent
    // so check res.headerSent
  } else {
    // decrement a download credit etc
  }
})

res.links(links)

指定された links を結合して、「Link」レスポンスヘッダーフィールドを設定します。

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.locals

レスポンスのローカル変数はリクエストのスコープであるため、そのリクエスト/レスポンスサイクル中にレンダリングされたビュー（存在する場合）でのみ使用できます。それ以外の場合、この API は app.locals と同じです。

このオブジェクトは、リクエストパス名、認証済みユーザー、ユーザー設定などのリクエストレベルの情報を公開するのに役立ちます。

app.use(function (req, res, next) {
  res.locals.user = req.user
  res.locals.authenticated = !req.user.anonymous
  next()
})

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

レンダリングされた文字列で応答するコールバックを使用して、view をレンダリングします。エラーが発生すると、next(err) が内部的に呼び出されます。コールバックが指定されている場合、発生する可能性のあるエラーとレンダリングされた文字列の両方が渡され、自動応答は実行されません。

res.render('index', function (err, html) {
  // ...
})

res.render('user', { name: 'Tobi' }, function (err, html) {
  // ...
})

res.req

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

ミドルウェア

basicAuth()

基本認証ミドルウェア。req.user にユーザー名を設定します。

単純なユーザー名とパスワード

app.use(express.basicAuth('username', 'password'))

コールバック検証

app.use(express.basicAuth(function (user, pass) {
  return user === 'tj' && pass === 'wahoo'
}))

fn(err, user) を受け入れる非同期コールバック検証。この場合、req.user は渡されたユーザーオブジェクトになります。

app.use(express.basicAuth(function (user, pass, fn) {
  User.authenticate({ user: user, pass: pass }, fn)
}))

bodyParser()

JSON、urlencoded、および multipart リクエストをサポートするリクエストボディ解析ミドルウェア。このミドルウェアは、単に json()、urlencoded()、および multipart() ミドルウェアのラッパーです。

app.use(express.bodyParser())

// is equivalent to:
app.use(express.json())
app.use(express.urlencoded())
app.use(express.multipart())

セキュリティのために、アプリケーションでファイルのアップロードが必要ない場合は、ファイルのアップロードを無効にすることをお勧めします。そのためには、必要なミドルウェアのみを使用します。つまり、bodyParser および multipart() ミドルウェアは使用しません。

app.use(express.json())
app.use(express.urlencoded())

アプリケーションでファイルのアップロードが必要な場合は、これらのファイルを処理するための戦略を設定する必要があります。

compress()

gzip / deflate でレスポンスデータを圧縮します。このミドルウェアは、すべてのレスポンスを圧縮できるように、スタック内で「上位」に配置する必要があります。

app.use(express.logger())
app.use(express.compress())
app.use(express.methodOverride())
app.use(express.bodyParser())

cookieParser()

Cookie ヘッダーフィールドを解析し、Cookie 名をキーとするオブジェクトで req.cookies に値を設定します。オプションで、secret 文字列を渡すことにより、署名付き Cookie サポートを有効にできます。

app.use(express.cookieParser())
app.use(express.cookieParser('some secret'))

cookieSession()

Cookie ベースのセッションを提供し、req.session に値を設定します。このミドルウェアは次のオプションを取ります。

key Cookie 名、デフォルトは connect.sess
secret Cookie の改ざんを防ぎます
cookie セッション Cookie の設定、デフォルトは { path: '/', httpOnly: true, maxAge: null }
proxy セキュア Cookie を設定するときにリバースプロキシを信頼する（「x-forwarded-proto」経由）

app.use(express.cookieSession())

Cookie をクリアするには、応答する前にセッションを null に設定します。

req.session = null

csrf()

CSRF 対策ミドルウェア。

デフォルトでは、このミドルウェアは「_csrf」という名前のトークンを生成します。これは、状態を変更するリクエストに、非表示のフォームフィールド、クエリ文字列などに追加する必要があります。このトークンは req.csrfToken() に対して検証されます。

デフォルトの value 関数は、bodyParser() ミドルウェアによって生成された req.body、query() によって生成された req.query、および「X-CSRF-Token」ヘッダーフィールドをチェックします。

このミドルウェアはセッションサポートを必要とするため、session() の下のどこかに追加する必要があります。

directory()

ディレクトリ配信ミドルウェア。指定された path を配信します。このミドルウェアは、static() と組み合わせてファイルを提供し、フル機能のファイルブラウザを提供できます。

app.use(express.directory('public'))
app.use(express.static('public'))

このミドルウェアは次のオプションを受け入れます。

hidden 隠し（ドット）ファイルを表示します。デフォルトは false です。
icons アイコンを表示します。デフォルトは false です。
filter このフィルター関数をファイルに適用します。デフォルトは false です。

3.x API

express()

アプリケーション

app.set(name, value)

app.get(name)

app.enable(name)

app.disable(name)

app.enabled(name)

app.disabled(name)

app.configure([env], callback)

app.use([path], function)

設定

app.engine(ext, callback)

app.param([name], callback)

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

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

app.locals

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

app.routes

app.listen()

リクエスト

req.params

req.query

req.body

req.files

req.param(name)

req.route

req.cookies

req.signedCookies

req.get(field)

req.accepts(types)

req.accepted

req.is(type)

req.ip

req.ips

req.path

req.host

req.fresh

req.stale

req.xhr

req.protocol

req.secure

req.subdomains

req.originalUrl

req.acceptedLanguages

req.acceptedCharsets

req.acceptsCharset(charset)

req.acceptsLanguage(lang)

req.res

レスポンス

res.status(code)

res.set(field, [value])

res.get(field)

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

res.clearCookie(name, [options])

res.redirect([status], url)

res.location

res.charset

res.send([body|status], [body])

res.json([status|body], [body])

res.jsonp([status|body], [body])

res.type(type)

res.format(object)

res.attachment([filename])

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

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

res.links(links)

res.locals

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

res.req

ミドルウェア

basicAuth()

bodyParser()

compress()

cookieParser()

cookieSession()

csrf()

directory()