在 Next.js 中开垦后端的第一块菜地：/pages/api 的 REST 接口

0. 序

做前端像是种花：摆弄组件、打理样式，赏心悦目。可一旦走向全栈，你就得去动土，养土壤，搞地下水系统。Next.js 给了你一把新锄头： /pages/api ------ 这片目录就是专属于后端的"小菜地"。在这里，你不再只种花，还能种土豆，甚至种点能给别人做炖菜用的"REST API"。

---

1. /pages/api 是什么？

在 Next.js 的传统 pages 目录下，每一个 .js 文件代表一个页面。

而在 /pages/api/ 目录下，每一个文件则代表一个 API 路由。

• /pages/api/hello.js → 对应接口：http://localhost:3000/api/hello
• 每一个 API 文件都必须导出一个函数 (req, res)，这就像你写了一个迷你 Express 服务。

简单讲：你只需写一个 JS 文件，Next.js 会替你造好后端服务器，把它挂在 /api/ 路由里。

---

2. 写下你的第一个 REST 接口

让我们从一个经典的例子开始：

// pages/api/hello.js
export default function handler(req, res) {
  if (req.method === "GET") {
    res.status(200).json({ message: "Hello, RESTful World!" });
  } else {
    res.status(405).json({ error: "Method Not Allowed" });
  }
}

🌟 用浏览器打开 http://localhost:3000/api/hello，你将收到香喷喷的 JSON：

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

这就好比在家门口挂了个小木牌：谁来敲门（GET 请求），你礼貌地回一句招呼。

---

3. 让它更"RESTFul"

仅仅说"Hello"当然不够，我们需要多点"后端的烟火气"。比如写一个 User API 来展示 CRUD（创建、读取、更新、删除）的骨架：

// pages/api/users.js
let users = [{ id: 1, name: "Alice" }];

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

  switch (method) {
    case "GET": // 读取
      res.status(200).json(users);
      break;

    case "POST": // 创建
      const newUser = { id: Date.now(), name: req.body.name };
      users.push(newUser);
      res.status(201).json(newUser);
      break;

    case "PUT": // 更新
      // 简化写法：实际应通过 id 定位
      users[0].name = req.body.name;
      res.status(200).json(users[0]);
      break;

    case "DELETE": // 删除
      users = [];
      res.status(204).end();
      break;

    default:
      res.setHeader("Allow", ["GET", "POST", "PUT", "DELETE"]);
      res.status(405).end(`Method ${method} Not Allowed`);
  }
}

这段代码就是一个微型的"江湖帮派管理系统"：

• GET → 查帮众
• POST → 收新弟子
• PUT → 洗心革面改名字
• DELETE → 解散帮派

😏 至于为什么大家都叫"users"，这是后端届的一种默契，就像武侠里少林一定有武僧一样。

---

4. 底层基础的"科学点拨" 🧪

• HTTP Request 对象 (req) ：

  • 包含请求的方法（GET, POST...）、头信息、请求体。
  • 其实就是浏览器到服务器之间的那串"快递单"。

• HTTP Response 对象 (res) ：

  • 你需要告诉客户端：状态码、数据内容。
  • 当你 res.status(200).json({...}) 时，本质是往 TCP 套接字写入一行带 HTTP 头和 JSON 的字节流。

• 为什么在 pages/api 下就能这样写？

  • 因为 Next.js 内部封装了 Node.js 的 http.createServer，请求匹配到 /api/... 路径时，它会直接调用你导出的函数，把原始的 Node 请求与响应对象"打包成更好用的 req 和 res"。

你写的小小 if (req.method === "GET")，最后会被翻译成数千个 CPU 指令，操作内存里的缓冲区，把数据从内核 socket 拷贝出来，然后再塞回网络内核，顺利回到浏览器。看似一行代码，实则是 层层抽象带来的力量。

---

5. 一点文学调味 🌸

若把 Web 比作江湖：

• 前端是镖局门面，光鲜亮丽、招呼宾客。
• 后端是镖师行走，护送货物，从不在人前炫耀。
• 而 /pages/api，就是那后堂的一扇门：推开后，你会发现里面烤得正香的馒头，和武林秘籍一样实用的接口。

---

6. 总结

• /pages/api 是 Next.js 内置的后端入口，每个文件天然就是一个 API 路径。
• 接口函数的参数就是 (req, res)，你要做的就是 解码请求，编码响应。
• 创造 CRUD REST 接口，就像写一首五言绝句：套路不复杂，但练多了才能见招拆招。

"前端与后端，就像阴与阳。若你只在阳面种花，便容易忘了地下根脉的深邃。"

🌱 现在，轮到你去 /pages/api/users.js 里种下第一棵"后端小苗"啦。