编辑“︁Next.js动态API路由”︁（章节）

= Next.js动态API路由 =

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

动态API路由常用于以下场景：  
* 根据URL参数查询数据库  
* 构建RESTful API接口  
* 处理用户个性化请求  

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

=== 示例代码 ===  
<syntaxhighlight lang="javascript">  
// pages/api/users/[id].js  
export default function handler(req, res) {  
  const { id } = req.query;  
  res.status(200).json({ userId: id, name: `User ${id}` });  
}  
</syntaxhighlight>  

=== 输入与输出 ===  
* '''请求URL'''：<code>/api/users/123</code>  
* '''响应'''：  
<syntaxhighlight lang="json">  
{  
  "userId": "123",  
  "name": "User 123"  
}  
</syntaxhighlight>  

== 多参数路由 ==  
支持多个动态参数，文件名格式为<code>[param1]/[param2].js</code>。

=== 示例代码 ===  
<syntaxhighlight lang="javascript">  
// pages/api/products/[category]/[productId].js  
export default function handler(req, res) {  
  const { category, productId } = req.query;  
  res.status(200).json({ category, productId });  
}  
</syntaxhighlight>  

=== 输入与输出 ===  
* '''请求URL'''：<code>/api/products/electronics/789</code>  
* '''响应'''：  
<syntaxhighlight lang="json">  
{  
  "category": "electronics",  
  "productId": "789"  
}  
</syntaxhighlight>  

== 实际应用场景 ==  
=== 案例：博客系统API ===  
动态路由可用于根据文章ID返回不同内容：  
<syntaxhighlight lang="javascript">  
// 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);  
}  
</syntaxhighlight>  

== 高级用法 ==  
=== 匹配所有路径 ===  
使用<code>[...slug].js</code>捕获所有子路径，参数以数组形式返回：  
<syntaxhighlight lang="javascript">  
// pages/api/[...slug].js  
export default function handler(req, res) {  
  const { slug } = req.query;  
  res.status(200).json({ path: slug }); // slug是数组  
}  
</syntaxhighlight>  

* '''请求URL'''：<code>/api/a/b/c</code>  
* '''响应'''：  
<syntaxhighlight lang="json">  
{  
  "path": ["a", "b", "c"]  
}  
</syntaxhighlight>  

=== 可选捕获 ===  
通过<code>[[...slug]].js</code>使动态参数可选：  
<syntaxhighlight lang="javascript">  
// pages/api/[[...slug]].js  
export default function handler(req, res) {  
  const { slug = [] } = req.query;  
  res.status(200).json({ path: slug });  
}  
</syntaxhighlight>  

* '''请求URL'''：<code>/api</code>  
* '''响应'''：  
<syntaxhighlight lang="json">  
{  
  "path": []  
}  
</syntaxhighlight>  

== 与其他Next.js功能集成 ==  
动态API路由可与以下功能结合使用：  
* '''Middleware'''：在路由处理前执行逻辑（如身份验证）  
* '''TypeScript'''：为参数添加类型定义  
* '''ISR（增量静态生成）'''：动态生成静态页面  

=== 类型安全示例（TypeScript） ===  
<syntaxhighlight lang="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}` });  
}  
</syntaxhighlight>  

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

== 数学公式（可选） ==  
动态路由的匹配规则可表示为：  
<math>  
R(p) = \begin{cases}  
\text{参数对象}, & \text{当路径 } p \text{ 匹配 } [param]\text{ 模式} \\  
\text{null}, & \text{否则}  
\end{cases}  
</math>  

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

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

[[Category:后端框架]]
[[Category:Next.js]]
[[Category:Next.js数据获取]]