处理会话 Handle Session

使用会话记住您的用户。

会话是一种使用 cookie 记住用户的方式。这是一种非常常见的方式，用于验证用户身份或保存有关他们的数据，例如他们的语言或他们在网络上的偏好。

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

useSession 用于初始化会话并返回包装器来控制它。
getSession 用于初始化或获取当前用户会话。
updateSession 用于更新当前会话的数据。
clearSession 用于清除当前会话。

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

初始化会话

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

import { defineEventHandler, useSession } from 'h3'

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

    // do something...
  }),
)

您必须提供密码才能加密会话。

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

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

标头优先于 cookie。

从会话中获取数据

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

import { defineEventHandler, useSession } from 'h3'

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

    return session.data
  }),
)

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

将数据添加到会话

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

import { defineEventHandler, useSession } from 'h3'

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

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

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

这里发生了什么？

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

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

如果您使用 CLI 工具（如 curl）来测试此示例，您将看不到访问该页面的次数，因为 CLI 工具不保存 cookie。您必须从响应中获取 cookie 并将其发送回服务器。

清除会话

要清除会话，我们仍将使用 useSession。在后台，它将使用 clearSession 来清除会话。

import { defineEventHandler, useSession } from 'h3'

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

    await session.clear()

    return 'Session cleared'
  }),
)

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

选项

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

import { defineEventHandler, useSession } from 'h3'

app.use(
  defineEventHandler(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
  }),
)