API Routes

示例

• Basic API Routes
• [API Routes with GraphQL](https://github.com/vercel/next.js/tree/canary/examples/api-routes-graphql
• API Routes with REST
• API Routes with CORS

API路由提供了一个用Next.js构建API的解决方案。

pages/api文件夹中的任何文件都映射到/api/*，将被视为api端点而不是page。它们只是服务器端捆绑包，不会增加客户端捆绑包的大小。

例如，下面的API路由pages/api/user.js返回一个json响应，状态码为200:

export default function handler(req, res) {
  res.status(200).json({ name: 'John Doe' })
}

注意: API路由将受到next.config.js中的pageExtensions配置的影响。

为了让API路由正常工作，你需要导出一个默认的函数(又名请求处理程序)，然后它会接收以下参数:

• req: 一个http.IncomingMessage的实例，再加上pre-built middlewares
• res: 一个http.ServerResponse的实例，再加上helper functions

要在一个API路由中处理不同的HTTP方法，你可以使用req.method，像这样:

export default function handler(req, res) {
  if (req.method === 'POST') {
    // Process a POST request
  } else {
    // Handle any other HTTP method
  }
}

要获取API端点，请查看本节开头的任何示例。

用例

对于新项目，你可以用API Routes构建你的整个API。如果已有API，则不需要通过API路由将调用转发到该API。API路由的一些其他用例是:

• 屏蔽外部服务的URL(如/api/secret而不是https://company.com/secret-url)
• 在服务器上使用环境变量安全地访问外部服务。

说明

• API路由不指定CORS报头这意味着它们默认是同源的。您可以通过使用CORS请求助手包装请求处理程序来定制此类行为。
• API路由不能与next export一起使用。

联系

关于下一步的更多信息，我们推荐以下部分: