API 路由
API 路由提供了一种在 Next.js 中构建公共 API 的解决方案。
pages/api
文件夹中的任何文件都映射到 /api/*
,并将被视为 API 端点而非页面。它们是仅服务端的包,不会增加客户端打包大小。
例如,以下 API 路由返回状态码为 200
的 JSON 响应:
import type { NextApiRequest, NextApiResponse } from 'next'
type ResponseData = {
message: string
}
export default function handler(
req: NextApiRequest,
res: NextApiResponse<ResponseData>
) {
res.status(200).json({ message: 'Hello from Next.js!' })
}
值得注意的是:
- API 路由不指定 CORS 标头,意味着默认情况下它们是仅同源的。你可以通过使用 CORS 请求助手包装请求处理程序来自定义此行为。
- API 路由不能与静态导出一起使用。但是,App Router 中的路由处理程序可以。
- API 路由将受到
next.config.js
中pageExtensions
配置的影响。
- API 路由将受到
参数
export default function handler(req: NextApiRequest, res: NextApiResponse) {
// ...
}
req
:http.IncomingMessage 的实例res
:http.ServerResponse 的实例
HTTP 方法
要在 API 路由中处理不同的 HTTP 方法,你可以在请求处理程序中使用 req.method
,如下所示:
import type { NextApiRequest, NextApiResponse } from 'next'
export default function handler(req: NextApiRequest, res: NextApiResponse) {
if (req.method === 'POST') {
// 处理 POST 请求
} else {
// 处理任何其他 HTTP 方法
}
}
请求助手
API 路由提供内置的请求助手,用于解析传入的请求(req
):
req.cookies
- 包含请求发送的 cookie 的对象。默认为{}
req.query
- 包含查询字符串的对象。默认为{}
req.body
- 包含由content-type
解析的正文的对象,如果未发送正文,则为null
自定义配置
每个 API 路由都可以导出一个 config
对象来更改默认配置,默认配置如下:
export const config = {
api: {
bodyParser: {
sizeLimit: '1mb',
},
},
// 指定此函数执行的最大允许持续时间(以秒为单位)
maxDuration: 5,
}
bodyParser
默认启用。如果你想将正文作为 Stream
或使用 raw-body
,可以将其设置为 false
。
禁用自动 bodyParsing
的一个用例是允许你验证 webhook 请求的原始正文,例如来自 GitHub。
export const config = {
api: {
bodyParser: false,
},
}
bodyParser.sizeLimit
是允许解析的正文的最大大小,支持 bytes 支持的任何格式,如:
export const config = {
api: {
bodyParser: {
sizeLimit: '500kb',
},
},
}
externalResolver
是一个显式标志,告诉服务器此路由由外部解析器(如 express 或 connect)处理。启用此选项将禁用未解析请求的警告。
export const config = {
api: {
externalResolver: true,
},
}
responseLimit
默认启用,当 API 路由的响应正文超过 4MB 时发出警告。
如果你不在无服务器环境中使用 Next.js,并且了解不使用 CDN 或专用媒体主机的性能影响,可以将此限制设置为 false
。
export const config = {
api: {
responseLimit: false,
},
}
responseLimit
还可以接受字节数或 bytes
支持的任何字符串格式,例如 1000
、'500kb'
或 '3mb'
。
此值将是显示警告之前的最大响应大小。默认为 4MB。(见上文)
export const config = {
api: {
responseLimit: '8mb',
},
}
响应助手
服务器响应对象(通常缩写为 res
)包含一组类似 Express.js 的辅助方法,以改善开发者体验并加快创建新 API 端点的速度。
包含的辅助方法有:
res.status(code)
- 设置状态码的函数。code
必须是有效的 HTTP 状态码res.json(body)
- 发送 JSON 响应。body
必须是可序列化的对象res.send(body)
- 发送 HTTP 响应。body
可以是string
、object
或Buffer
res.redirect([status,] path)
- 重定向到指定的路径或 URL。status
必须是有效的 HTTP 状态码。如果未指定,status
默认为 "307" "临时重定向"。res.revalidate(urlPath)
- 按需重新验证页面使用getStaticProps
。urlPath
必须是string
。
设置响应的状态码
当向客户端发送响应时,你可以设置响应的状态码。
以下示例将响应的状态码设置为 200
(OK
),并返回一个 message
属性,其值为 Hello from Next.js!
作为 JSON 响应:
import type { NextApiRequest, NextApiResponse } from 'next'
type ResponseData = {
message: string
}
export default function handler(
req: NextApiRequest,
res: NextApiResponse<ResponseData>
) {
res.status(200).json({ message: 'Hello from Next.js!' })
}
发送 JSON 响应
当向客户端发送响应时,你可以发送 JSON 响应,这必须是可序列化的对象。 在真实的应用程序中,你可能希望根据请求端点的结果让客户端了解请求的状态。
以下示例发送状态码为 200
(OK
)的 JSON 响应和异步操作的结果。它包含在 try catch 块中,以处理可能发生的任何错误,并将捕获的适当状态码和错误消息发送回客户端:
import type { NextApiRequest, NextApiResponse } from 'next'
export default async function handler(
req: NextApiRequest,
res: NextApiResponse
) {
try {
const result = await someAsyncOperation()
res.status(200).json({ result })
} catch (err) {
res.status(500).json({ error: 'failed to load data' })
}
}
发送 HTTP 响应
发送 HTTP 响应的方式与发送 JSON 响应相同。唯一的区别是响应正文可以是 string
、object
或 Buffer
。
以下示例发送状态码为 200
(OK
)的 HTTP 响应和异步操作的结果。
import type { NextApiRequest, NextApiResponse } from 'next'
export default async function handler(
req: NextApiRequest,
res: NextApiResponse
) {
try {
const result = await someAsyncOperation()
res.status(200).send({ result })
} catch (err) {
res.status(500).send({ error: 'failed to fetch data' })
}
}
重定向到指定路径或 URL
以表单为例,你可能希望在客户端提交表单后将其重定向到指定路径或 URL。
以下示例在表单成功提交后将客户端重定向到 /
路径:
import type { NextApiRequest, NextApiResponse } from 'next'
export default async function handler(
req: NextApiRequest,
res: NextApiResponse
) {
const { name, message } = req.body
try {
await handleFormInputAsync({ name, message })
res.redirect(307, '/')
} catch (err) {
res.status(500).send({ error: 'Failed to fetch data' })
}
}
添加 TypeScript 类型
你可以通过从 next
导入 NextApiRequest
和 NextApiResponse
类型,使你的 API 路由更加类型安全,此外,你还可以为响应数据添加类型:
import type { NextApiRequest, NextApiResponse } from 'next'
type ResponseData = {
message: string
}
export default function handler(
req: NextApiRequest,
res: NextApiResponse<ResponseData>
) {
res.status(200).json({ message: '来自 Next.js 的问候!' })
}
值得注意的是:
NextApiRequest
的 body 是any
,因为客户端可能包含任何负载。你应该在使用之前在运行时验证 body 的类型/形状。
动态 API 路由
API 路由支持动态路由,并遵循与 pages/
相同的文件命名规则。
import type { NextApiRequest, NextApiResponse } from 'next'
export default function handler(req: NextApiRequest, res: NextApiResponse) {
const { pid } = req.query
res.end(`文章:${pid}`)
}
现在,对 /api/post/abc
的请求将响应文本:文章:abc
。
捕获所有 API 路由
通过在括号内添加三个点(...
),API 路由可以扩展以捕获所有路径。例如:
pages/api/post/[...slug].js
匹配/api/post/a
,同时也匹配/api/post/a/b
、/api/post/a/b/c
等。
值得注意的是:你可以使用除
slug
之外的名称,如:[...param]
匹配的参数将作为查询参数(示例中的 slug
)发送到页面,并且它将始终是一个数组,因此路径 /api/post/a
将具有以下 query
对象:
{ "slug": ["a"] }
对于 /api/post/a/b
,以及任何其他匹配的路径,新参数将被添加到数组中,如下所示:
{ "slug": ["a", "b"] }
例如:
import type { NextApiRequest, NextApiResponse } from 'next'
export default function handler(req: NextApiRequest, res: NextApiResponse) {
const { slug } = req.query
res.end(`文章:${slug.join(', ')}`)
}
现在,对 /api/post/a/b/c
的请求将响应文本:文章:a, b, c
。
可选的捕获所有 API 路由
通过在双括号中包含参数([[...slug]]
),捕获所有路由可以变为可选。
例如,pages/api/post/[[...slug]].js
将匹配 /api/post
、/api/post/a
、/api/post/a/b
等。
主要区别在于,使用可选捕获的路由也匹配没有参数的路由(上例中的 /api/post
)。
query
对象如下:
{ } // GET `/api/post`(空对象)
{ "slug": ["a"] } // `GET /api/post/a`(单元素数组)
{ "slug": ["a", "b"] } // `GET /api/post/a/b`(多元素数组)
注意事项
- 预定义的 API 路由优先于动态 API 路由,动态 API 路由优先于捕获所有 API 路由。看看以下示例:
pages/api/post/create.js
- 将匹配/api/post/create
pages/api/post/[pid].js
- 将匹配/api/post/1
、/api/post/abc
等。但不匹配/api/post/create
pages/api/post/[...slug].js
- 将匹配/api/post/1/2
、/api/post/a/b/c
等。但不匹配/api/post/create
、/api/post/abc
Edge API 路由
如果你想使用 Edge Runtime 的 API 路由,我们建议逐步采用 App Router 并改用路由处理程序。
路由处理程序的函数签名是同构的,这意味着你可以对 Edge 和 Node.js 运行时使用相同的函数。