深入理解unjs/h3中的H3Event对象

最新推荐文章于 2025-06-10 09:01:52 发布

原创最新推荐文章于 2025-06-10 09:01:52 发布

· 389 阅读

5 ·

版权

深入理解unjs/h3中的H3Event对象

h3 ⚡️ Minimal H(TTP) framework built for high performance and portability 项目地址: https://gitcode.com/gh_mirrors/h31/h3

什么是H3Event

在unjs/h3框架中，H3Event是一个核心概念，它代表了HTTP请求的生命周期。每当服务器接收到一个HTTP请求时，h3框架内部会自动创建一个H3Event对象，这个对象会贯穿整个请求处理流程，直到最终响应被发送。

H3Event对象包含了请求的所有相关信息，以及响应准备阶段的各种方法和属性。理解H3Event的工作原理对于高效使用h3框架至关重要。

H3Event的核心作用

H3Event主要有三个核心作用：

承载请求信息：包含原始请求对象(req)、解析后的URL等信息
准备响应：提供响应对象(res)用于设置状态码、响应头等
上下文共享：通过context属性在不同处理函数间共享数据

H3Event的主要属性和方法

1. 请求相关属性

`event.req`

这是原始的HTTP请求对象，基于Web标准的Request接口，并添加了一些运行时扩展：

app.get("/", async (event) => {
  // 获取请求URL和方法
  const url = event.req.url;
  const method = event.req.method;
  
  // 获取请求头
  const headers = event.req.headers;
  
  // 获取请求体(注意：请求体只能被消费一次)
  const textBody = await event.req.text();  // 文本格式
  const jsonBody = await event.req.json();  // JSON格式
  const formData = await event.req.formData(); // FormData格式
  
  return "处理完成";
});

`event.url`

这是解析后的URL对象，提供了方便的访问方式：

app.get("/search", (event) => {
  // 获取查询参数
  const searchTerm = event.url.searchParams.get("q");
  
  return `搜索关键词: ${searchTerm}`;
});

2. 响应相关属性

`event.res`

用于准备HTTP响应，可以设置状态码、状态文本和响应头：

app.get("/custom", (event) => {
  event.res.status = 201;  // 设置状态码
  event.res.statusText = "Created";  // 设置状态文本
  event.res.headers.set("X-Custom-Header", "value");  // 设置响应头
  
  return { message: "资源已创建" };
});

3. 上下文共享

`event.context`

这是一个对象，用于在不同处理函数间共享数据：

// 中间件中设置上下文
app.use((event) => {
  event.context.user = { id: 1, name: "张三" };
});

// 路由处理函数中使用上下文
app.get("/profile", (event) => {
  const user = event.context.user;
  return `欢迎, ${user.name}`;
});

框架预定义了一些上下文键名：

context.params: 路由匹配参数
middlewareParams: 中间件匹配参数
matchedRoute: 匹配的路由对象
sessions: 缓存的会话数据
basicAuth: 基本认证数据

4. 实用方法

`event.waitUntil()`

这个方法告诉运行时环境，有一个后台操作需要完成，即使主响应已经发送：

// 主应用文件
app.get("/", (event) => {
  event.waitUntil(logAnalytics(event));
  return "请求已处理";
});

// 日志记录模块
async function logAnalytics(event) {
  await someAsyncOperation({
    method: event.req.method,
    url: event.req.url,
    ip: event.ip
  });
}

这个方法非常适合用于不需要阻塞主响应但需要确保完成的操作，如日志记录、数据分析等。

实际应用示例

让我们看一个综合使用H3Event的完整示例：

app.post("/api/users", async (event) => {
  // 1. 记录请求信息
  console.log(`[${event.req.method}] ${event.req.url}`);
  
  // 2. 解析JSON请求体
  const userData = await event.req.json().catch(() => null);
  if (!userData) {
    event.res.status = 400;
    return { error: "无效的JSON数据" };
  }
  
  // 3. 验证数据
  if (!userData.name || !userData.email) {
    event.res.status = 422;
    return { error: "缺少必要字段" };
  }
  
  // 4. 创建用户(模拟)
  const newUser = {
    id: Date.now(),
    ...userData,
    createdAt: new Date()
  };
  
  // 5. 异步记录操作(不阻塞响应)
  event.waitUntil(logUserCreation(event, newUser));
  
  // 6. 返回响应
  event.res.status = 201;
  return newUser;
});

async function logUserCreation(event, user) {
  // 这里可以执行数据库操作或发送通知等
  await someAsyncLoggingOperation({
    userId: user.id,
    ip: event.ip,
    timestamp: new Date()
  });
}