Guide

服务器路由

Nitro 支持文件系统路由,自动将文件映射到 h3 路由。

事件处理器

事件处理程序是一个将被绑定到路由的函数,当路由被路由器匹配到传入请求时将执行该函数。

Read more in h3.unjs.io/guide/event-handler.

文件系统路由

Nitro 支持基于文件的 API 路由(文件自动映射到 h3 路由)。定义一个路由只需要在 server/api/server/routes/ 目录中创建一个文件。

每个文件只能定义一个处理程序,你可以 将 HTTP 方法附加 到文件名,以定义一个特定的请求方法。

server/
  api/
    test.ts      <-- /api/test
  routes/
    hello.get.ts     <-- GET /hello
    hello.post.ts    <-- POST /hello
nitro.config.ts

你可以通过创建子目录来嵌套路由。

server/
  routes/
    communities/
      index.get.ts
      index.post.ts
      [id]/
        index.get.ts
        index.post.ts
    hello.get.ts
    hello.post.ts
一些提供商如 Vercel 使用顶级的 /api/ 目录作为特性,因此放置在 /api 下的路由将无法工作。 你将需要使用 server/routes/api/

简单路由

首先,在 server/routes/server/api/ 目录中创建一个文件。文件名将作为路由路径。

然后,导出一个用 defineEventHandler 包装的函数,当路由匹配时将被执行。

server/api/test.ts
export default defineEventHandler(() => {
  return { hello: 'API' }
})

带参数的路由

单个参数

要定义具有参数的路由,请使用 [<param>] 语法,其中 <param> 是参数的名称。该参数将可在 event.context.params 对象中使用,或使用来自 unjs/h3getRouterParam 工具。

server/routes/hello/[name].ts
export default defineEventHandler(event => {
  const name = getRouterParam(event, 'name')

  return `Hello ${name}!`
})

调用带参数的路由 /hello/nitro,你将得到:

Response
Hello nitro!

多个参数

你可以使用 [<param1>]/[<param2>] 语法在一个路由中定义多个参数,其中每个参数是一个文件夹。你 不能 在单个文件名或文件夹中定义多个参数。

server/routes/hello/[name]/[age].ts
export default defineEventHandler(event => {
  const name = getRouterParam(event, 'name')
  const age = getRouterParam(event, 'age')

  return `Hello ${name}! You are ${age} years old.`
})

捕获所有参数

你可以使用 [...<param>] 语法捕获 URL 的所有剩余部分。这将包括参数中的 /

server/routes/hello/[...name].ts
export default defineEventHandler(event => {
  const name = getRouterParam(event, 'name')

  return `Hello ${name}!`
})

调用带参数的路由 /hello/nitro/is/hot,你将得到:

Response
Hello nitro/is/hot!

特定请求方法

你可以将 HTTP 方法附加到文件名,以强制路由仅匹配特定的 HTTP 请求方法,例如 hello.get.ts 只会匹配 GET 请求。你可以使用任何你想要的 HTTP 方法。

// server/routes/users/[id].get.ts
export default defineEventHandler(async (event) => {
  const id = getRouterParam(event, 'id')

  // 做一些与 id 相关的操作

  return `User profile!`
})

捕获所有路由

你可以创建一个特殊的路由,匹配所有未被任何其他路由匹配的路由。这对于创建默认路由很有用。

要创建一个捕获所有路由,请在 server/routes/server/api/ 目录或任何子目录中创建一个名为 [...].ts 的文件。

server/routes/[...].ts
export default defineEventHandler(event => {
  const url = getRequestURL(event)

  return `Hello ${url}!`
})

环境特定处理程序

你可以通过在文件名后添加 .dev.prod.prerender 后缀,指定仅在特定构建中包含的路由,例如:routes/test.get.dev.tsroutes/test.get.prod.ts

你可以通过使用 handlers[] 配置的编程注册路径,指定多个环境或使用预设名称作为环境。

中间件

Nitro 路由中间件可以钩入请求生命周期。

中间件可以在请求被处理之前修改请求,而不是之后。
Read more in h3.unjs.io/guide/event-handler#middleware.

中间件会自动在 server/middleware/ 目录中注册。

