Route Handlers

这一课你将能做到

1. 在 app/api/**/route.ts 里写出 GET / POST 等接口，处理查询参数、JSON 请求体与动态段
2. 实现一个「转发到 Spring Boot 并透传登录态」的 BFF 接口（本站 roadmap-node 接口的同款模式）
3. 说清 Route Handler 与 Server Action 的区别，知道各自该用在什么场景

为什么要学

App Router 出现之前，Next.js 项目的后端接口要么另起一个 Express/Koa 服务，要么全部依赖外部后端。Route Handlers 把「写接口」变成了在 app/ 目录里建一个 route.ts 文件——和页面放在一起，同一套部署。

什么时候真的需要它？三个高频场景：

1. BFF（Backend for Frontend）：前端不想暴露后端真实地址，或需要在中间「加一层」（拼数据、鉴权、限流、改格式）。本站就有一个活例子：src/app/api/roadmap-node/[slug]/[nodeKey]/route.ts，它把请求转发到后端并透传用户 token。
2. 给第三方提供回调入口：支付回调、Webhook 接收，必须是一个公网 URL。
3. 纯小项目：个人工具、demo、内部系统，不想为几个接口起一个 Java 服务。

面试角度，「Route Handler 是什么、和 API Routes 有何区别、和 Server Action 怎么选」属于 App Router 新特性题的常客。答案核心：Route Handler 是 HTTP 层（有 URL、能收任意 HTTP 请求），Server Action 是 RPC 层（表单/组件直接调函数，无独立 URL 语义）。

先建立图像

Route Handler 的文件约定一图流：

app/api/health/route.ts          → GET /api/health
app/api/echo/route.ts            → POST /api/echo
app/api/tracks/[slug]/route.ts   → GET /api/tracks/java-essentials

route.ts 里导出的函数名 = 允许的 HTTP 方法：
  export async function GET()    → 处理 GET
  export async function POST()   → 处理 POST
  还有 PUT / PATCH / DELETE / HEAD / OPTIONS

两条铁律：

• 文件名必须叫 route.ts（不是 page.tsx，也不是 index.ts）
• 同一文件夹里 route.ts 和 page.tsx 不能共存（同一个 URL 冲突）

请求与响应的最小骨架：

   Request（入）                     Response（出）
┌──────────────────┐            ┌──────────────────────┐
│ request.nextUrl  │ 查询参数    │ NextResponse.json()  │ JSON 响应
│ request.headers  │ 请求头      │ NextResponse.redirect│ 跳转
│ await request.json() 请求体   │ new Response(body)   │ 自定义
│ { params }       │ 动态段      │ NextResponse.cookies │ 操作 Cookie
└──────────────────┘            └──────────────────────┘

跟着做

步骤 1：第一个 GET 接口——健康检查

新建 src/app/api/health/route.ts：

import { NextResponse } from "next/server";

export async function GET() {
  return NextResponse.json({
    status: "ok",
    time: new Date().toISOString(),
  });
}