会话

¥Sessions

使用会话记住你的用户。

¥Remember your users using a session.

会话是一种使用 Cookie 记住用户的方式。这是一种非常常用的方法，用于验证用户身份或保存用户数据，例如用户的语言或 Web 偏好设置。

¥A session is a way to remember users using cookies. It is a very common method for authenticating users or saving data about them, such as their language or preferences on the web.

H3 提供了许多实用程序来处理会话：

¥H3 provides many utilities to handle sessions:

• useSession 初始化会话并返回一个封装器来控制它。
• getSession 初始化或检索当前用户会话。
• updateSession 更新当前会话的数据。
• clearSession 会清除当前会话。

大多数情况下，你将使用 useSession 来操作会话。

¥Most of the time, you will use useSession to manipulate the session.

初始化会话

¥Initialize a Session

要初始化会话，你需要在 事件处理程序 中使用 useSession：

¥To initialize a session, you need to use useSession in an event handler:

import { useSession } from "h3";

app.use(async (event) => {
  const session = await useSession(event, {
    password: "80d42cfb-1cd2-462c-8f17-e3237d9027e9",
  });

  // do something...
});

这将初始化会话并返回一个包含名为 h3 的 Cookie 和加密内容的标头 Set-Cookie。

¥This will initialize a session and return an header Set-Cookie with a cookie named h3 and an encrypted content.

如果请求包含名为 h3 的 Cookie 或名为 x-h3-session 的标头，则会话将使用 Cookie 或标头的内容进行初始化。

¥If the request contains a cookie named h3 or a header named x-h3-session, the session will be initialized with the content of the cookie or the header.

从会话中获取数据

¥Get Data from a Session

要从会话中获取数据，我们仍然会使用 useSession。在底层，它将使用 getSession 获取会话。

¥To get data from a session, we will still use useSession. Under the hood, it will use getSession to get the session.

import { useSession } from "h3";

app.use(async (event) => {
  const session = await useSession(event, {
    password: "80d42cfb-1cd2-462c-8f17-e3237d9027e9",
  });

  return session.data;
});

数据存储在会话的 data 属性中。如果没有数据，它将是一个空对象。

¥Data are stored in the data property of the session. If there is no data, it will be an empty object.

向会话添加数据

¥Add Data to a Session

要向会话添加数据，我们仍然会使用 useSession。在底层，它将使用 updateSession 更新会话。

¥To add data to a session, we will still use useSession. Under the hood, it will use updateSession to update the session.

import { useSession } from "h3";

app.use(async (event) => {
  const session = await useSession(event, {
    password: "80d42cfb-1cd2-462c-8f17-e3237d9027e9",
  });

  const count = (session.data.count || 0) + 1;
  await session.update({
    count: count,
  });

  return count === 0
    ? "Hello world!"
    : `Hello world! You have visited this page ${count} times.`;
});

这里发生了什么？

¥What is happening here?

我们尝试从请求中获取会话。如果没有会话，则会创建一个新的会话。然后，我们增加会话的 count 属性，并使用新值更新会话。最后，我们返回一条消息，其中包含用户访问页面的次数。

¥We try to get a session from the request. If there is no session, a new one will be created. Then, we increment the count property of the session and we update the session with the new value. Finally, we return a message with the number of times the user visited the page.

尝试多次访问该页面，你将看到访问次数。

¥Try to visit the page multiple times and you will see the number of times you visited the page.

清除会话

¥Clear a Session

要清除会话，我们仍然会使用 useSession。在底层，它将使用 clearSession 清除会话。

¥To clear a session, we will still use useSession. Under the hood, it will use clearSession to clear the session.

import { useSession } from "h3";

app.use("/clear", async (event) => {
  const session = await useSession(event, {
    password: "80d42cfb-1cd2-462c-8f17-e3237d9027e9",
  });

  await session.clear();

  return "Session cleared";
});

H3 将发送一个带有名为 h3 的空 Cookie 的标头 Set-Cookie 来清除会话。

¥H3 will send a header Set-Cookie with an empty cookie named h3 to clear the session.

选项

¥Options

当使用 useSession 时，你可以传递一个带有选项的对象作为第二个参数来配置会话：

¥When to use useSession, you can pass an object with options as the second argument to configure the session:

import { useSession } from "h3";

app.use(async (event) => {
  const session = await useSession(event, {
    name: "my-session",
    password: "80d42cfb-1cd2-462c-8f17-e3237d9027e9",
    cookie: {
      httpOnly: true,
      secure: true,
      sameSite: "strict",
    },
    maxAge: 60 * 60 * 24 * 7, // 7 days
  });

  return session.data;
});