Next.js API 路由：构建后端端点

关键要点

• Next.js 的 API 路由允许在同一项目中创建后端端点，支持 GET、POST 等 HTTP 方法，简化全栈开发。
• API 路由基于文件系统，在 pages/api/（Pages Router）或 app/api/（App Router）目录下定义。
• 支持动态路由、查询参数、中间件和数据库集成。
• 涵盖基本实现、动态端点、请求处理、安全性和性能优化。
• 提供详细代码示例和最佳实践，适合初学者和进阶开发者。

为什么需要这篇文章？

Next.js 作为全栈框架，不仅擅长前端渲染，还提供了 API 路由功能，让开发者在同一项目中构建后端逻辑，无需单独的服务器。API 路由通过文件系统定义端点，支持各种 HTTP 方法和动态参数，适用于创建 RESTful API 或 GraphQL 端点。无论是处理表单提交、数据库查询还是第三方服务集成，掌握 API 路由都能大大提升开发效率和应用可扩展性。本文将深入探讨 API 路由的工作原理，展示如何在 Next.js 中创建后端端点，并提供实用示例和优化建议。

目标

• 解释 API 路由的原理和配置方法。
• 展示如何在 Pages Router 和 App Router 中实现基本和动态 API 路由。
• 结合请求处理、中间件和数据库展示后端逻辑。
• 提供性能优化、安全最佳实践和错误处理方法。
• 帮助开发者构建全栈应用并组织大型项目。

---

1. 引言

Next.js 是一个基于 React 的全栈框架，其 API 路由功能允许开发者在前端项目中直接创建后端端点，实现全栈开发的无缝整合。API 路由通过文件系统定义，类似于页面路由，但专注于处理 HTTP 请求，支持 GET、POST、PUT、DELETE 等方法。无论是构建简单的 JSON 接口，还是复杂的数据库操作，API 路由都能提供高效的解决方案。

在 Next.js 中，API 路由支持两种路由方式：Pages Router（基于 pages/api/ 目录）和 App Router（基于 app/api/ 目录）。Pages Router 适合现有项目，App Router 则提供更现代的特性，如 Route Handlers。本文将详细讲解 API 路由的工作原理，展示如何在 Next.js 中创建后端端点，结合动态路由、请求处理、中间件和数据库集成，展示实际应用，并通过代码示例、最佳实践和常见问题解决方案，帮助开发者掌握这一核心功能。

通过本文，您将学会：

• 理解 API 路由的基本原理和配置方法。
• 在 Pages Router 和 App Router 中实现基本和动态 API 路由。
• 处理不同 HTTP 方法和查询参数。
• 集成数据库和第三方服务构建复杂后端逻辑。
• 优化性能、安全处理和组织大型项目的 API 结构。

2. API 路由的基本原理

API 路由是 Next.js 的后端功能，通过文件系统定义端点，自动处理 HTTP 请求和响应。以下是核心概念：

• 文件系统定义：
  • Pages Router：在 pages/api/ 目录下创建文件，如 pages/api/hello.js 对应 /api/hello 端点。
  • App Router：在 app/api/ 目录下创建 route.js 或 route.ts，如 app/api/hello/route.js 对应 /api/hello。
• 请求处理：
  • 默认导出函数接收 req（请求对象）和 res（响应对象）。
  • 支持 JSON、文本、状态码等响应格式。
• 动态路由：
  • 使用方括号定义动态参数，如 pages/api/users/[id].js 对应 /api/users/:id。
• HTTP 方法：
  • 通过 req.method 判断处理 GET、POST 等方法。
  • App Router 支持方法特定函数（如 export async function GET()）。
• 优势：
  • 全栈整合：前端和后端在同一项目中，简化部署。
  • 自动优化：Next.js 处理路由解析、缓存和安全。
  • 可扩展：支持中间件、数据库和第三方 API。
• 限制：
  • API 路由无状态，适合无状态操作；复杂逻辑需结合数据库。
  • App Router 的 Route Handlers 不支持中间件，需单独配置。