server/
  routes/
    hello.ts
  middleware/
    auth.ts
    logger.ts
    ...
nitro.config.ts

简单中间件

中间件的定义与路由处理程序完全相同,唯一的例外是在于它们不应返回任何内容。 从中间件返回的内容会像从请求返回一样 - 返回的值将作为响应返回,后续代码将不再运行。

server/middleware/auth.ts
export default defineEventHandler((event) => {
  // 扩展或修改事件
  event.context.user = { name: 'Nitro' }
})

位于 server/middleware/ 目录中的中间件会自动对所有路由注册。如果你想为特定路由注册中间件,请参见 对象语法事件处理程序

从中间件返回任何内容将关闭请求,应避免这样做!从中间件返回的任何值都会成为响应,并且后续代码不会被执行,但 这并不推荐这样做!

路由元信息

你可以在构建时通过 defineRouteMeta 微功能在事件处理程序文件中定义路由处理程序元信息。

🚧 此功能当前为实验性功能。
server/api/test.ts
defineRouteMeta({
  openAPI: {
    tags: ["test"],
    description: "测试路由描述",
    parameters: [{ in: "query", name: "test", required: true }],
  },
});

export default defineEventHandler(() => "OK");
此功能当前可用于指定 OpenAPI 元信息。有关可用的 OpenAPI 选项,请参见 swagger 规范。

执行顺序

中间件按目录列表顺序执行。

server/
  middleware/
    auth.ts <-- 首先
    logger.ts <-- 其次
    ... <-- 第三

使用数字作为前缀来控制它们的执行顺序。

server/
  middleware/
    1.logger.ts <-- 首先
    2.auth.ts <-- 其次
    3.... <-- 第三
请记住,文件名按字符串排序,因此,如果你有 3 个文件 1.filename.ts2.filename.ts10.filename.ts,那么 10.filename.ts 将在 1.filename.ts 之后。如果你有超过 10 个中间件在同一目录中,可以将 1-9 前缀加上 0,比如 01

请求过滤

中间件在每个请求上执行。

应用自定义逻辑,以将它们范围缩小到特定条件。

例如,你可以使用 URL 为特定路由应用中间件:

server/middleware/auth.ts
export default defineEventHandler((event) => {
  // 仅在 /auth 路由执行
  if (getRequestURL(event).pathname.startsWith('/auth')) {
    event.context.user = { name: 'Nitro' }
  }
})

错误处理

你可以使用 H3 中可用的工具 来处理路由和中间件中的错误。

错误返回给客户端的方式取决于路由的路径。对于大多数路由,Content-Type 默认设置为 text/html,并提供一个简单的 HTML 错误页面。如果路由以 /api/ 开头(无论是因为它放置在 api/ 还是 routes/api/ 中),默认值将更改为 application/json 并发送一个 JSON 对象。

此行为可以通过某些请求属性(例如:AcceptUser-Agent 头)进行覆盖。

路由规则

Nitro 允许你在配置的顶层为每个路由添加逻辑。它可以用于重定向、代理、缓存和向路由添加头信息。

它是从路由模式(遵循 unjs/radix3)到路由选项的映射。

当设置 cache 选项时,匹配模式的处理程序将自动包裹在 defineCachedEventHandler 中。请参见 缓存指南 以了解有关此功能的更多信息。

swr: true|numbercache: { swr: true, maxAge: number } 的简写。

你可以使用 routeRules 选项在 nitro.config.ts 中设置路由规则。

export default defineNitroConfig({
  routeRules: {
    '/blog/**': { swr: true },
    '/blog/**': { swr: 600 },
    '/blog/**': { static: true },
    '/blog/**': { cache: { /* 缓存选项 */ } },
    '/assets/**': { headers: { 'cache-control': 's-maxage=0' } },
    '/api/v1/**': { cors: true, headers: { 'access-control-allow-methods': 'GET' } },
    '/old-page': { redirect: '/new-page' },
    '/old-page/**': { redirect: '/new-page/**' },
    '/proxy/example': { proxy: 'https://example.com' },
    '/proxy/**': { proxy: '/api/**' },
  }
})