🧭 新一代 Next.js App Router 下的 Route Handlers —— 从原理到优雅实践

当年人类第一次造船时，造了一块木板就下水了，淹得不成人样。后来我们发现，要想在海上浪迹天涯，需要 船体、舵、地图 。前端路由的发展何尝不是如此：从最初的 SPA 里疯狂监听 hashchange，到 React Router 一点点织网，直到 2023 年 Next.js App Router 带着服务器组件和 Route Handlers，从"前端小船"变成了"全栈巨舰"。

今天我们来聊聊其中颇有哲学意味的部分：Route Handlers 。

一句话总结：它让你在 app/ 目录下，写一份文件，就可以直接处理 HTTP 请求。相当于内置了 后端 API。

🌍 Route Handlers 的基本定位

在旧版 Next.js (Pages Router) 下，想写接口要建 pages/api/*。

新版 App Router 更像是一本精装书：所有内容都归档在 /app 下，页面、布局、接口，都是同一棵树的不同叶子。

👉 你只需要在某个文件夹下建一个 route.js 文件（或 route.ts），即可定义 HTTP 方法。

这意味着，Next.js 在同一个运行时里扮演了两种角色：

React 渲染器：负责搬运客户看到的 HTML
轻量服务器：直接拦截和处理请求

这种双重身份，很像莎士比亚演员一会儿是王子，一会儿是弄臣。🎭

📝 基本写法：GET & POST

`GET` Handler

创建文件：app/api/hello/route.js

javascript 复制代码

export async function GET(request) {
  return new Response(
    JSON.stringify({ message: 'Hello Next.js 🌐' }),
    {
      status: 200,
      headers: { 'Content-Type': 'application/json' }
    }
  )
}

解释：

GET 方法就是一个导出的函数
它的参数是 request（标准的 Web API Request 对象）
返回值用 Response ------ 这不是 Express 的 res，而是 Fetch 标准里的 Response

也就是说：Next.js 底层是基于 WHATWG Fetch 标准 ，而不是绑死在 req/res 上。这放在 2010 年代的前端圈，就好像突然有人掏出了一把激光剑。

`POST` Handler

创建文件：app/api/echo/route.js

javascript 复制代码

export async function POST(request) {
  const body = await request.json()
  return new Response(
    JSON.stringify({ you_said: body }),
    {
      status: 200,
      headers: { 'Content-Type': 'application/json' }
    }
  )
}

解释：

request.json() 直接解析 body
不需要额外安装 body-parser，也不用担心 Buffer 数据拼接
Next.js 直接调用 Node.js 的流接口并转化成 Fetch Request，对开发者完全透明

从思想角度说，这是一种"抽象复用"：既可以跑在 Node.js，也能跑在 Edge Runtime。换句话说，写一次，跑遍天涯。🌍

⚙️ 底层原理一点点（保证不会无聊）

Route Handlers 之所以能运行，是因为 Next.js 在构建时，会将 app/**/route.js 文件编译为特殊的 middleware entry：

当请求匹配 http://localhost:3000/api/hello
Server runtime 查路由树，发现有个 route.js
调用里面导出的 GET 或 POST
填装返回值到标准 Fetch Response，再返回客户端

底层其实就是 Node.js 的 http.createServer 收到请求后的一层分发逻辑，只不过进行了标准化包装。

这个标准化让我们离浏览器 API 更近，离 "裸 Node.js 回调" 更远。就像你骑自行车已经够累了，这时 Next.js 给了你一辆自动平衡的电动小摩托 🛵。

🎨 幽默示意图

虽然我没办法直接贴图，这里用 ASCII 小图标形象描述下：

vbscript 复制代码

          🌐 Request
              │
              ▼
      +-----------------+
      | Next.js Router  |
      +-----------------+
         │          │
         ▼          ▼
     页面渲染     Route Handlers
                   │
                   ▼
             JSON / Response

你可以想象 App Router 是总驯兽师，页面和接口是两只听话的猴子 🐒，各司其职。

📜 总结

Route Handlers 是 App Router 下的重要进化：把前后端接口统一到一棵路由树结构
写法极简：直接导出 GET、POST、PUT 等函数
底层基于 Fetch 标准，与浏览器 API 接口对齐
优势：无额外依赖、天然支持 Edge Runtime、逻辑清晰

✍️ 留个小作业

如果你今天学会了 GET/POST 的写法，可以试着写一个：

GET 返回当前时间戳
POST 模拟一个 "留言接口" 把 body 里内容回传

你会发现，Next.js 不再只是你心中的前端框架，而变成了一个"可以写后端接口的全栈剧场"。🎭