🛰️ Next.js API Route 的请求与响应（req/res 对象）

一、前言：当 Web 遇上厨房

在 Next.js 的世界里，API Route 就像一间小型“程序厨房”。

• req 是进门的顾客：带着点单、要求、奇怪的自定义 header。
• res 是厨房里端出来的菜：要及时送上，又不能夹带生菜泥。

今天我们来聊聊：如何在这间厨房里优雅地接待顾客（处理请求）并献上一份完美的料理（响应）。

---

二、API Route 基础 🛠️

在 Next.js 中，任何位于 pages/api/ 下的文件都会自动成为一个 API Endpoint。
比如：

pages/api/hello.js → /api/hello

核心结构如下：

export default function handler(req, res) {
  // req: 请求对象 (IncomingMessage)
  // res: 响应对象 (ServerResponse)
  res.status(200).json({ message: 'Hello World!' });
}

• req 来自 Node.js http 模块，经由 Next.js 封装。
• res 则是熟悉的 Node.js 响应对象，带着服务器的“餐具”。

---

三、req 对象：像侦探一样读取顾客需求 🕵️

1. req.method

顾客想点 炒饭 还是 炒面？
用 req.method 获取请求方式：

if (req.method === 'POST') {
  // 用户递交了“点餐表单”
}

2. req.query

GET 请求参数 → 像菜单上的小字：

// /api/user?id=42
const { id } = req.query; // "42"

3. req.body

POST/PUT 请求体 → 菜谱的详细要求：

if (req.method === 'POST') {
  const data = req.body;  // {"name":"Tom"}
}

⚠️ 注意：Next.js 自动内置 JSON 解析，不需要你自己 JSON.parse()。

4. req.headers

HTTP 头是顾客递上的“VIP 卡”：

const userAgent = req.headers['user-agent'];

---

四、res 对象：把菜端上桌 🍲

1. res.status(code)

餐厅要先说“OK”还是“对不起”：

res.status(200); // 表示成功
res.status(404); // 找不到菜品

2. res.setHeader

加点调料 🧂：

res.setHeader('Content-Type', 'application/json');

3. res.json()

端出 JSON 格式的佳肴：

res.status(200).json({ name: 'Alice', age: 18 });

4. res.send()

端出任意格式的菜：

res.send('<h1>Hello from Next.js</h1>');

---

五、一个完整的小例子 🍱

当顾客发来请求，厨师如何判断是“要看菜单”还是“点餐”？

export default function handler(req, res) {
  if (req.method === 'GET') {
    // 顾客查看菜单
    res.status(200).json({ menu: ['拉面', '寿司', '火锅'] });
  } else if (req.method === 'POST') {
    // 顾客下单
    const order = req.body;
    res.status(201).json({ message: '下单成功', order });
  } else {
    // 其他操作，本店暂不提供
    res.status(405).json({ error: 'Method Not Allowed' });
  }
}

---

六、结构小图 📊

┌─────────────┐     ┌─────────────┐
│   客户端      │  →  │   req对象     │
│ (请求发送者)   │     │  method/query│
└───────▲─────┘     │  body/headers │
        │            └───────┬─────┘
        │                    │
        │            ┌───────▼─────┐
        │            │   res对象     │
        │            │ status/json  │
        │            │ send/header  │
        │            └───────┬─────┘
        │                    │
┌───────┴─────┐     ┌────────▼─────┐
│   用户得到    │  ←  │   服务端响应   │
│   菜单/结果   │     │   (响应内容)   │
└─────────────┘     └─────────────┘

---

七、思辨时刻 🤔

你觉得 API Route 里的 req/res 和 Express.js 的有何异同？

• 一样：写法几乎魔法般相似，老 Node.js 开发者能一秒上手。
• 不一样：Next.js 额外提供了 内置 body 解析 和更深的框架集成，让开发体验更“丝滑”。

---

八、结尾：诗意的收场

所以说，Next.js 的 API Route，
就是一桌前端开发的 深夜食堂：

• 顾客带着 req 走进来，
• 厨师端着 res 走出去。

写 API，也能是一种文学。🍵