Next.js API 路由对比 Route Handler：何时使用各自

Next.js 是用于构建 Web 应用程序的流行框架。了解如何有效地使用其功能对于开发者至关重要。一个核心关注领域是 API 路由与 Route Handler 之间的区别。两者都允许开发者创建服务端端点，但各自的实现方式有所不同。下面我们将剖析这些区别，并帮助你决定何时使用各自。

什么是 Next.js API 路由？

Next.js API 路由是 Pages Router 的一部分。你可以在 pages/api 目录中找到它们。该目录中的每个文件都对应一个 API 端点。

这些路由使用 NextApiRequest 和 NextApiResponse，它们是对 Node.js 的 IncomingMessage 和 ServerResponse的薄封装。这意味着 API 路由的运行时始终是 Node.js。

API 路由的一个关键特性是它们不支持静态缓存。每个请求都会触发 Serverless 函数，这意味着如果你想控制缓存行为，必须手动设置缓存响应头。

什么是 Route Handler？

随 App Router 一起引入的 Route Handler 位于 app 目录中。它们定义在名为 route.js 或 route.ts的文件中。与 API 路由不同，Route Handler 使用 Web Fetch API，这意味着它们使用标准的 Request 和 Response 对象处理请求。

Route Handler 可以在各种运行时上运行，包括 Node.js 和 Edge 函数。这种灵活性带来了更好的性能，尤其是对于低延迟端点。此外，Route Handler 还支持对 GET 请求的静态缓存，可以使用类似于 revalidate 和 runtime.

主要区别

以下是两者的简要对比：

特性	API 路由	Route Handler
文件位置	pages/api/slug.ts	app/api/slug/route.ts
请求类型	NextApiRequest	Request （Web Fetch）
响应类型	NextApiResponse	Response （Web Fetch）
运行时环境	仅 Node.js	Node.js 和 Edge 函数
缓存行为	无静态缓存；需手动设置标头	支持对 GET

何时使用各自

在以下情况下使用 API 路由：

• 你需要始终在 Node.js 上运行的服务端端点。
• 你不需要静态缓存。
• 你想处理不应被缓存的请求，例如内部工具。

在以下情况下使用 Route Handler：

• 你正在使用 App Router 启动新的 Next.js 项目。
• 你需要 Edge 运行时来获得更快的响应。
• 你想利用静态缓存来优化 API 响应。
• 你正在构建流式端点或将表单操作处理程序与对应页面同置于一处。

示例代码

以下是使用这两种方法实现返回文章列表端点的简要示例：

API 路由示例

// 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 路由和 Route Handler 之间进行选择取决于你的项目需求。理解它们的区别有助于你优化性能并有效管理缓存。

优点

• API 路由： 简单易用，适合低流量的内部工具，无需担心意外的缓存行为。
• Route Handler： 支持 Edge 函数、更佳的缓存控制以及针对常见任务更简短的代码。

缺点

• API 路由： 缺乏缓存支持可能导致性能问题，尤其是在高负载下。
• Route Handler： 思维模型更复杂，现有的开发者可能需要学习新的模式。

注意

本文仅供教育目的。请务必在你的项目中将所有占位符值替换为真实值。在依赖相关说法之前，请务必参照原始来源进行核实。

常见问题

• 什么是 Next.js API 路由？ — 它们是位于 pages/api 目录中的服务端端点，使用 Node.js。
• Next.js 中的 Route Handler 是什么？ — 它们是位于 app 目录中的服务端端点，使用 Web Fetch API。
• 我应该何时使用 API 路由？ — 在不需要缓存的简单、仅基于 Node.js 的服务端功能中使用它们。
• 我应该何时使用 Route Handler？ — 在需要 Edge 函数和缓存功能的新项目中使用它们。
• 我可以在同一个项目中同时使用 API 路由和 Route Handler 吗？ — 可以，它们可以在迁移期间共存。
• 两者的缓存机制有什么不同？ — API 路由需要手动设置缓存标头，而 Route Handler 则自动支持静态缓存。

标签

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