2.1 Pages Router vs App Router

特性	Pages Router	App Router
目录	pages/api/	app/api/
文件名	hello.js	route.js 或 route.ts
处理函数	默认导出 (req, res) => {}	方法特定函数（如 GET(req)）
动态路由	[id].js	[id]/route.js
中间件	支持	不支持（需单独中间件）
适用场景	现有项目、简单 API	新项目、现代功能

App Router 是 Next.js 的未来方向，提供更结构化的 API 处理，推荐新项目使用。本文将主要基于 App Router 讲解 API 路由，但也会覆盖 Pages Router 的实现方法。

3. App Router 中的 API 路由

App Router 使用 Route Handlers 定义 API 路由，支持方法特定函数和动态参数。

3.1 基本 API 路由

• 项目结构：

  app/
  ├── api/
  │   ├── hello/
  │   │   ├── route.js  # /api/hello
  ├── page.js
  

• 代码示例（app/api/hello/route.js）：

  import { NextResponse } from 'next/server';export async function GET(request) {return NextResponse.json({ message: 'Hello, API!' });
  }
  

• 访问：

  • GET /api/hello 返回 {"message": "Hello, API!"}。

• 处理 POST 请求：

  export async function POST(request) {const body = await request.json();return NextResponse.json({ received: body });
  }
  

• 效果：

  • 支持多种 HTTP 方法，自动处理 JSON 请求和响应。
  • 使用 NextResponse 控制状态码、头信息等。

3.2 动态 API 路由

动态路由使用方括号定义参数。

• 项目结构：

  app/
  ├── api/
  │   ├── users/
  │   │   ├── [id]/
  │   │   │   ├── route.js  # /api/users/:id
  

• 代码示例（app/api/users/[id]/route.js）：

  import { NextResponse } from 'next/server';export async function GET(request, { params }) {const { id } = params;// 模拟数据库查询const user = { id, name: `User ${id}` };return NextResponse.json(user);
  }
  

• 访问：

  • GET /api/users/123 返回 {"id":"123","name":"User 123"}。

• 处理 PUT 请求：

  export async function PUT(request, { params }) {const { id } = params;const body = await request.json();// 模拟更新用户const updatedUser = { id, ...body };return NextResponse.json(updatedUser);
  }
  

3.3 处理查询参数和头信息

• 代码示例（app/api/search/route.js）：

  import { NextResponse } from 'next/server';export async function GET(request) {const { searchParams } = new URL(request.url);const query = searchParams.get('q');const token = request.headers.get('authorization');// 模拟搜索const results = [{ id: 1, title: `Result for ${query}` }];return NextResponse.json(results);
  }
  

• 访问：

  • GET /api/search?q=next.js 返回搜索结果。

3.4 集成数据库

使用 Prisma 或 Mongoose 集成数据库。

• 安装 Prisma：

  npm install prisma @prisma/client
  npx prisma init
  

• 代码示例（app/api/posts/route.js）：

  import { PrismaClient } from '@prisma/client';
  import { NextResponse } from 'next/server';const prisma = new PrismaClient();export async function GET() {const posts = await prisma.post.findMany();return NextResponse.json(posts);
  }export async function POST(request) {const body = await request.json();const post = await prisma.post.create({data: {title: body.title,content: body.content,},});return NextResponse.json(post);
  }
  

• 效果：

  • GET /api/posts 返回所有文章。
  • POST /api/posts 创建新文章。

4. Pages Router 中的 API 路由

Pages Router 使用 pages/api/ 目录定义 API 路由。

4.1 基本 API 路由

• 项目结构：

  pages/
  ├── api/
  │   ├── hello.js     # /api/hello
  ├── index.js
  

• 代码示例（pages/api/hello.js）：

  export default function handler(req, res) {if (req.method === 'GET') {res.status(200).json({ message: 'Hello, API!' });} else {res.status(405).json({ error: 'Method Not Allowed' });}
  }
  

