请求 Request

用于访问传入请求的实用程序

`assertMethod(event, expected, allowHead?)`

使用 isMethod 断言传入的请求方法属于预期类型。

如果不允许该方法，它将抛出 405 错误，并显示消息“不允许 HTTP 方法”。

如果 allowHead 为 true，则如果预期方法是 GET，它将允许 HEAD 请求通过。

示例：

export default defineEventHandler((event) => {
  assertMethod(event, 'GET')
  // 处理 GET 请求，否则抛出 405 错误
})

`getQuery(event)`

从使用 unjs/ufo 解析的请求 URL 中获取查询 params 对象。

示例：

export default defineEventHandler((event) => {
  const query = getQuery(event) // { key: "value", key2: ["value1", "value2"] }
})

`getRequestHeader(event, name)`

按名称获取请求标头。

示例：

export default defineEventHandler((event) => {
  const contentType = getRequestHeader(event, 'content-type') // "application/json"
})

`getRequestHeaders(event)`

获取请求标头对象。

数组标头用逗号连接。

示例：

export default defineEventHandler((event) => {
  const headers = getRequestHeaders(event) // { "content-type": "application/json", "x-custom-header": "value" }
})

`getRequestHost(event, opts: { xForwardedHost? })`

获取请求主机名。

如果 xForwardedHost 为 true，则将使用 x-forwarded-host 标头（如果存在）。

如果未找到主机标头，则将默认为“localhost”。

示例：

export default defineEventHandler((event) => {
  const host = getRequestHost(event) // "example.com"
})

`getRequestIP(event)`

尝试从传入请求中获取客户端 IP 地址。

如果 xForwardedFor 为 true，它将使用 x-forwarded-for 标头（如果存在）。

如果无法确定 IP，它将默认为 undefined。

示例：

export default defineEventHandler((event) => {
  const ip = getRequestIP(event) // "192.0.2.0"
})

`getRequestProtocol(event, opts: { xForwardedProto? })`

获取请求协议。

如果 x-forwarded-proto 标头设置为“https”，它将返回“https”。您可以通过将 xForwardedProto 设置为 false 来禁用此行为。

如果无法确定协议，它将默认为“http”。

示例：

export default defineEventHandler((event) => {
  const protocol = getRequestProtocol(event) // "https"
})

`getRequestURL(event, opts: { xForwardedHost?, xForwardedProto? })`

使用 getRequestProtocol、getRequestHost 和 event.path 生成完整的传入请求 URL。

如果 xForwardedHost 为 true，它将使用 x-forwarded-host 标头（如果存在）。

如果 xForwardedProto 为 false，它将不使用 x-forwarded-proto 标头。

示例：

export default defineEventHandler((event) => {
  const url = getRequestURL(event) // "https://example.com/path"
})

`getRouterParam(event, name, opts: { decode? })`

根据名称获取匹配的路由参数。

如果 decode 选项为 true，它将使用 decodeURI 解码匹配的路由参数。

示例：

export default defineEventHandler((event) => {
  const param = getRouterParam(event, 'key')
})

`getRouterParams(event, opts: { decode? })`

获取匹配的路由参数。

如果 decode 选项为 true，它将使用 decodeURI 解码匹配的路由参数。

示例：

export default defineEventHandler((event) => {
  const params = getRouterParams(event) // { key: "value" }
})

`getValidatedQuery(event, validate)`

从使用 unjs/ufo 解析并使用验证函数验证的请求 URL 中获取查询参数。

您可以使用简单函数来验证查询对象，也可以使用“zod”之类的库来定义架构。

示例：

export default defineEventHandler((event) => {
  const query = getValidatedQuery(event, (data) => {
    return 'key' in data && typeof data.key === 'string'
  })
})

示例：

import { z } from 'zod'
export default defineEventHandler((event) => {
  const query = getValidatedQuery(
    event,
    z.object({
      key: z.string(),
    }),
  )
})

`getValidatedRouterParams(event, validate, opts: { decode? })`

获取匹配的路由参数并使用验证函数进行验证。

如果 decode 选项为 true，它将使用 decodeURI 解码匹配的路由参数。

您可以使用简单函数来验证参数对象或使用 zod 之类的库来定义架构。

示例：

export default defineEventHandler((event) => {
  const params = getValidatedRouterParams(event, (data) => {
    return 'key' in data && typeof data.key === 'string'
  })
})

示例：

import { z } from 'zod'
export default defineEventHandler((event) => {
  const params = getValidatedRouterParams(
    event,
    z.object({
      key: z.string(),
    }),
  )
})

`isMethod(event, expected, allowHead?)`

检查传入的请求方法是否为预期类型。

如果 allowHead 为 true，则如果预期方法是 GET，它将允许 HEAD 请求通过。

示例：

export default defineEventHandler((event) => {
  if (isMethod(event, 'GET')) {
    // Handle GET request
  }
  else if (isMethod(event, ['POST', 'PUT'])) {
    // Handle POST or PUT request
  }
})

`getRequestFingerprint(event, opts)`

获取传入请求的唯一指纹。

Body utils

`getBodyStream(event)`

从请求中捕获流。

`readFormDataBody(event)`

将事件转换为 Web 请求后，从事件构造 FormData 对象。

示例：

export default defineEventHandler(async (event) => {
  const formData = await readFormDataBody(event)
  const email = formData.get('email')
  const password = formData.get('password')
})

`readJSONBody(event)`

读取请求正文并尝试使用 JSON.parse 或 URLSearchParams 进行解析。

示例：

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

`readRawBody(event)`

读取请求正文并返回原始正文的 Uint8Array。

示例：

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

`readTextBody(event)`

读取请求正文并返回原始正文的字符串 (utf-8)。

示例：

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

`readValidatedJSONBody(event, validate)`

尝试通过“readJSONBody”读取请求主体，然后使用提供的验证函数并抛出验证错误或返回结果。

您可以使用简单函数来验证主体，或使用“zod”之类的库来定义架构。

示例：

export default defineEventHandler(async (event) => {
  const body = await readValidatedJSONBody(event, (body) => {
    return typeof body === 'object' && body !== null
  })
})

示例：

import { z } from 'zod'
export default defineEventHandler(async (event) => {
  const objectSchema = z.object()
  const body = await readValidatedJSONBody(event, objectSchema.safeParse)
})