Next.js API 路由完整指南：构建高效全栈应用的关键

一. 什么是 Next.js API 路由？

Next.js 是一个基于 React 的框架，专为构建生产级静态和服务端渲染应用而设计。它提供丰富的内置功能，并支持完全自定义页面请求。其中，API 路由是 Next.js 的核心功能之一，允许开发者在 pages 目录中创建 API 端点，就像编写后端代码一样。

通过 Next.js API 路由，开发者可以将前端和后端代码无缝结合，无需额外的代码库。无论是构建 RESTful API 还是 GraphQL API，Next.js 都能简化开发流程并提升效率。

二. 为什么需要 API 路由？

现代 Web 应用通常需要通过 API 与外部数据源进行交互。API（应用程序编程接口）定义了应用或服务如何通过 HTTP 请求和响应进行通信，例如：客户端获取用户列表或提交表单数据。

目前最流行的 API 构建方法是 REST（表征状态转移）。RESTful API 允许客户端通过不同 HTTP 方法（如 GET、POST、PUT、DELETE）与服务器交互。除了 REST，还有 SOAP 和 GraphQL 等方法。

在传统全栈开发中，前端和后端通常分开构建，而 Next.js API 路由 使开发者能够在同一个项目中处理前端和后端逻辑，简化项目结构并减少维护成本。

三. 如何创建 API 路由？

在 Next.js 中，创建 API 路由与创建页面路由类似。不同之处在于 API 路由必须放置在 pages/api 目录下，每个文件即一个 API 端点。例如：

文件路径：pages/api/example.js
访问路径：/api/example

1. 示例：创建一个简单 API 路由

项目初始化后，pages/api 目录下默认包含一个示例文件 hello.js：

export default function handler(req, res) {
  res.status(200).json({ message: 'Hello, World!' });
}

访问 http://localhost:3000/api/hello 或发送 GET 请求，将返回：

{
  "message": "Hello, World!"
}

2. 请求和响应对象

每个 API 路由都需要导出一个默认函数处理请求，该函数接收两个参数：

req：请求对象，包含 req.body、req.query 等
res：响应对象，用于返回数据，例如 res.status()、res.json()

如果熟悉 Node.js 或 Express.js，这些方法非常类似。

四. 处理不同的 HTTP 方法

默认情况下，API 路由会对所有 HTTP 方法返回相同响应。可以通过 switch 或 if/else 根据方法处理不同请求：

export default function handler(req, res) {
  switch (req.method) {
    case 'GET':
      res.status(200).json({ message: 'This is a GET request' });
      break;
    case 'POST':
      res.status(201).json({ message: 'This is a POST request' });
      break;
    default:
      res.status(405).json({ error: 'Method not allowed' });
  }
}

五. 动态 API 路由

Next.js 支持动态 API 路由，工作方式与动态页面路由类似。例如：

在 pages/api/trivia/[number].js 中创建动态路由：

export default function handler(req, res) {
  const { number } = req.query;

  if (isNaN(number)) {
    res.status(400).json({ error: 'Invalid number' });
  } else {
    res.status(200).json({ trivia: Random trivia for number ${number} });
  }
}

访问 http://localhost:3000/api/trivia/42 返回：

{
  "trivia": "Random trivia for number 42"
}

六. 使用中间件增强 API 路由

中间件是处理请求的预处理函数，可用于身份验证、日志记录或请求验证。在 Next.js 中，可使用 next-connect 实现中间件功能。

1. 示例：身份验证中间件

import nextConnect from 'next-connect';

const authenticate = (req, res, next) => {
  const token = req.headers.authorization;

  if (token === 'valid-token') {
    next();
  } else {
    res.status(401).json({ error: 'Unauthorized' });
  }
};

const handler = nextConnect()
  .use(authenticate)
  .get((req, res) => {
    res.status(200).json({ message: 'Authenticated GET request' });
  });

export default handler;

七. 使用 TypeScript 提升类型安全

Next.js 支持 TypeScript，确保 API 路由类型安全：

import { NextApiRequest, NextApiResponse } from 'next';

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  res.status(200).json({ message: 'TypeScript is awesome!' });
}

八. 测试 API 路由

测试确保 API 路由可靠性，可通过单元测试和集成测试实现。

1. 单元测试

使用 Jest 和 node-mocks-http 模拟请求和响应对象：

import { createMocks } from 'node-mocks-http';
import handler from '../pages/api/hello';

test('returns correct response', async () => {
  const { req, res } = createMocks({ method: 'GET' });
  await handler(req, res);

  expect(res._getStatusCode()).toBe(200);
  expect(res._getJSONData()).toEqual({ message: 'Hello, World!' });
});

2. 集成测试

集成测试确保 API 路由与数据库或其他服务协同工作：

jest.mock('../lib/db', () => ({
  getUser: jest.fn(),
}));

test('returns user data', async () => {
  getUser.mockResolvedValueOnce({ id: 1, name: 'John Doe' });

  const { req, res } = createMocks({ method: 'GET' });
  await handler(req, res);

  expect(res._getStatusCode()).toBe(200);
  expect(res._getJSONData()).toEqual({ id: 1, name: 'John Doe' });
});