高级的 Advanced

本页介绍更多的实用工具

Session utils

clearSession(event, config)

清除当前请求的会话数据。

getSession(event, config)

获取当前请求的会话。

sealSession(event, config)

加密并签名当前请求的会话数据。

unsealSession(_event, config, sealed)

解密并验证当前请求的会话数据。

updateSession(event, config, update?)

更新当前请求的会话数据。

useSession(event, config)

为当前请求创建会话管理器。

deleteCookie(event, name, serializeOptions?)

按名称删除 cookie。

getCookie(event, name)

按名称获取 cookie 值。

parseCookies(event)

解析请求以获取 HTTP Cookie 标头字符串并返回所有 cookie 名称-值对的对象。

setCookie(event, name, value, options?)

按名称设置 cookie 值。

指纹实用程序

getRequestFingerprint(event, opts)

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

WebSocket 实用程序

defineWebSocket(hooks)

定义 WebSocket 钩子。

defineWebSocketHandler(hooks)

定义 WebSocket 事件处理程序。

Sanitize

sanitizeStatusCode(statusCode?, defaultStatusCode)

确保状态代码是有效的 HTTP 状态代码。

sanitizeStatusMessage(statusMessage)

确保状态消息在响应中可以安全使用。

允许的字符：水平制表符、空格或可见的 ASCII 字符：https://www.rfc-editor.org/rfc/rfc7230#section-3.1.2

Base

useBase(base, handler)

使用基本路径添加前缀并执行处理程序。

示例：

ts
const app = createApp()
const router = createRouter()
const apiRouter = createRouter().get(
  '/hello',
  defineEventHandler((event) => {
    return 'Hello API!'
  }),
)
router.use('/api/**', useBase('/api', apiRouter.handler))
app.use(router.handler)

Cache

handleCacheHeaders(event, opts)

检查请求缓存标头（If-Modified-Since）并添加缓存标头（Last-Modified、Cache-Control）注意：默认情况下将添加public缓存控制

代理

fetchWithEvent(event, req, init?, options?: { fetch: F })

使用事件的上下文和标头发出获取请求。

getProxyRequestHeaders(event)

获取请求标头对象，不包括已知在代理时会导致问题的标头。

proxy(event, target, opts)

向目标 URL 发出代理请求并将响应发送回客户端。

proxyRequest(event, target, opts)

将传入请求代理到目标 URL。

CORS

appendCorsHeaders(event, options)

将 CORS 标头附加到响应。

appendCorsPreflightHeaders(event, options)

将 CORS 预检标头附加到响应。

handleCors(event, options)

处理传入请求的 CORS。

如果传入请求是 CORS 预检请求，它将附加 CORS 预检标头并发送 204 响应。

如果返回值为true，则表示请求已处理，无需采取进一步措施。

示例：

ts
const app = createApp()
const router = createRouter()
router.use('/', defineEventHandler(async (event) => {
  const corsRes = handleCors(event, {
    origin: '*',
    preflight: {
      statusCode: 204,
    },
    methods: '*',
  })
  if (corsRes) {
    return corsRes
  }
  // Your code here
}))

isCorsOriginAllowed(origin, options)

检查传入请求是否为 CORS 请求。

isPreflightRequest(event)

检查传入请求是否为 CORS 预检请求。

服务器发送事件 (SSE)

createEventStream(event, opts?)

初始化 EventStream 实例以创建 服务器发送事件

示例：

ts
import { createEventStream, sendEventStream } from 'h3'

defineEventHandler((event) => {
  const eventStream = createEventStream(event)

  // 每秒发送一条消息
  const interval = setInterval(async () => {
    await eventStream.push('Hello world')
  }, 1000)

  // 清理间隔并在连接终止时关闭流
  eventStream.onClosed(async () => {
    console.log('closing SSE...')
    clearInterval(interval)
    await eventStream.close()
  })

  return eventStream.send()
})