使用Next.js构建API

使用 Next.js 构建 API 的全面指南

本指南将详细介绍如何使用 Next.js 构建 API，包括项目设置、应用程序路由器和路由处理程序的使用、处理多种 HTTP 方法、实现动态路由、创建可重用的中间件逻辑，以及何时启动专用的 API 层。

创建一个新的 Next.js 项目

如果你是初次接触 Next.js，可以通过以下命令快速创建一个新的项目：

npx create-next-app@latest --api

此命令将为你生成一个包含 API 支持的 Next.js 项目结构。

页面路由器与应用程序路由器

页面路由器的历史背景

在早期版本中，Next.js 使用 pages/api/* 路径来定义 API 路由。这种方式依赖于 Node.js 的请求/响应对象，并提供类似 Express 的 API。

应用程序路由器的现代方式

在新的应用程序路由器（app/）中，你可以通过创建文件夹和 route.ts 文件来定义 API 路由。例如，若要在 /api/users 处创建一个端点，可以按照以下步骤操作：

在 app/api/users 文件夹中创建一个 route.ts 文件。
在文件中导出多个函数来处理不同的 HTTP 方法（如 GET 和 POST）。

示例代码如下：

export async function GET(request: Request) {
  // 处理 GET 请求
}

export async function POST(request: Request) {
  // 处理 POST 请求
}

通过这种方式，向 /api/users 发送 GET 请求将返回用户列表，而发送 POST 请求则会插入新的用户数据。

动态路由的实现

若需要创建动态路径（例如 /api/users/:id），可以在文件夹结构中使用动态段：

在 app/api/users/[id]/route.ts 文件中定义路由。
通过 params.id 获取动态段的值。

示例代码：

export async function GET(request: Request, { params }: { params: { id: string } }) {
  const userId = params.id;
  // 根据 userId 处理逻辑
}

这种方式可以轻松捕获 URL 中的动态参数，例如 /api/users/123 中的 123。

构建公共 API

支持多客户端的公共 API

使用 Next.js，你可以构建一个公共 API，供 Web 应用、移动应用或第三方服务使用。例如，React 网站和 React Native 应用都可以通过 /api/users 获取用户数据。

代理后端服务

Next.js 还支持代理现有的后端服务。在请求到达远程服务器之前，你可以进行身份验证、日志记录或数据转换。例如：

export async function POST(request: Request) {
  const response = await fetch('https://external-service.com/api', {
    method: 'POST',
    body: request.body,
  });
  return response;
}

这种模式被称为“前端的后端”（Backend for Frontend，BFF），可以简化客户端的调用逻辑。

可重用的中间件逻辑

如果需要在多个路由处理程序中应用相同的逻辑（如身份验证或日志记录），可以创建可重用的中间件函数。例如：

function withAuth(handler: Function) {
  return async (request: Request) => {
    // 验证逻辑
    const isAuthenticated = true; // 示例逻辑
    if (!isAuthenticated) {
      return new Response('Unauthorized', { status: 401 });
    }
    return handler(request);
  };
}

在路由处理程序中使用该中间件：

export const GET = withAuth(async (request: Request) => {
  return new Response('Authenticated');
});

部署与静态导出

标准部署

通过 next start 部署 Next.js 应用时，你可以使用路由处理程序、服务器组件和中间件等功能，而无需额外配置。

静态导出模式

Next.js 还支持将整个网站导出为静态单页应用程序（SPA）。在这种模式下，Next.js 会生成纯静态的 HTML、CSS 和 JavaScript 文件，但无法运行服务器端代码（如 API 端点）。如果需要 API 支持，你需要单独托管一个后端服务。

部署到 Vercel

如果将应用部署到 Vercel，可以利用其提供的编程限速、防火墙和 Cron Jobs 等功能来增强 API 的能力。

使用 React 服务器组件

通过 App Router 的 React 服务器组件，你可以直接在服务器上获取数据，而无需公开公共端点。这种方式适用于仅在 Next.js 应用中使用的数据场景。

TypeScript 支持

Next.js 完全支持 TypeScript，你可以在 route.ts 文件中定义请求和响应的类型。例如：

export async function GET(request: Request): Promise {
  return new Response('Hello, TypeScript!');
}

总结

使用 Next.js 的应用程序路由器和路由处理程序，可以灵活地构建支持 Web 平台的现代 API。无论是创建公共 API、实现动态路由，还是代理后端服务，Next.js 都提供了强大的工具和灵活的架构。此外，通过结合 TypeScript 和中间件逻辑，你可以进一步提升代码的可维护性和安全性。

原文链接: https://nextjs.org/blog/building-apis-with-nextjs