h3 v2 で変わるリクエストとレスポンスの扱い
2026/11/15
wattanxはじめに
Nitro v3 では、HTTP リクエストの処理を担う h3 が v2 に変わります。
この記事では、h3 v1 から v2 へ移行するときに確認したい、リクエストとレスポンスの扱いを整理します。
Web 標準の API を基盤にした入出力
h3 v1 も複数の JavaScript ランタイムに対応していました。v1 では event.node.req / event.node.res という Node.js のリクエスト・レスポンスを中心に扱い、Node.js の HTTP API を使えない環境では node-mock-http で互換オブジェクトを用意していました。
h3 v2 は Request、Response、Headers、URL など、Web 標準の API を基盤としています。ハンドラーは event.req(Request)からリクエストを読み取り、h3 はハンドラーが返した値を Response に変換します。Node.js 上では、srvx が Node.js の HTTP API と Web 標準の API の間を変換します。
リクエストの読み方とレスポンスの返し方
h3 v2 のハンドラーでは、リクエストの情報を event.req から読み取り、レスポンスのステータスやヘッダーを event.res に設定します。
たとえば、h3 v1 でヘッダー操作のヘルパーを使っていたコードは、v2 では Headers の API で書けます。
// h3 v1
import { defineEventHandler, getHeader, setHeader } from "h3";
export default defineEventHandler((event) => {
const language = getHeader(event, "accept-language");
setHeader(event, "x-example", "h3");
return { language };
});
// h3 v2
import { defineHandler } from "h3";
export default defineHandler((event) => {
const language = event.req.headers.get("accept-language");
event.res.headers.set("x-example", "h3");
return { language };
});
getHeader / setHeader / appendHeader や defineEventHandler は、v2 でも非推奨の API として残っているため、すぐに動かなくなるわけではありません。新しいコードでは、上の例のように event.req.headers / event.res.headers と defineHandler を使います。
リクエストを読む
event.req は Web 標準の Request です。ヘッダーと同じく、メソッドも Request の API で読み取ります。URL は、Web 標準の URL である event.url から読み取ります。クエリパラメータや body は、v1 と同じく getQuery や readBody で読み取れます。
たとえば、メソッド、パス、クエリパラメータ、JSON の body を読むコードは次のようになります。
// h3 v1
import { defineEventHandler, getQuery, readBody } from "h3";
export default defineEventHandler(async (event) => {
const method = event.method;
const path = event.path;
const page = getQuery(event).page;
const body = await readBody(event);
return { method, path, page, body };
});
// h3 v2
import { defineHandler, getQuery, readBody } from "h3";
export default defineHandler(async (event) => {
const method = event.req.method;
const path = event.url.pathname + event.url.search;
const page = getQuery(event).page;
const body = await readBody(event);
return { method, path, page, body };
});
- メソッド:
event.methodの代わりにevent.req.method - パス:
event.pathの代わりにevent.url.pathname + event.url.search
レスポンスを返す
event.res は、最終的なレスポンスに反映するステータスやヘッダーを準備しておくためのオブジェクトです。v1 の event.node.res(Node.js の ServerResponse)とは違い、write() や end() は持っていません。
v1 では、次のように event.node.res へレスポンスを直接書き込むこともできました。
// h3 v1
import { defineEventHandler } from "h3";
export default defineEventHandler((event) => {
event.node.res.statusCode = 200;
event.node.res.setHeader("content-type", "text/plain");
event.node.res.write("Hello, ");
event.node.res.end("h3!");
});
v2 では、文字列やオブジェクトを返す場合、ステータスとヘッダーを event.res に設定し、body はハンドラーから return します。h3 は、返り値と event.res に設定した内容から Response を作ります。Response を返す場合やエラーを throw する場合の書き方は、「ステータスとヘッダーを書く場所」で説明します。
// h3 v2
import { defineHandler } from "h3";
export default defineHandler((event) => {
event.res.status = 200;
event.res.headers.set("content-type", "text/plain");
return "Hello, h3!";
});
write() を何度も呼んで少しずつ送っていた処理は、ReadableStream を作って return する形に書き換えます。上の v1 の例と同じく、"Hello, " と "h3!" を2回に分けて送る場合は次のようになります。
// h3 v2
import { defineHandler } from "h3";
export default defineHandler((event) => {
event.res.headers.set("content-type", "text/plain");
const encoder = new TextEncoder();
const stream = new ReadableStream({
start(controller) {
controller.enqueue(encoder.encode("Hello, "));
controller.enqueue(encoder.encode("h3!"));
controller.close();
},
});
return stream;
});
controller.enqueue() に渡したデータが、v1 の write() で書き込んでいたチャンクにあたります。controller.close() でストリームを閉じると、レスポンスが終了します。
v1 の send* も、値や Response を return する形に書き換えます(基本的には非推奨で、一部の API は削除されているため)。置き換え先は、Response Handling - H3 を参照してください。
たとえば、リダイレクトは sendRedirect(event, ...) から次のように変更します。
// h3 v2
import { defineHandler, redirect } from "h3";
export default defineHandler(() => {
return redirect("/new-page", 302);
});
Node.js の API が必要な場合
event.node.req / event.node.res は非推奨です。Node.js 固有の API が必要な場合は、event.runtime.node から req / res を参照します。どちらも Node.js 上で動かしている場合にだけ使えます。
エラーの返し方とヘッダーを書く場所
v2 では、エラーはハンドラーから throw で返します。また、ステータスやヘッダーを書く場所は、ハンドラーが返す値によって変わります。
HTTPError でエラーを返す
エラーには HTTPError を使います。createError も非推奨として残っていますが、新しいコードでは new HTTPError(...) を使います。
// h3 v2
import { defineHandler, HTTPError } from "h3";
export default defineHandler(() => {
throw new HTTPError({
status: 404,
statusText: "Not Found",
message: "The requested article does not exist.",
});
});
推奨されるフィールド名は status / statusText です。v2 でも statusCode / statusMessage は非推奨として受け付けますが、新しいコードでは status / statusText を使います。
statusText は HTTP レスポンスのステータスに添える短いテキストです。ドキュメントでは最大 512〜1024 文字とされており、詳しい説明はレスポンス body の message に書きます。
HTTPError 以外のエラーは、unhandled なエラーとして扱われます。unhandled なエラーでは、セキュリティのため、JSON レスポンスに含まれる message / data / body / stack の詳細が隠されます(Unhandled Errors - H3)。
ステータスとヘッダーを書く場所
h3 のドキュメントでは、ハンドラーが返す値によって、ステータスやヘッダーを書く場所を使い分けることを勧めています。
| 返す値 | ステータスとヘッダーを書く場所 |
|---|---|
| 文字列やオブジェクト | event.res.status / event.res.headers |
Response | 返す Response |
| エラー(throw) | new HTTPError({ status, headers }) |
Response を返す場合は、ヘッダーも Response に直接書きます。event.res.headers に値があると、h3 は返された Response をそのまま使わず、ヘッダーをマージした新しい Response を作り直すためです。
// h3 v2
import { defineHandler } from "h3";
export default defineHandler(() => {
return new Response("Hello, h3!", {
headers: {
"content-type": "text/plain",
"cache-control": "no-store",
},
});
});
全部 Response にまとめたほうがわかりやすくないかと思ってましたが、h3 では次の理由から、すべてのハンドラーで Response を返す形にはしにくくなっています。
- h3 のユーティリティは
event.resに書き込みます。たとえばhandleCorsは、CORS のヘッダーをevent.res.headersに設定します。ハンドラーがResponseを返しても、こうしたヘッダーとのマージは起こります。 - Node.js 上では、送信の処理が増えます。文字列を返すと body を 1 回で書き出せますが、ネイティブの
Responseを返すと body をReadableStreamから読み出しながら書き出します(「Web の Response を Node.js の ServerResponse へ書き出す」を参照)。 - エラーは
HTTPErrorを throw して返します。ステータスが 400 以上のResponseを返しても、h3 はエラーとして扱わないため、onErrorなどのエラー処理は呼ばれません。
event.res と返す値が重なった場合
event.res に設定した値と、ハンドラーが返す値が重なった場合は、次のように扱われます。
Responseをそのまま返すと、event.res.statusに設定したステータスは捨てられ、返したResponseのステータスが使われます。ヘッダーはマージされ、同じ名前のヘッダーはevent.res.headersに設定したほうが優先されます。ただし、set-cookieは上書きせず追加されます(h3 の mergeHeaders のソースコード)。- 返した
Responseのステータスが 400 以上の場合は、event.res.headersではなく、event.res.errHeadersに設定したヘッダーだけがマージされます。 - エラーを throw すると、
event.res.statusとevent.res.headersに設定した値は捨てられます。エラー時に付けたいヘッダーは、new HTTPError({ headers })かevent.res.errHeadersで指定します。
たとえば、成功時はキャッシュさせ、エラー時はキャッシュさせないように、event.res.headers と event.res.errHeaders に別々の値を設定してからエラーを throw するとします。
// h3 v2
import { defineHandler, HTTPError } from "h3";
export default defineHandler((event) => {
event.res.headers.set("cache-control", "max-age=60");
event.res.errHeaders.set("cache-control", "no-store");
throw new HTTPError({
status: 404,
message: "The requested article does not exist.",
});
});
このレスポンスの cache-control は、event.res.headers の max-age=60 ではなく、event.res.errHeaders の no-store になります。
ただし、エラーのレスポンスに付けるヘッダーは new HTTPError({ headers }) で指定するのが基本で、errHeaders は CORS のヘッダーのように、エラーになるかどうかがわかる前に付けておきたいヘッダーのための最終手段です。h3 の handleCors も、CORS のヘッダーを event.res.headers と event.res.errHeaders の両方に設定しています(h3 の setCorsHeaders のソースコード)。
srvx が Node.js の HTTP API を Web 標準の API につなぐ仕組み
h3 v2 のアプリは、Web 標準の Request を受け取って Response を返す app.fetch() を持っています。event.req は、app.fetch() に引数として渡された Request です。ハンドラーが返した値は、h3 が Response に変換し、app.fetch() の戻り値として返します。
しかし、Node.js の node:http では、リクエストとレスポンスの扱い方が異なります。createServer() に渡したハンドラーは、リクエストを IncomingMessage(req)として受け取り、レスポンスは ServerResponse(res)に書き込んで送信します。
// node:http
import { createServer } from "node:http";
createServer((req, res) => {
// req(IncomingMessage)からリクエストを読む
console.log(req.method, req.url);
// res(ServerResponse)にステータスとヘッダーを書き込む
res.writeHead(200, { "content-type": "text/plain" });
// body を書き込み、レスポンスを終える
res.write("Hello, node:http!");
res.end();
}).listen(3000);
node:http が Request を渡したり、Response を受け取って送信したりするわけではありません。では、Node.js 上で h3 を動かすとき、IncomingMessage から Request を作り、返した Response を送信しているのは誰でしょうか。
この間をつないでいるのが srvx です。Node.js 上で h3 を動かすときに使う serve() や toNodeHandler() は、内部で srvx を使っています。srvx は Node.js の入出力にアダプターを挟み、ハンドラーを Request を受け取って Response を返す形で実行します。
たとえば toNodeHandler() は、h3 のアプリを createServer() に渡せる (req, res) のハンドラーで包みます。
// h3 v2
import { createServer } from "node:http";
import { H3, toNodeHandler } from "h3";
const app = new H3().get("/", () => "Hello, h3!");
createServer(toNodeHandler(app)).listen(3000);
serve() を使う場合は、この createServer() の呼び出しも srvx が行います。
toNodeHandler() が返すハンドラーの中身をコードで表すと、次のようになります。これは srvx v1.0.8 の実装をもとに、型やエラー処理などを省いた疑似コードです。
function toNodeHandler(fetchHandler) {
// createServer() に渡す (req, res) のハンドラーを返す
return async (nodeReq, nodeRes) => {
// Node.js のリクエストを Web Request として扱う
const request = new NodeRequest({ req: nodeReq, res: nodeRes });
// h3 の app.fetch() などが Web Response を返す
const response = await fetchHandler(request);
// Web Response の内容を Node.js のレスポンスへ書き出す
await sendNodeResponse(nodeRes, response);
};
}
Node.js のリクエストを NodeRequest で包む
NodeRequest は元の IncomingMessage を保持し、getter やメソッドを通して Web 標準の API を提供します。必要な値を参照した時点で処理することで、変換にかかるコストを抑えています。
request.headers.get(name)は、通常は元のreq.headersから値を読みます。ヘッダー名の大文字・小文字や重複などを処理し、必要に応じてネイティブのHeadersを生成します。request.urlは、Node.js 側のパスやホストなどの情報から完全な URL を組み立てます。request.bodyにアクセスすると、Node.js の読み取りストリームをReadable.toWeb()で Web のReadableStreamとして扱えるようにします。request.json()には、body を直接読み取ってJSON.parse()する経路もあります。ストリームやネイティブのRequestがすでに作られている場合は、そちらを使います。
Node.js 上で動かす場合、event.req の実体はこの NodeRequest です。NodeRequest が Request と同じ API を持っているので、アプリケーション側は Node.js 上でも event.req.headers.get() や event.req.json() と書けます。その内側で、srvx が IncomingMessage からデータを取り出しています。
Web の Response を Node.js の ServerResponse へ書き出す
ハンドラーから返った Response は、srvx の sendNodeResponse が Node.js の res に書き出します。ステータスとヘッダーは writeHead() に渡し、body は形式によって書き出し方が変わります。
ハンドラーが文字列や Buffer を返した場合、h3 は srvx の FastResponse を作ります。FastResponse は Response と同じ API を持つクラスで、Node.js 上では body を元の文字列や Buffer のまま持ちます。そのため srvx は、res.write("Hello, h3!") のように 1 回で書き出して end() します。
ハンドラーが ReadableStream やネイティブの Response を返した場合、body は ReadableStream なので、srvx はチャンクを読み取って res.write() に渡します。res.write() が false を返したら、drain イベントを待ってから次のチャンクを読みます。これがバックプレッシャーへの対応です。最後に res.end() で終了します。
バックプレッシャーとは?
バックプレッシャーとは、データを処理する側のペースに合わせて、送り込む量や速さを抑える仕組みです。
クライアントがデータを読まずに受信バッファが埋まると、TCP のフロー制御によってサーバーの OS は送信を止めます。すると、Node.js の書き込みバッファに送信待ちのデータがたまっていきます。res.write() は、このたまった量がしきい値(highWaterMark)を超えると false を返します。
この srvx の処理では、res.write() が false なら次のチャンクを読まず、drain を待って再開します。ここでの false は書き込み失敗ではなく、「追加を待って」という合図です。渡したチャンク自体はバッファに入っていて、捨てられたわけではありません。
まとめ
h3 v1 から v2 への主な書き換えをまとめると、次のようになります。
| 対象 | h3 v1 | h3 v2 |
|---|---|---|
| リクエストヘッダー | getHeader(event, name) | event.req.headers.get(name) |
| レスポンスヘッダー | setHeader(event, name, value) / appendHeader(event, name, value) | event.res.headers.set(name, value) / event.res.headers.append(name, value) |
| URL | event.path | event.url.pathname + event.url.search |
| メソッド | event.method | event.req.method |
| レスポンス | send(event, value) / sendStream(event, stream) など | 値、Response、ストリームを return |
| エラー | createError(...) / sendError(event, error) | throw new HTTPError(...) |
| Node.js 固有の API | event.node.req / event.node.res | event.runtime.node.req / event.runtime.node.res(Node.js 上でのみ使用) |
h3 v2 のハンドラーは、Web 標準の Request を読み、値や Response を返す形で書きます。ステータスやヘッダーは、返す値に合わせて event.res、返す Response、HTTPError のいずれかに設定します。
Node.js 上では、srvx が IncomingMessage を NodeRequest で包んで event.req として渡し、返した Response を ServerResponse へ書き出します。Node.js の API との変換を srvx が受け持つので、アプリケーションのコードは実行環境によらず同じ書き方になります。