• 访问：

  • GET /api/hello 返回 {"message": "Hello, API!"}。

4.2 动态 API 路由

• 项目结构：

  pages/
  ├── api/
  │   ├── users/
  │   │   ├── [id].js  # /api/users/:id
  

• 代码示例（pages/api/users/[id].js）：

  export default function handler(req, res) {const { id } = req.query;if (req.method === 'GET') {res.status(200).json({ id, name: `User ${id}` });} else if (req.method === 'PUT') {const body = req.body;res.status(200).json({ id, ...body });} else {res.status(405).json({ error: 'Method Not Allowed' });}
  }
  

4.3 集成数据库

类似 App Router，使用 Prisma。

• 代码示例（pages/api/posts.js）：

  import { PrismaClient } from '@prisma/client';const prisma = new PrismaClient();export default async function handler(req, res) {if (req.method === 'GET') {const posts = await prisma.post.findMany();res.status(200).json(posts);} else if (req.method === 'POST') {const { title, content } = req.body;const post = await prisma.post.create({data: { title, content },});res.status(201).json(post);} else {res.status(405).json({ error: 'Method Not Allowed' });}
  }
  

5. API 路由的安全性

• 验证请求：

  export async function GET(request) {const token = request.headers.get('authorization');if (!token) {return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });}// 验证 tokenreturn NextResponse.json({ message: 'Authenticated' });
  }
  

• 防止 CSRF：使用 tokens 或 same-site cookies。

• 率限制：使用中间件或库如 rate-limiter-flexible。

• 输入验证：使用 Joi 或 Zod 验证请求体：

  npm install zod
  

• 代码示例：

  import { z } from 'zod';export async function POST(request) {const schema = z.object({title: z.string().min(1),content: z.string().min(10),});const body = await request.json();const validation = schema.safeParse(body);if (!validation.success) {return NextResponse.json({ error: validation.error.errors }, { status: 400 });}// 处理数据return NextResponse.json({ success: true });
  }
  

6. 性能优化

• 缓存响应：

  export async function GET() {// 生成数据const data = { message: 'Cached' };return NextResponse.json(data, {headers: { 'Cache-Control': 's-maxage=60, stale-while-revalidate' },});
  }
  

• 按需加载：使用动态导入减少初次加载。

• 数据库优化：使用连接池（如 Prisma 的内置池）。

• 监控：使用 Vercel Analytics 或 Sentry 监控 API 性能。

7. 使用场景

7.1 表单提交

• 需求：处理表单 POST 请求。

• 代码示例（app/api/form/route.js）：

  export async function POST(request) {const body = await request.json();// 存储到数据库return NextResponse.json({ received: body });
  }
  

• 前端调用：

  'use client';
  import { useState } from 'react';export default function Form() {const [input, setInput] = useState('');const handleSubmit = async () => {const res = await fetch('/api/form', {method: 'POST',headers: { 'Content-Type': 'application/json' },body: JSON.stringify({ input }),});const data = await res.json();console.log(data);};return (<div><input value={input} onChange={(e) => setInput(e.target.value)} /><button onClick={handleSubmit}>提交</button></div>);
  }
  

7.2 数据库 CRUD

• 需求：实现产品 CRUD 操作。

• 代码示例（app/api/products/route.js）：

  import { PrismaClient } from '@prisma/client';const prisma = new PrismaClient();export async function GET() {const products = await prisma.product.findMany();return NextResponse.json(products);
  }export async function POST(request) {const body = await request.json();const product = await prisma.product.create({data: body,});return NextResponse.json(product, { status: 201 });
  }
  

• 代码示例（动态）（app/api/products/[id]/route.js）：

  export async function GET(request, { params }) {const product = await prisma.product.findUnique({where: { id: params.id },});if (!product) return NextResponse.json({ error: 'Not Found' }, { status: 404 });return NextResponse.json(product);
  }export async function PUT(request, { params }) {const body = await request.json();const product = await prisma.product.update({where: { id: params.id },data: body,});return NextResponse.json(product);
  }export async function DELETE(request, { params }) {await prisma.product.delete({where: { id: params.id },});return NextResponse.json({ success: true }, { status: 204 });
  }
  

