npm でインストールします。
$ npm install express
今回は下記のバージョンで検証しています。
OS : Ubuntu 22.04 Node.js : v18.16.0 npm : v9.5.1 Express : v4.18.2
http://～/hello にアクセスすると Hello world を返却する簡単な使用例です。
const express = require("express");
const app = express();
app.get("/hello", (req, res) => {
res.send("Hello world\n");
});
app.listen(80);
サーバで main.js を起動します。
$ node main.js
クライアントから呼び出します。
$ curl http://127.0.0.1/hello Hello world
パス名にコロン(:)をつけるとパラメータとして受け取ることができます。
const express = require("express");
const app = express();
app.get("/hello/:name", (req, res) => {
console.log(req.params.name);
res.send("OK\n");
});
app.listen(80);
クライアントから次の様に呼び出します。
$ curl http://127.0.0.1/hello/Yamada
GET パラメータは req.query で受け取ります。
const express = require("express");
const app = express();
app.get("/hello", (req, res) => {
console.log(req.query.name);
console.log(req.query.age);
res.send("OK\n");
});
app.listen(80);
クライアントから次の様に呼び出します。
$ curl "http://127.0.0.1/hello?name=Yamada&age=36"
POST パラメータは express.urlencoded() を用いて受け取ります。
const express = require("express");
const app = express();
app.use(express.urlencoded({ extended: true }));
app.post("/hello", (req, res) => {
console.log(req.body.name);
console.log(req.body.age);
res.send("OK\n");
});
app.listen(80);
クライアントから次の様に呼び出します。
$ curl -X POST -d 'name=Yamada&age=36' http://127.0.0.1/hello
extended: true の場合はデコーダーとして qs を、extended: false の場合は querystring を使用します。qs ライブラリの場合は、name[1]=Taro, name[2]=Jiro などのデータを配列として解釈してくれます。
$ curl -X POST -d 'name[1]=Yamada&name[2]=Taro&age=36' http://127.0.0.1/hello
express.urlencoded() の部分は express のバージョンによって色々変更があります。元々は bodyDecoder() でしたが bodyParser() に名称変更し、Express4 では body-parser という別モジュールに切り出されたのですが、v4.16.0 で再度 express に同梱されました。
// 古い書き方(1): bodyDecoder時代 app.use(express.bodyDecoder()); // 古い書き方(2): Express3 bodyParser時代 app.use(express.bodyParser()); // 古い書き方(3): Express4前期 urlencoded + body-parser時代 var bodyParser = require("body-parser"); app.use(bodyParser.urlencoded({ extended: false })); // 新しい書き方: Express 4.16.0 以降 app.use(express.urlencoded({ extended: true }));
JSON データは express.json() を用いて受け取ります。res.json() を用いると JSON データを返却できます。
const express = require("express");
const app = express();
app.use(express.json())
app.post("/", (req, res) => {
console.log(req.body.name);
console.log(req.body.age);
res.json({status: "OK"});
});
app.listen(80);
クライアントから次の様に呼び出します。
$ curl -X POST -H "Content-Type: application/json" \
-d '{"name": "Yamada", "age": 36}' http://127.0.0.1/
EJS, Jade, Pug などのテンプレートエンジンを使用することができます。まず、EJS をインストールします。
$ npm install ejs
views フォルダを作成します。
$ mkdir views
views フォルダ内に test.ejs テンプレートを作成します。<%= var %> は var で指定した変数の値を表示します。
<!DOCTYPE html> <html> <head> <title>TEST</title> </head> <body> <p>Hello <%= name %></p> </body> </html>
Express からこれを呼び出します。
const express = require("express");
const app = express();
app.set("view engine", "ejs");
app.get("/", (req, res) => {
res.render("test", { name: "Yamada" });
});
app.listen(80);
express.static() を用いて特定フォルダ配下のファイルを HTML, CSS, JavaScript, 画像などのスタティックファイルとして返却することができます。
$ mkdir -p static/css static/js static/img
* { box-sizing: border-box; }
const express = require("express");
const app = express();
app.use(express.static("static"));
app.get("/hello", (req, res) => {
res.send("OK\n");
});
app.listen(80);
$ curl http://127.0.0.1/css/style.css
200 以外の HTTPステータスを返却するには res.status() を用います。
const express = require('express');
const app = express();
app.get("/", (req, res) => {
res.status(201).send("Created\n");
});
app.listen(80);
リクエストのHTTPヘッダを参照するには req.get() を、レスポンスのHTTPヘッダを設定するには res.append() を使用します。
const express = require('express');
const app = express();
app.get("/", (req, res) => {
console.log(req.get("Content-Type"));
res.append("Content-Type", "text/plain");
res.send("Created\n");
});
app.listen(80);
http://～/users/ 配下の処理は users.js で、http://～/groups/ 配下の処理は groups.js でなど、機能群に応じて実装ファイルを分割することができます。
const express = require("express");
const app = express();
app.use("/users", require("./users.js"));
app.use("/groups", require("./groups.js"));
app.listen(80);
const express = require("express");
const router = express.Router();
var users = [
{ name: "Tanaka", age: 36 },
{ name: "Suzuki", age: 42 },
{ name: "Yamada", age: 53 },
];
router.get("/", (req, res) => {
res.json(users);
});
module.exports = router;
$ curl http://127.0.0.1/users
POST データを受け取る際に必要な処理です。データを URLエンコーディングされたデータとして受け取り、req.body に格納します。v4.16.0 でサポートされました。(詳細)
app.use(express.urlencoded({ limit: "100kb" }));
データを JSON データとして解析し、req.body に格納します。クライアントは Content-Type ヘッダに application/json を指定します。v4.16.0 でサポートされました。(詳細)
app.use(express.json());
データをテキストデータとして受け取り、req.body に格納します。v4.17.0 でサポートされました。(詳細)
app.use(express.text({ defaultCharset: "utf-8" }));
データをバイナリデータとして受け取り、req.body に格納します。v4.17.0 でサポートされました。(詳細)
app.use(express.raw({ limit: "100kb" }));
root ディレクトリ配下のファイルをスタティックファイルとして返却します。(詳細)
app.use(express.static("static"));
Router オブジェクトを作成します。上記の 使用例 を参照してください。(詳細)
const router = express.Router();
router.get("/", (req, res) => {
res.json(users);
});
port で指定したポート番号でクライアントからのリクエストを待ち受けします。(詳細)
const express = require("express");
const app = express();
app.listen(8080);
port を省略すると適当なポート番号が自動割り当てされます。割り当てられたポート番号は listener.address().port で知ることができます。
const listener = app.listen(); console.log(listener.address().port);
host を指定するとバインドするネットワークインタフェースを指定することができます。
app.listen(8080, "127.0.0.1");
backlog には接続時の待ち受けキューの数を指定します。
app.listen(8080, "127.0.0.1", 10);
callback には接続開始時に呼ばれるコールバックを指定することができます。
app.listen(8080, (err) => {
if (err) {
console.log("ERROR");
} else {
console.log(`Start server.`);
}
});
GET メソッドに対応するハンドラを指定します。(詳細)
app.get("/users/:user_id", (req, res) => {
res.send(`Get user ${req.params.user_id}.\n`);
});
POST メソッドに対応するハンドラを指定します。(詳細)
app.post("/users", (req, res) => {
res.send(`Create user.\n`);
});
PUT メソッドに対応するハンドラを指定します。(詳細)
app.put("/users/:user_id", (req, res) => {
res.send(`Update user ${req.params.user_id}.\n`);
});
DELETE メソッドに対応するハンドラを指定します。(詳細)
app.delete("/users/:user_id", (req, res) => {
res.send(`Delete user ${req.params.user_id}.\n`);
});
GET, POST, PUT, DELETE などすべての HTTP メソッドに対して処理を行います。(詳細)
const express = require("express");
const app = express();
app.all("/", (req, res) => {
console.log(req.method);
res.send("OK\n");
});
app.listen(80);
path で始まる URL にアクセスされた際に呼び出されるミドルウェアコールバックを指定します。path を省略するとすべてのリクエストに対してミドルウェアを実行します。(詳細)
const express = require("express");
const app = express();
app.use("/", (req, res, next) => {
console.log("MIDDLEWARE");
next();
});
app.get("/admin", (req, res) => {
console.log("ADMIN");
res.send("OK\n");
});
app.listen(80);
callback には下記のようなサブアプリケーションを指定することもできます。book は http://～/books 配下の URL に対するアプリケーションを定義します。
const express = require('express');
const app = express();
const book = express();
app.use("/books", book);
book.get("/", (req, res) => {
res.send("OK\n");
});
app.listen(80);
app.use() で設定したアプリケーションの基準パスを返します。(詳細)
const express = require('express');
const app = express();
const book = express();
app.use("/books", book);
console.log(book.path()); // => /books
app.locals.name に設定した値をテンプレートエンジンで参照することができます。app.set() で設定した値は app.locals.settings に格納されます。app.locals に設定した値は次のリクエストでも保持されます。リクエスト内で有効な値を設定するには res.locals を用います。(詳細)
const express = require("express");
const app = express();
app.set("view engine", "ejs");
app.locals.foo = "FOO";
app.get("/", (req, res) => {
res.render("test");
});
app.listen(80);
<p><%= foo %></p>
メインパスに対してサブパスが設定されている場合、サブパスが適用されているパス名を返します。(詳細)
const express = require("express");
const app = express(); // メインパス
const admin = express(); // サブパス
app.use("/admin", admin);
admin.get("/", (req, res) => {
console.log(admin.mountpath); // => /admin
res.send("OK\n");
});
app.listen(80);
サブパスがマウントされた時に呼ばれます。parent には親の app が渡されます。(詳細)
const express = require("express");
const app = express();
const admin = express();
admin.on("mount", (parent) => {
console.log(parent);
});
app.use("/admin", admin);
拡張子 ext に対応するテンプレートエンジンを指定します。(詳細)
const ejs = require("ejs");
app.engine("ejs", ejs.renderFile);
テンプレートエンジンを用いてレンダリングします。res.redner() がレンダリングした結果をクライアントに返すのに対して、app.render() はレンダリング結果をコールバック関数で返却します。(詳細)
const express = require('express');
const app = express();
app.set('view engine', 'ejs');
app.render('test', { name: "Yamada" }, (err, html) => {
if (err) console.log(err);
console.log(html);
});
path に対して METHOD で指定したメソッドを受信した場合に callback を呼び出します。METHOD には get, post, put, delete, head など(下記参照)のうちひとつを指定します。(詳細)
checkout copy delete get head lock merge mkactivity mkcol move m-search notify options patch post purge put report search subscribe trace unlock unsubscribe
const express = require("express");
const app = express();
app.get("/", (req, res) => {
res.send("OK\n");
});
app.listen(80);
path に対するルートインスタンスを返却します。ルートインスタンスは .get(), .post(), .put(), .delete() および .all() などのメソッドを持ち、それぞれのメソッドに対する処理を行います。(詳細)
const express = require('express');
const app = express();
app.route("/")
.get((req, res, next) => {
res.send("GET\n");
})
.post((req, res, next) => {
res.send("POST\n");
})
.all((req, res, next) => {
res.send("ALL\n");
});
app.listen(80);
name で指定したパラメータに対する前処理を行います。下記の例では :user で受け取るユーザ名に対して [ ... ] で囲むといった前処理を行っています。(詳細)
const express = require('express');
const app = express();
app.param("user", (req, res, next, id) => {
req.params.user = "[" + req.params.user + "]";
next();
});
app.get("/users/:user", (req, res) => {
console.log(req.params.user);
res.send("OK\n");
});
app.listen(80);
リクエストメソッド(GET, POST, PUT, DELETE)を示します。(詳細)
// GET http://www.example.com/ console.log(req.method); // => GET
プロトコル(http, https)を示します。(詳細)
// http://www.example.com/ console.log(req.protocol); // => http
サーバのホスト名を示します。(詳細)
// http://foo.baa.example.com/ console.log(req.hostname); // => foo.baa.example.com
サーバのサブドメイン部の配列を返します。(詳細)
// http://foo.baa.example.com/ console.log(req.subdomains); // => ["baa", "foo"]
アクセスされたパス名を示します。?foo=FOO などの GETパラメータは除外されます。(詳細)
// http://www.example.com/hello?foo=FOO console.log(req.path); // => /hello
アクセスされたパス名を示します。?foo=FOO などの GETパラメータも含まれます。(詳細)
// http://www.example.com/hello?foo=FOO console.log(req.originalUrl); // => /hello?foo=FOO
app.get() などの第一引数で :name で指定されたパラメータを受け取ります。(詳細)
// http://www.example.com/groups/G123/U456 app.get("/groups/:group_id/:user_id", (req, res) => { res.send(req.params); // => {"group_id": "G123", "user_id": "U456"} });
パスパラメータ(URL の ? 以降に指定された key=value パラメータ)を示します。(詳細)
// http://www.example.com/hello?foo=FOO&baa=BAA app.get("/hello", (req, res) => { res.send(req.query); // => {"foo": "FOO", "baa": "BAA"} });
下記の例では URLエンコーディングされた POST パラメータを示します。(詳細)
app.use(express.urlencoded({ extended: true }));
app.post("/", (req, res) => {
res.send(req.body);
});
$ curl -X POST -d 'name=Yamada&age=26' http://127.0.0.1
{"name":"Yamada","age":"26"}
下記の例では POST された JSON データを示します。
app.use(express.json())
app.post("/", (req, res) => {
res.json(req.body);
});
$ curl -X POST -H "Content-Type: application/json" \
-d '{"name": "Yamada", "age": 26}' http://127.0.0.1
{"name":"Yamada","age":26}
リクエストに含まれる Cookie 情報を参照します。cookie-parser をインストールしてミドルウェアに組み込んでおく必要があります。(詳細)
$ npm install cookie-parser
const express = require("express");
const app = express();
const cookieParser = require("cookie-parser");
app.use(cookieParser());
app.get("/", (req, res) => {
res.send(req.cookies);
});
app.listen(80);
$ curl -H "Cookie: name=Yamada" http://127.0.0.1/
{"name":"Yamada"}
リクエストに含まれる署名付きCookie情報を返します。cookie-parser をインストールしてミドルウェアに組み込んでおく必要があります。(詳細)
console.log(req.signedCookies); // { "user: "...", ... }
このリクエストを処理しているアプリケーションを参照します。(詳細)
req.app.get("/", (req, res) => {
req.sender("OK\n");
});
app.use() で設定したアプリケーションの基準パスを参照します。(詳細)
const express = require('express');
const app = express();
const book = express();
app.use("/books", book);
book.get("/", (req, res) => {
console.log(req.baseUrl);
res.send("OK\n");
});
app.listen(80);
レスポンスがクライアントキャッシュ中にまだフレッシュな状態か否か true/false で返します。(詳細)
console.log(req.fresh); // true/false
リクエストが古い(stale)か否かを true/false で返します。(詳細)
console.log(req.fresh); // true/false
クライアントのIPアドレスを返します。trust proxy が true に設定されていて、X-Forwarded-For ヘッダがある場合はその一番左側アドレスを返します。(詳細)
app.set("trust proxy", true);
console.log(req.ip); // 192.168.100.1
クライアント、および通信経路のIPアドレスを返します。trust proxy が true に設定されていて、X-Forwarded-For ヘッダがある場合はそのアドレスを配列で返します。(詳細)
// X-Forwarded-For: 192.168.100.1, 192.168.200.1 app.set("trust proxy", true); console.log(req.ips); // ["192.168.100.1", "192.168.200.1"]
ルーティング情報を返します。(詳細)
console.log(req.route);
Route {
path: '/',
stack: [
Layer {
handle: [Function (anonymous)],
name: '<anonymous>',
params: undefined,
path: undefined,
keys: [],
regexp: /^\/?$/i,
method: 'get'
}
],
methods: { get: true }
}
通信がセキュアか否か (HTTPSを用いているか否か) を true/false で返します。(詳細)
console.log(req.secure); // => true or false
Ajax 通信か否かを示すための X-Requested-With ヘッダに XMLHttpRequest が設定されていれば true を、さもなくば false を返します。(詳細)
console.log(req.xhr); // => true or false
field で指定したヘッダ情報を返します。(詳細)
// Content-Type: application/json
req.get("Content-Type"); // => "application/json"
req.get("No-Such-Header"); // => undefined
クライアントから送信される Content-Type ヘッダと比較して、今から受け取るコンテンツタイプ types を調べます。types には文字列または文字列の配列を指定します。マッチすればマッチした種別を、マッチしなければ false を返します。リクエストボディが空の時は null が返されます。(詳細)
// Content-Type: application/json req.is("json") // => "json" req.is("application/json") // => "application/json" req.is("xml") // => false req.is(["xml", "json"]) // => "json"
クライアントから送信される Accept ヘッダと比較して、今から返却しようとするコンテンツタイプ types が、クライアントが受け付けられるコンテンツタイプかどうかを調べます。types には文字列または文字列の配列を指定します。マッチすればマッチした種別を、マッチしなければ false を返します。(詳細)
// Accept: text/html req.access("html") // => "html" req.access("text/html") // => "text/html" req.access("json") // => false req.access(["json", "html"]) // => "html"
九合アントから送信される Accept-Charset ヘッダと比較して、今から返却しようとするコンテンツの文字コード charsets が、クライアントが受け付けられる文字コードとマッチするかどうかを調べます。(詳細)
// Accept-Charset: utf-8, Shift_JIS
req.acceptsCharsets("utf-8") // => "utf-8"
req.acceptsCharsets("Shift_JIS") // => "Shift_JIS"
req.acceptsCharsets("EUC-JP") // => false
req.acceptsCharsets(["EUC-JP", "utf-8"]) // => "utf-8"
クライアントから送信される Accept-Encoding ヘッダと比較して、今から返却しようとするコンテンツのエンコーディング encodings が、クライアントが受け付けられるエンコーディングとマッチするかどうかを調べます。(詳細)
// Accept-Encoding: gzip, compress
req.acceptsEncodings("gzip") // => "gzip"
req.acceptsEncodings("deflate") // => false
req.acceptsEncodings(["deflate", "gzip"]) // => "gzip"
クライアントから送信される Accept-Language ヘッダと比較して、今から返却しようとするコンテンツの言語 language が、クライアントが受け付けられる言語とマッチするかどうかを調べます。(詳細)
// Accept-Language: ja, en
req.acceptsLanguages("ja") // => "ja"
req.acceptsLanguages("de") // => false
req.acceptsLanguages(["de", "ja"]) // => "ja"
パスパラメータやGETパラメータを受け取ります。このメソッドは非推奨(deprecated) となっており、代わりに req.params, req.body, req.query を使用することが推奨されています。(詳細)
// curl http://www.example.com/users/yamada
app.get("/users/:user", (req, res) => {
console.log(req.param("user")); // => "yamada"
res.send("OK\n");
});
// curl http://www.example.com/users?user=yamada
app.get("/users", (req, res) => {
console.log(req.param("user")); // => "yamada"
res.send("OK\n");
});
// curl -X POST http://www.example.com/users -d 'user=yamada'
app.use(express.urlencoded({ extended: true }));
app.post("/users", (req, res) => {
console.log(req.param("user")); // => "yamada"
res.send("OK\n");
});
クライアントから送信される Range ヘッダ情報を返します。maxsize にはサーバが返却可能な最大サイズを指定します。(詳細)
// => curl -H "Range: bytes=0-999, 2000-2999" http://www.example.com/ const express = require('express'); const app = express(); app.get("/", (req, res) => { var range = req.range(8192); if (range.type == "bytes") { range.forEach((r) => { console.log(r.start + "-" + r.end); // => 0-999, 2000-2999 }); } res.send("OK\n"); }); app.listen(80);
HTTP のレスポンスボディを返却します。(詳細)
res.send("OK\n");
res.send({ foo: "FOO" });
res.status(404).send("Not Found.");
JSONデータを返却します。(詳細)
res.json({ status: "OK" });
res.status(404).json({ error: "Not Found" });
テンプレートエンジンを用いて view で示したテンプレートに locals で示したパラメータを埋め込んで返却します。使用例は「EJSテンプレートエンジンを使用する」を参照してください。(詳細)
res.render("index", { name: "Yamada" });
path で指定したファイルを読み取って返却します。v4.8.0 でサポートされました。(詳細)
res.sendFile("index.html", { root: "./html" });
レスポンスを終了します。(詳細)
res.end(); res.status(404).end();
HTTPステータスコードを指定します。(詳細)
res.status(403).end();
res.status(404).send("Not Found.");
res.status(404).sendFile("404.html");
このリクエストを処理しているアプリケーションを参照します。(詳細)
console.log(res.app);
ヘッダ情報を送信済みか否かを true/false で返します。(詳細)
app.get('/', function (req, res) {
console.dir(res.headersSent) // => false
res.send('OK')
console.dir(res.headersSent) // => true
})
app.locals 同様、テンプレートエンジンに渡すパラメータを指定します。単一のリクエスト内のみで有効となる点が異なります。(詳細)
app.get("/", (req, res) => {
res.locals.foo = "FOO";
res.render("test");
});
// <p>Hello <%= foo %></p>
HTTPヘッダを加えます。(詳細)
res.append("Set-Cookie", "foo=FOO; path=/; HttpOnly");
アタッチメントファイルを処理するために Content-Disposition ヘッダを設定します。(詳細)
res.attachment(); // Content-Disposition: attachment res.attachment("img/test.png"); // Content-Disposition: attachment; filename="test.png" // Content-Type: image/png
レスポンスクッキーを設定します。(詳細)
res.cookie("foo", "FOO", { path: "/", secure: true });
// Set-Cookie: foo=FOO; Path=/; Secure
設定したレスポンスクッキーを削除します。(詳細)
res.cookie("foo", "FOO", { path: "/", secure: true });
res.clearCookie("foo");
ファイルをダウンロードさせます。(詳細)
res.download("./img/test.png");
// Content-Type: image/png
// Content-Disposition: attachment; filename="test.png"
res.download("./img/test.png", "test123.png");
// Content-Disposition: attachment; filename="test123.png"
res.download("./img/test.png", { maxAge: "1d" });
// Cache-Control: public, max-age=86400
res.download("./img/test.png", (err) => { console.log(err) });
クライアントが Accept ヘッダで指定したフォーマットに応じたレスポンス処理を行います。(詳細)
res.format({
"text/plain": () => {
res.send("Hello")
},
"text/html": () => {
res.send("<p>Hello</p>")
},
"application/json": () => {
res.send({ message: "Hello" })
},
default: () => {
res.status(406).send("Not Acceptable")
}
});
レスポンスのHTTPヘッダを設定します。(詳細)
res.set("Content-Type", "text/plain");
レスポンスヘッダを参照します。(詳細)
res.get("Content-Type"); // => text/html; charset=utf-8
JSONP を実現するためのスクリプトを返却します。(詳細)
const express = require("express");
const app = express();
app.set('jsonp callback name', 'cb');
app.get("/", (req, res) => {
res.jsonp({name: "Yamada"});
});
app.listen(80);
$ curl http://www.example.com/?cb=getData
/**/ typeof getData === 'function' && getData({"name":"Yamada"});
Link ヘッダを返却します。(詳細)
res.links({
next: '/users?page=2',
last: '/users?page=5'
});
// Link: </users?page=2>; rel="next", </users?page=5>; rel="last"
Location ヘッダを返却します。(詳細)
res.location("/login");
// Location: /login
指定したページにリダイレクトします。(詳細)
res.redirect(302, "/maintenance.html"); // HTTP/1.1 302 Found // Location: /maintenance.html
HTTPステータスを返却します。(詳細)
res.sendStatus(404);
// HTTP/1.1 404 Not Found
Content-Type ヘッダを設定します。(詳細)
res.type("html"); // Content-Type: text/html
res.type("json"); // Content-Type: application/json
res.type("png"); // Content-Type: image/png
リクエストに含まれるヘッダ情報によってレスポンスが変動する可能性があることを示す Vary ヘッダを設定します。(詳細)
res.vary("User-Agent").send("OK\n");
// Vary: User-Agent
const express = require("express");
const app = express();
const routerUser = express.Router();
app.use("/users", routerUser);
routerUser.all("/", (req, res) => {
res.send("OK\n");
});
app.listen(80);
app.METHOD() と同様です。(詳細)
const express = require("express");
const app = express();
const routerUser = express.Router();
app.use("/users", routerUser);
routerUser.get("/", (req, res) => {
res.send("OK\n");
});
app.listen(80);
app.param() と同様です。(詳細)
router.param("user", (req, res, next, id) => {
req.params.user = "[" + req.params.user + "]";
next();
});
app.route() と同様です。(詳細)
router.route("/")
.get((req, res, next) => {
res.send("GET\n");
})
.post((req, res, next) => {
res.send("POST\n");
})
.all((req, res, next) => {
res.send("ALL\n");
});