Next.js动态API路由

Next.js动态API路由

介绍

Next.js动态API路由（Dynamic API Routes）是Next.js框架中一种强大的功能，允许开发者基于动态参数创建灵活的API端点。与静态路由不同，动态路由可以根据URL中的变量生成不同的响应，适用于处理动态数据请求（如用户ID、产品名称等）。此功能基于文件系统路由（File-system Routing），通过文件名约定（如[param].js）实现。

动态API路由常用于以下场景：

• 根据URL参数查询数据库
• 构建RESTful API接口
• 处理用户个性化请求

基本语法

在Next.js中，动态API路由通过在pages/api目录下创建带有方括号的文件（如[id].js）实现。参数通过req.query对象传递。

示例代码

  
// pages/api/users/[id].js  
export default function handler(req, res) {  
  const { id } = req.query;  
  res.status(200).json({ userId: id, name: `User ${id}` });  
}

输入与输出

• 请求URL：/api/users/123
• 响应：

  
{  
  "userId": "123",  
  "name": "User 123"  
}

多参数路由

支持多个动态参数，文件名格式为[param1]/[param2].js。

示例代码

  
// pages/api/products/[category]/[productId].js  
export default function handler(req, res) {  
  const { category, productId } = req.query;  
  res.status(200).json({ category, productId });  
}

输入与输出

• 请求URL：/api/products/electronics/789
• 响应：

  
{  
  "category": "electronics",  
  "productId": "789"  
}

实际应用场景

案例：博客系统API

动态路由可用于根据文章ID返回不同内容：

  
// pages/api/posts/[postId].js  
import { getPostById } from '../../../lib/posts';  

export default async function handler(req, res) {  
  const { postId } = req.query;  
  const post = await getPostById(postId);  
  if (!post) return res.status(404).json({ error: 'Post not found' });  
  res.status(200).json(post);  
}

高级用法

匹配所有路径

使用[...slug].js捕获所有子路径，参数以数组形式返回：

  
// pages/api/[...slug].js  
export default function handler(req, res) {  
  const { slug } = req.query;  
  res.status(200).json({ path: slug }); // slug是数组  
}

• 请求URL：/api/a/b/c
• 响应：

  
{  
  "path": ["a", "b", "c"]  
}

可选捕获

通过...slug.js使动态参数可选：

  
// pages/api/[[...slug]].js  
export default function handler(req, res) {  
  const { slug = [] } = req.query;  
  res.status(200).json({ path: slug });  
}

• 请求URL：/api
• 响应：

  
{  
  "path": []  
}

与其他Next.js功能集成

动态API路由可与以下功能结合使用：

• Middleware：在路由处理前执行逻辑（如身份验证）
• TypeScript：为参数添加类型定义
• ISR（增量静态生成）：动态生成静态页面

类型安全示例（TypeScript）

  
import { NextApiRequest, NextApiResponse } from 'next';  

interface ResponseData {  
  userId: string;  
  name: string;  
}  

export default function handler(  
  req: NextApiRequest,  
  res: NextApiResponse<ResponseData>  
) {  
  const { id } = req.query as { id: string };  
  res.status(200).json({ userId: id, name: `User ${id}` });  
}

流程图：请求处理流程

graph LR A[客户端请求 /api/users/123] --> B[Next.js服务器] B --> C{匹配动态路由?} C -->|是| D[执行 pages/api/users/[id].js] C -->|否| E[返回404] D --> F[返回JSON响应]

数学公式（可选）

动态路由的匹配规则可表示为： $R(p)=\{\begin{array}{ll}\text{参数对象},& \text{当路径 }p\text{ 匹配 }[param]\text{ 模式}\\ \text{null},& \text{否则}\end{array}$

注意事项

1. 动态路由文件必须放在pages/api目录下 2. 参数名称需与文件名中的占位符一致（如[id]对应req.query.id） 3. 生产环境中需添加错误处理和输入验证

总结

Next.js动态API路由通过文件系统约定简化了灵活API的构建，适合从简单CRUD到复杂RESTful服务的各种场景。结合TypeScript和中间件，可进一步提升开发效率与代码安全性。