Next.js API Routes vs Route Handlers: それぞれの使い分け

Next.jsは、ウェブアプリケーションを構築するための人気のあるフレームワークです。その機能を効果的に使用する方法を理解することは、開発者にとって重要です。注目の重要な領域の1つは、API routesとroute handlersの違いです。どちらも開発者がサーバーサイドエンドポイントを作成することを可能にしますが、異なる方法で行います。これらの違いを詳しく解説し、それぞれをいつ使用すべきかを決定するのに役立てましょう。

Next.js API Routesとは何ですか？

Next.js API routesはPages Routerの一部です。これらは pages/api ディレクトリにあります。このディレクトリ内の各ファイルは、APIエンドポイントに対応しています。

これらのルートは NextApiRequest および NextApiResponseを使用しており、これらはNode.jsの IncomingMessage および ServerResponseの薄いラッパーです。これは、API routesのランタイムが常にNode.jsであることを意味します。

API routesの主な特徴は、静的キャッシュをサポートしていないことです。すべてのリクエストがサーバーレス関数をトリガーするため、キャッシュの動作を制御したい場合は、手動でキャッシュヘッダーを設定する必要があります。

Route Handlersとは何ですか？

App Routerで導入されたRoute handlersは、 app ディレクトリに配置されます。これらは route.js または route.tsという名前のファイルで定義されます。API routesとは異なり、route handlersはWeb Fetch APIを使用するため、標準の Request および Response オブジェクトを使用してリクエストを処理します。

Route handlersは、Node.jsやEdge functionsを含むさまざまなランタイムで実行できます。この柔軟性により、特に低レイテンシのエンドポイントでパフォーマンスが向上します。さらに、route handlersは GET リクエストの静的キャッシュをサポートしており、これは revalidate および runtime.

主な違い

両者の簡単な比較は以下の通りです：

機能	API Routes	Route Handlers
ファイルの位置	pages/api/slug.ts	app/api/slug/route.ts
リクエストの種類	NextApiRequest	Request (Web Fetch)
レスポンスの種類	NextApiResponse	Response (Web Fetch)
実行環境	Node.jsのみ	Node.jsおよびEdge functions
キャッシュの動作	静的キャッシュなし、手動ヘッダー	静的キャッシュをサポート（対象： GET

それぞれの使い分け

API Routesを使用すべき場合：

• 常にNode.js上で実行されるサーバーサイドエンドポイントが必要な場合。
• 静的キャッシュが必要ない場合。
• 内部ツールなど、キャッシュすべきではないリクエストを処理したい場合。

Route Handlersを使用すべき場合：

• App Routerを使用した新しいNext.jsプロジェクトを開始する場合。
• より高速なレスポンスのためにEdge runtimeが必要な場合。
• APIレスポンスに対して静的キャッシュを活用したい場合。
• ストリーミングエンドポイントを構築している場合、またはフォームアクションハンドラーをページと同じ場所に配置している場合。

コード例

両方の方法を使用して投稿のリストを返すエンドポイントを実装する簡単な例を以下に示します：

API Routeの例

// pages/api/posts.ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { client } from '@/sanity/client';

type Post = { _id: string; title: string; slug: string };

export default async function handler(req: NextApiRequest, res: NextApiResponse<Post[]>) {
    if (req.method !== 'GET') {
        res.status(405).end();
        return;
    }

    const posts = await client.fetch<Post[]>(`*[_type == "post"]{ _id, title, "slug": slug.current }`);
    res.setHeader('Cache-Control', 's-maxage=60, stale-while-revalidate=300');
    res.status(200).json(posts);
}

Route Handlerの例

// app/api/posts/route.ts
import { NextResponse } from 'next/server';
import { client } from '@/sanity/client';

export const revalidate = 60; // ISR: revalidate every 60 seconds

type Post = { _id: string; title: string; slug: string };

export async function GET() {
    const posts = await client.fetch<Post[]>(`*[_type == "post"]{ _id, title, "slug": slug.current }`, {}, { next: { revalidate: 60 }});
    return NextResponse.json(posts);
}

まとめ

Next.jsのAPI routesとroute handlersのどちらを選択するかは、プロジェクトのニーズによって異なります。両者の違いを理解することで、パフォーマンスを最適化し、キャッシュを効果的に管理するのに役立ちます。

メリット

• API Routes: 使い方がシンプルで、トラフィックの少ない内部ツールに適しており、キャッシュによる想定外の動作がありません。
• Route Handlers: Edge functionsのサポート、より優れたキャッシュ制御、一般的なタスクに対するより短いコード。

デメリット

• API Routes: キャッシュサポートの欠如により、特に負荷がかかっている場合にパフォーマンスの問題が発生する可能性があります。
• Route Handlers: メンタルモデルがより複雑であり、既存の開発者にとっては新しいパターンを習得する必要があるかもしれません。

注意事項

この記事は教育目的のためのものです。プロジェクトではプレースホルダーの値を実際の値に置き換えるようにしてください。情報に依拠する前に、常に元の情報源と照合して検証してください。

よくある質問

• Next.js API routesとは何ですか？ — これらはNode.jsを使用して pages/api ディレクトリに配置されるサーバーサイドエンドポイントです。
• Next.jsにおけるroute handlersとは何ですか？ — これらはWeb Fetch APIを使用して app ディレクトリに配置されるサーバーサイドエンドポイントです。
• API routesはいつ使用すべきですか？ — キャッシュの必要がない、シンプルなNode.js専用のサーバーサイド機能に使用します。
• route handlersはいつ使用すべきですか？ — Edge functionsやキャッシュ機能を必要とする新しいプロジェクトに使用します。
• 同じプロジェクトでAPI routesとroute handlersの両方を使用できますか？ — はい、移行期間中は共存させることができます。
• 両者でキャッシュの仕組みはどのように異なりますか？ — API routesは手動のキャッシュヘッダーを必要としますが、route handlersは自動的に静的キャッシュをサポートします。

タグ

#nextjs #approuter #webdevelopment #caching #performance #programming #javascript #webdev