API 与自定义服务

这一课你将能做到

1. 用 route.ts 创建 RESTful API 端点，支持 GET、POST、PUT、DELETE
2. 用 Middleware 实现请求拦截、鉴权、重定向、CORS 处理
3. 理解 Edge Runtime 和 Node.js Runtime 的区别，按需选择
4. 处理文件上传、请求体解析、自定义 Header
5. 区分 Route Handler 和 Server Action 的适用场景

为什么要学

Next.js 不只是前端框架，也是全栈框架。route.ts 让你在同一项目里写 API，和前端共享类型、共享工具函数、共享环境变量。Middleware 让你在请求到达页面之前做拦截：未登录用户重定向到登录页、API 请求校验 Token、A/B 测试分流。Edge Runtime 让你在离用户最近的节点执行代码，延迟从几百毫秒降到几十毫秒。

人话：传统架构是「前端 → Nginx → 后端 API → 数据库」，Next.js 可以是「前端 → Next.js API → 数据库」，甚至「边缘节点直接返回」——少一跳是一跳。

先建立图像

Route Handler 文件结构:
app/
└── api/
    ├── users/
    │   ├── route.ts          ← GET /api/users, POST /api/users
    │   └── [id]/
    │       └── route.ts      ← GET /api/users/1, PUT /api/users/1
    ├── upload/
    │   └── route.ts          ← POST /api/upload
    └── auth/
        └── [...nextauth]/
            └── route.ts      ← NextAuth.js 端点

Middleware 执行位置:
请求 → middleware.ts → 匹配的路由 → route.ts / page.tsx
       (鉴权/重定向/重写)

跟着做

步骤 1：基础 Route Handler

app/api/users/route.ts：

import { NextResponse } from 'next/server';

const users = [
  { id: 1, name: '张三', email: 'zhangsan@example.com' },
  { id: 2, name: '李四', email: 'lisi@example.com' },
];

export async function GET() {
  return NextResponse.json(users);
}

export async function POST(request: Request) {
  const body = await request.json();
  const newUser = {
    id: users.length + 1,
    name: body.name,
    email: body.email,
  };
  users.push(newUser);
  return NextResponse.json(newUser, { status: 201 });
}

测试：

curl http://localhost:3000/api/users
curl -X POST http://localhost:3000/api/users \
  -H "Content-Type: application/json" \
  -d '{"name":"王五","email":"wangwu@example.com"}'

步骤 2：动态路由参数

app/api/users/[id]/route.ts：

import { NextResponse } from 'next/server';

const users = [
  { id: 1, name: '张三', email: 'zhangsan@example.com' },
  { id: 2, name: '李四', email: 'lisi@example.com' },
];

interface Props {
  params: Promise<{ id: string }>;
}

export async function GET(request: Request, { params }: Props) {
  const { id } = await params;
  const user = users.find(u => u.id === Number(id));

  if (!user) {
    return NextResponse.json({ error: '用户不存在' }, { status: 404 });
  }

  return NextResponse.json(user);
}

export async function PUT(request: Request, { params }: Props) {
  const { id } = await params;
  const body = await request.json();
  const index = users.findIndex(u => u.id === Number(id));

  if (index === -1) {
    return NextResponse.json({ error: '用户不存在' }, { status: 404 });
  }

  users[index] = { ...users[index], ...body };
  return NextResponse.json(users[index]);
}

export async function DELETE(request: Request, { params }: Props) {
  const { id } = await params;
  const index = users.findIndex(u => u.id === Number(id));

  if (index === -1) {
    return NextResponse.json({ error: '用户不存在' }, { status: 404 });
  }

  users.splice(index, 1);
  return new NextResponse(null, { status: 204 });
}