编辑“︁Next.js API路由”︁

= Next.js API路由 =

== 介绍 ==
'''Next.js API路由'''是Next.js框架提供的一项核心功能，允许开发者在同一项目中创建后端API端点，无需单独配置服务器。这些API路由位于<code>pages/api</code>目录下，每个文件会自动映射为一个HTTP端点，支持常见的请求方法（GET、POST、PUT等）。API路由基于Node.js运行时，适合处理表单提交、数据库操作或第三方服务集成等场景。

== 基本结构 ==
Next.js API路由的文件系统遵循以下规则：
* 文件路径：<code>pages/api/</code>目录下的<code>.js</code>或<code>.ts</code>文件
* 路由映射：文件路径直接对应URL路径（例如<code>pages/api/user.js</code> → <code>/api/user</code>）
* 默认导出：每个文件需导出一个请求处理函数，接收<code>req</code>（请求对象）和<code>res</code>（响应对象）参数

=== 示例代码 ===
<syntaxhighlight lang="javascript">
// pages/api/hello.js
export default function handler(req, res) {
  if (req.method === 'GET') {
    res.status(200).json({ message: 'Hello from Next.js!' })
  } else {
    res.setHeader('Allow', ['GET'])
    res.status(405).end(`Method ${req.method} Not Allowed`)
  }
}
</syntaxhighlight>

'''输入'''：<code>GET /api/hello</code><br>
'''输出'''：<code>{ "message": "Hello from Next.js!" }</code>

== 请求方法处理 ==
API路由可通过<code>req.method</code>区分HTTP方法，实现RESTful接口：

<syntaxhighlight lang="javascript">
// pages/api/tasks.js
export default function handler(req, res) {
  switch (req.method) {
    case 'GET':
      // 获取任务列表
      res.status(200).json(tasks)
      break
    case 'POST':
      // 创建新任务
      const newTask = JSON.parse(req.body)
      tasks.push(newTask)
      res.status(201).json(newTask)
      break
    default:
      res.setHeader('Allow', ['GET', 'POST'])
      res.status(405).end()
  }
}
</syntaxhighlight>

== 动态路由 ==
支持动态参数，文件名使用<code>[param]</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 })
}
</code>

'''访问'''：<code>/api/users/123</code> → 输出<code>{ "userId": "123" }</code>

== 中间件支持 ==
可通过高阶函数实现中间件逻辑：

<syntaxhighlight lang="javascript">
// 身份验证中间件示例
const withAuth = (handler) => (req, res) => {
  const token = req.headers.authorization
  if (!token) return res.status(401).end()
  return handler(req, res)
}

export default withAuth((req, res) => {
  res.status(200).json({ secretData: 'Authenticated!' })
})
</syntaxhighlight>

== 配置选项 ==
通过导出<code>config</code>对象自定义行为：

<syntaxhighlight lang="javascript">
export const config = {
  api: {
    bodyParser: false, // 禁用默认body解析
    externalResolver: true, // 声明使用外部解析器
  }
}
</syntaxhighlight>

== 实际应用案例 ==
'''场景'''：构建一个天气查询API
<syntaxhighlight lang="javascript">
// pages/api/weather/[city].js
import axios from 'axios'

export default async function handler(req, res) {
  const { city } = req.query
  const API_KEY = process.env.WEATHER_API_KEY
  
  try {
    const response = await axios.get(
      `https://api.weatherapi.com/v1/current.json?key=${API_KEY}&q=${city}`
    )
    res.status(200).json(response.data)
  } catch (error) {
    res.status(500).json({ error: 'Failed to fetch weather data' })
  }
}
</syntaxhighlight>

== 性能优化 ==
<mermaid>
graph LR
  A[客户端请求] --> B[Edge Network]
  B --> C{API路由}
  C -->|静态生成| D[CDN缓存]
  C -->|动态渲染| E[Serverless Function]
</mermaid>

* '''静态生成'''：适合不常变的数据，通过<code>getStaticProps</code>预渲染
* '''动态渲染'''：实时数据使用<code>getServerSideProps</code>或直接API调用

== 数学表示 ==
API响应时间模型（单位：毫秒）：
<math>
T_{total} = T_{network} + T_{processing} + \sum_{i=1}^{n} (T_{db_i})
</math>

== 常见问题 ==
* '''CORS问题'''：默认同源策略，需手动配置CORS头
* '''环境变量'''：使用<code>process.env</code>访问，需在<code>next.config.js</code>中配置
* '''冷启动'''：Serverless函数首次调用可能有延迟

== 进阶技巧 ==
1. '''批量请求'''：使用<code>Promise.all</code>处理并行请求
2. '''类型安全'''（TypeScript）：
   <syntaxhighlight lang="typescript">
   import type { NextApiRequest, NextApiResponse } from 'next'
   
   type ResponseData = {
     data?: string
     error?: string
   }
   
   export default function handler(
     req: NextApiRequest,
     res: NextApiResponse<ResponseData>
   ) { ... }
   </syntaxhighlight>

== 总结 ==
Next.js API路由提供了一种轻量级后端解决方案，特点包括：
* 无额外服务器配置
* 自动路由映射
* 支持中间件模式
* 与前端代码共置
* 适合全栈JavaScript开发

通过合理设计，可构建从简单CRUD到复杂微服务网关的各种API应用。

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