第 6 章：API 路由（后端能力）

第 6 章：API 路由（后端能力）

Next.js 不仅能渲染页面，还内置了 API 路由功能 ，可以在 pages/api/ 目录中直接编写后端接口，支持处理请求、读写数据库、返回 JSON 等。

---

6.1 什么是 API 路由？

API 路由就是运行在 服务器端的 JavaScript 函数，每个文件导出一个 handler 函数（req, res）即构成一个 API 接口。

📁 示例结构：

pages/
└── api/
    ├── hello.js         // GET: /api/hello
    └── user/
        └── login.js     // POST: /api/user/login

---

6.2 编写第一个 API 路由

📄 pages/api/hello.js

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

• 访问路径：http://localhost:3000/api/hello
• 返回结果：{ "message": "Hello from API" }

✅ 所有 API 路由 只能使用默认导出，且只运行在服务端，不会被打包进客户端。

---

6.3 支持多种 HTTP 方法（GET、POST 等）

示例：pages/api/user.js

export default function handler(req, res) {
  const { method } = req;

  switch (method) {
    case 'GET':
      res.status(200).json({ name: 'Eric' });
      break;
    case 'POST':
      const body = req.body;
      res.status(201).json({ message: '用户创建成功', data: body });
      break;
    default:
      res.setHeader('Allow', ['GET', 'POST']);
      res.status(405).end(`Method ${method} Not Allowed`);
  }
}

前端请求示例（使用 fetch）：

fetch('/api/user', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Eric' })
});

---

6.4 路由结构与嵌套目录

你可以根据业务组织接口目录，比如：

pages/api/
├── user/
│   ├── login.js      // /api/user/login
│   └── register.js   // /api/user/register
├── product/
│   └── [id].js       // /api/product/123
└── index.js          // /api

动态路由也适用于 API，比如：

📄 pages/api/product/[id].js

export default function handler(req, res) {
  const { id } = req.query;
  res.status(200).json({ productId: id });
}

---

6.5 处理请求参数（query、body、headers）

export default function handler(req, res) {
  const { method, query, body, headers } = req;

  console.log('Query:', query);
  console.log('Body:', body);
  console.log('Headers:', headers);

  res.status(200).json({ ok: true });
}

---

6.6 中间件模拟（权限验证、CORS）

Next.js API 路由不支持传统 Express 中间件，但可以手动实现。

示例：简单权限校验

export default function handler(req, res) {
  const token = req.headers.authorization;

  if (token !== 'Bearer 123456') {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  res.status(200).json({ message: '验证通过' });
}

示例：设置 CORS

export default function handler(req, res) {
  res.setHeader('Access-Control-Allow-Origin', '*');
  res.setHeader('Access-Control-Allow-Methods', 'GET, POST');

  if (req.method === 'OPTIONS') {
    return res.status(200).end(); // 处理预检请求
  }

  res.status(200).json({ data: 'OK' });
}

---

6.7 API 路由常见用途

• 登录/注册处理
• 表单数据提交
• 请求数据库或第三方 API
• 文件上传（需 multipart 处理）
• 管理后台接口
• 搭配客户端 fetch / useSWR 获取数据

---

✅ 小结

能力	方法
编写接口	在 pages/api/ 中创建 .js 文件
接收请求	使用 req.query, req.body, req.method
返回响应	res.status(code).json(data)
支持方法	GET / POST / PUT / DELETE / PATCH 等
接口嵌套结构	文件夹组织，支持动态路由 [id].js
中间件模拟	手动添加 header 检查、权限验证逻辑