# H3Event

> H3Event，承载传入的请求、已准备的响应和上下文。

每个 HTTP 请求，H3 会在内部创建一个 `H3Event` 对象，并将其传递给事件处理程序，直到发送响应。

<read-more title="请求生命周期" to="/guide/basics/lifecycle">



</read-more>

事件会经过所有的生命周期钩子和可组合工具，用作上下文。

**示例：**

```js
app.get("/", async (event) => {
  // 记录 HTTP 请求
  console.log(`[${event.req.method}] ${event.req.url}`);

  // 解析的 URL 和查询参数
  const searchParams = event.url.searchParams;

  // 尝试读取请求的 JSON body
  const jsonBody = await event.req.json().catch(() => {});

  return "OK";
});
```

## `H3Event` 方法

### `H3Event.waitUntil`

告知运行时有一个未完成的操作，在对应的 Promise 解析前不应该关闭。

<CodeGroup>

```js [app.mjs]
import { logRequest } from "./tracing.mjs";

app.get("/", (event) => {
  request.waitUntil(logRequest(request));
  return "OK";
});
```

```js [tracing.mjs]
export async function logRequest(request) {
  await fetch("https://telemetry.example.com", {
    method: "POST",
    body: JSON.stringify({
      method: request.method,
      url: request.url,
      ip: request.ip,
    }),
  });
}
```

</CodeGroup>

## `H3Event` 属性

### `H3Event.app?`

Access to the H3 [application instance](/guide/api/h3).

### `H3Event.context`

上下文是一个包含关于请求的任意信息的对象。

你可以将自定义属性存储在 `event.context` 中，以便在各种工具间共享。

**已知上下文键:**

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

### `H3Event.req`

基于原生的 [Web Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) 的传入 HTTP 请求信息，并包含额外的运行时扩展（参见 [srvx 文档](https://srvx.h3.dev/guide/handler#extended-request-context)）。

```ts
app.get("/", async (event) => {
  const url = event.req.url;
  const method = event.req.method;
  const headers = event.req.headers;

  // （注意：请求体只能使用一次，可以用以下任一方法）
  const bodyStream = await event.req.body;
  const textBody = await event.req.text();
  const jsonBody = await event.req.json();
  const formDataBody = await event.req.formData();

  return "OK";
});
```

### `H3Event.url`

访问完整解析后的请求 [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL)。

### `H3Event.res`

已准备的 HTTP 响应状态和头信息。

```ts
app.get("/", (event) => {
  event.res.status = 200;
  event.res.statusText = "OK";
  event.res.headers.set("x-test", "works");

  return "OK";
});
```

<read-more title="准备响应" to="/guide/basics/response#preparing-response">



</read-more>