7.3 第三方 API 集成

• 需求：代理第三方 API 请求。

• 代码示例（app/api/weather/route.js）：

  export async function GET(request) {const { searchParams } = new URL(request.url);const city = searchParams.get('city');const res = await fetch(`https://api.openweathermap.org/data/2.5/weather?q=${city}&appid=your-api-key`);const data = await res.json();return NextResponse.json(data);
  }
  

• 效果：

  • GET /api/weather?city=Beijing 返回天气数据。

8. 中间件集成

在 App Router 中，使用中间件处理 API 请求（如认证）。

• 代码示例（middleware.js）：

  import { NextResponse } from 'next/server';export function middleware(request) {if (request.nextUrl.pathname.startsWith('/api/')) {const token = request.headers.get('authorization');if (!token) {return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });}// 验证 token}return NextResponse.next();
  }export const config = {matcher: '/api/:path*',
  };
  

• 效果：

  • 所有 /api/* 请求需携带 token，否则返回 401。

9. 最佳实践

• 模块化处理：

  // lib/db.js
  import { PrismaClient } from '@prisma/client';export const prisma = new PrismaClient();
  

• 类型安全（TypeScript）：

  interface Post {title: string;content: string;
  }export async function POST(request) {const body: Post = await request.json();// 处理 body
  }
  

• 性能优化：

  • 使用缓存（如 Redis）。
  • 限制请求体大小：

    export const config = {api: {bodyParser: {sizeLimit: '1mb',},},
    };
    

• 安全优化：

  • 验证输入、使用 HTTPS。
  • 防止 SQL 注入，使用 ORM 如 Prisma。

• 日志记录：

  export async function GET() {console.log('API 调用: GET /api/hello');return NextResponse.json({ message: 'Logged' });
  }
  

10. 常见问题及解决方案

问题	解决方案
API 路由未生效	检查目录路径，确保文件名为 route.js 或正确导出处理函数。
动态参数未获取	使用 params（App Router）或 req.query（Pages Router）。
请求方法不匹配	通过 req.method 或方法特定函数处理不同方法。
数据库连接失败	检查 Prisma 配置，确保环境变量正确。
跨域问题	配置 CORS 头：

```js
return NextResponse.json(data, {headers: { 'Access-Control-Allow-Origin': '*' },
});
```                                                                 |

11. 大型项目中的组织

对于大型项目，推荐以下结构：

app/
├── api/
│   ├── auth/
│   │   ├── route.js
│   ├── products/
│   │   ├── [id]/
│   │   │   ├── route.js
│   │   ├── route.js
├── lib/
│   ├── db.js
├── page.tsx

• 模块化数据库：

  // lib/db.js
  import { PrismaClient } from '@prisma/client';export const prisma = new PrismaClient();
  

• 全局配置：

  // next.config.js
  module.exports = {experimental: {serverActions: true,},
  };
  

• 类型定义：

  // types/product.ts
  export interface Product {id: string;name: string;price: number;
  }
  

12. 下一步

掌握 API 路由后，您可以：

• 集成认证系统（如 NextAuth.js）。
• 构建 GraphQL 端点（如 Apollo Server）。
• 配置部署（如 Vercel API 路由）。
• 测试 API 性能和安全。

总结

Next.js 的 API 路由通过文件系统定义后端端点，简化了全栈开发。本文通过详细代码示例，讲解了 API 路由的工作原理和实现方法，结合动态路由、请求处理和数据库集成展示了其灵活性。性能优化、安全最佳实践和错误处理进一步帮助开发者构建高效、可扩展的应用。掌握 API 路由将为您的 Next.js 开发提供强大支持，助力构建完整的全栈 Web 应用。