Next.js API 路由：终极指南 - Makerkit

虽然 Next.js 让创建 API 路由和服务器端功能变得非常简单，但要构建可用于生产环境的 API，需要的不仅仅是基本实现。本指南将带您深入了解如何在 Next.js 中创建健壮、安全且高效的 API 端点，并分享关键的最佳实践。

理解 Next.js API 开发的关键概念

Next.js 提供了无缝的全栈开发体验，通过 App Router，开发者可以直接在 Next.js 应用中实现复杂的后端功能。然而，随着功能的增强，责任也随之增加。要构建企业级应用，需要特别关注以下几个关键领域：

1. 安全：保护端点免受未经授权的访问。
2. 数据验证：确保数据完整性并防止恶意输入。
3. 错误管理：优雅地处理意外情况。
4. 性能优化：编写高效的异步代码并实现缓存策略。
5. 跨源资源共享（CORS）：管理跨域请求。
6. 可观测性：实施全面的日志记录。
7. 现代数据突变：利用服务器操作优化数据处理。

Next.js 中的服务器端代码执行

在传统的服务器端框架中，服务器端代码通常通过 REST API 提供给客户端使用。而在 Next.js 中，开发者可以选择以下几种执行上下文：

1. 服务器组件：在服务器端渲染的组件，可以直接调用数据库或其他服务，无需设置 API 端点。
2. 路由处理程序：即 API 端点，通过 Fetch API 或 HTTP 请求调用。
3. 服务器操作：服务器端执行的特殊函数，可以像普通 JavaScript 函数一样从 React 组件中调用。
4. 中间件：在处理每个请求之前运行的代码。

在本文中，“API 端点”主要指 路由处理程序 和 服务器操作。

深入了解 Next.js API 路由处理程序

路由处理程序的基础知识

在 Next.js 中，路由处理程序位于 app 目录下，文件名通常为 route.ts 或 route.js。例如：

app/

  api/

    users/

      route.ts

在上述结构中，route.ts 文件用于处理 /api/users 端点的所有请求。

路由处理程序中的 HTTP 方法

路由处理程序支持所有标准的 HTTP 方法（如 GET、POST、PUT、DELETE 等）。每种方法都可以作为函数导出，从而在单个文件中处理多种 HTTP 请求。

使用 Next.js API 请求

以下是一些常见的 API 请求处理示例：

NextRequest 对象

Next.js 扩展了标准的 Request 对象，提供了额外功能，同时也扩展了 Response 对象为 NextResponse。

查询参数

通过 NextRequest 对象，可以轻松获取查询参数。

动态路由段

使用 params 对象处理动态路径段。例如，从 URL 中提取 categoryId 和 postId。

处理请求头

Next.js 提供了工具来方便地处理请求头。

使用 Cookie

Next.js 提供了强大的 Cookie API，用于设置和读取 Cookie。

请求正文

支持处理多种类型的请求体（如 JSON、表单数据等）。

响应类型

路由处理程序支持多种响应类型，可以根据需求返回适当的响应。

使用 Webhooks

Webhooks 是 API 开发中的常见模式，用于接收第三方服务的事件通知。通过 NextRequest 对象，可以访问请求正文和头部，并验证 Webhook 的来源。

错误处理

在 API 路由处理程序中，可以使用 NextResponse 对象返回错误响应。一个好的错误处理机制不仅可以提高调试能力，还能向客户端提供明确的反馈，避免敏感信息泄露，并保持系统的稳定性。

保护 API 端点

为了确保 API 的安全性，可以实施以下保护措施：

1. CSRF 保护：防止跨站请求伪造攻击。
2. 身份验证：验证请求用户的身份。
3. 授权：限制对资源或操作的访问。
4. 有效载荷验证：确保发送到 API 的数据有效且符合要求。

CSRF 保护

通过中间件实现 CSRF 保护，客户端需要在请求中包含 CSRF 令牌。

有效载荷验证

数据验证对于维护应用程序的质量和安全性至关重要。通过验证，可以防止无效数据进入系统，并降低安全风险。

身份验证和授权

根据具体的身份验证机制，可以在 API 路由处理程序中检查用户的身份和权限。

API 日志记录和可观测性

全面的日志记录对于监控和调试 API 至关重要。以下是一些最佳实践：

1. 结构化日志记录：记录结构化数据，便于查询和分析。
2. 性能日志：记录性能指标，监控 API 请求的效率。
3. 错误日志：记录错误详情，包括类型、消息和堆栈跟踪。
4. 上下文保护：在记录日志时，保留请求的上下文信息。

使用 Pino 等工具，可以轻松实现高效的日志记录。

Next.js API 路由处理程序还是服务器操作？

对于内部数据突变，建议使用服务器操作；而对于更通用的 API 请求，则使用 API 路由处理程序。

总结

Next.js 提供了强大的工具来简化 API 开发，但要构建生产级别的应用，需要遵循一系列最佳实践，包括安全性、性能优化、错误处理和日志记录等。通过合理利用路由处理程序和服务器操作，可以高效地实现复杂的后端功能。

原文链接: https://makerkit.dev/blog/tutorials/nextjs-api-best-practices