server 文件夹中的内容，会被自动注册为API和服务器处理程序。

服务器 API

对应路径 server/api

server/api/hello.ts

export default defineEventHandler((event) => {
  return {
    hello: 'world'
  }
})

页面中使用

<script setup lang="ts">
const { data } = await useFetch('/api/hello')
</script>

<template>
  <pre>{{ data }}</pre>
</template>

动态参数 []

server/api/hello/[name].ts

export default defineEventHandler((event) => {
  const name = getRouterParam(event, 'name')

  return `Hello, ${name}!`
})

[…slug].ts 全匹配

捕获所有API，并通过 event.context.params.slug 访问匹配的内容

export default defineEventHandler((event) => {
  // 访问 /api/bar/baz ，则 event.context.params.slug 获取路由段：'bar/baz'
  return `Default foo handler`
})

定义HTTP方法

文件名中使用.get、.post、.put、.delete等后缀来定义HTTP方法

server/api/test.get.ts

export default defineEventHandler(() => 'Test get handler')

GET方法请求 /test 会返回Test get handler

获取 GET 方法中的参数 getQuery

如查询 /api/query?foo=bar&baz=qux

server/api/query.get.ts

export default defineEventHandler((event) => {
  const query = getQuery(event)

  return { a: query.foo, b: query.baz }
})

获取 POST 中的请求体 readBody

server/api/submit.post.ts

export default defineEventHandler(async (event) => {
  const body = await readBody(event)
  return { body }
})

获取运行时配置 useRuntimeConfig

export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig(event)

  const repo = await $fetch('https://api.github.com/repos/nuxt/nuxt', {
    headers: {
      Authorization: `token ${config.githubToken}`
    }
  })

  return repo
})

配置信息在 nuxt.config.ts 中定义

export default defineNuxtConfig({
  runtimeConfig: {
    githubToken: ''
  }
})

获取 Cookie 信息 parseCookies

export default defineEventHandler((event) => {
  const cookies = parseCookies(event)

  return { cookies }
})

错误处理

  • 没有抛出错误，将返回状态码200 OK
  • 任何未捕获的错误都将返回500 Internal Server Error
  • 返回其他错误代码，请使用createError抛出异常

server/api/validation/[id].ts

export default defineEventHandler((event) => {
  const id = parseInt(event.context.params.id) as number

  if (!Number.isInteger(id)) {
    throw createError({
      statusCode: 400,
      statusMessage: 'ID should be an integer',
    })
  }
  return 'All good'
})

状态码

返回其他状态码，请使用setResponseStatus实用程序。

server/api/validation/[id].ts

export default defineEventHandler((event) => {
  // 返回202 Accepted
  setResponseStatus(event, 202)
})

重定向 sendRedirect

export default defineEventHandler(async (event) => {
  await sendRedirect(event, '/path/redirect/to', 302)
})

服务器路由

对应路径 server/routes

server/routes/hello.ts

export default defineEventHandler(() => 'Hello World!')

即定义了 /hello 路由

服务器中间件

对应路径 server/middleware

中间件处理程序将在任何其他服务器路由之前在每个请求上运行，以添加或检查标头、记录请求或扩展事件的请求对象。

  • 中间件处理程序不应返回任何内容（也不应关闭或响应请求），只能检查或扩展请求上下文或抛出错误。

server/middleware/log.ts

export default defineEventHandler((event) => {
  console.log('New request: ' + getRequestURL(event))
})

server/middleware/auth.ts

export default defineEventHandler((event) => {
  event.context.auth = { user: 123 }
})

服务器插件

对应路径 server/plugins

它们会被注册为Nitro插件。这允许扩展Nitro的运行时行为并钩入生命周期事件。

server/plugins/nitroPlugin.ts

export default defineNitroPlugin((nitroApp) => {
  console.log('Nitro plugin', nitroApp)
})

服务器工具

对应路径 server/utils

可以添加更多的自定义辅助函数

server/utils/handler.ts

import type { EventHandler, EventHandlerRequest } from 'h3'

export const defineWrappedResponseHandler = <T extends EventHandlerRequest, D> (
  handler: EventHandler<T, D>
): EventHandler<T, D> =>
  defineEventHandler<T>(async event => {
    try {
      // 在路由处理程序之前执行某些操作
      const response = await handler(event)
      // 在路由处理程序之后执行某些操作
      return { response }
    } catch (err) {
      // 错误处理
      return { err }
    }
  })

服务器类型

对应路径 server/tsconfig.json Nuxt >= 3.5 版本中可用

下方代码可提高IDE中对来自’nitro’和’vue’的自动导入的清晰度
server/tsconfig.json

{
  "extends": "../.nuxt/tsconfig.server.json"
}

服务器类型

对应路径 server/tsconfig.json