响应式 Cookie - ElysiaJS - Elysia 中文文档

Elysia 提供了一个可变信号，用于与 Cookie 进行交互。

没有 get/set，您可以直接提取 Cookie 名称并检索或更新其值。

import { Elysia } from 'elysia'

new Elysia()
    .get('/', ({ cookie: { name } }) => {
        // 获取
        name.value

        // 设置
        name.value = "新值"
    })

默认情况下，响应式 Cookie 可以自动编码/解码对象类型，使我们能够将 Cookie 视为对象，而无需担心编码/解码。它就是这样工作的。

响应性

Elysia 的 Cookie 是响应式的。这意味着当您更改 Cookie 值时，Cookie 会根据类似信号的方式自动更新。

Elysia Cookies 提供了处理 Cookies 的单一真实来源，能够自动设置头部并同步 Cookie 值。

由于 Cookies 默认是基于 Proxy 的对象，提取的值永远不会是 undefined；相反，它将始终是一个 Cookie<unknown> 的值，可以通过调用 .value 属性获取。

我们可以将 Cookie 罐视为常规对象，对其进行迭代只会迭代已经存在的 Cookie 值。

要使用 Cookie 属性，您可以使用以下任一方法：

直接设置属性
使用 set 或 add 来更新 Cookie 属性。

有关更多信息，请参见 Cookie 属性配置。

分配属性

您可以像对待任何普通对象一样获取/设置 Cookie 的属性，响应性模型会自动同步 Cookie 值。

import { Elysia } from 'elysia'

new Elysia()
    .get('/', ({ cookie: { name } }) => {
        // 获取
        name.domain

        // 设置
        name.domain = 'millennium.sh'
        name.httpOnly = true
    })

set

set 允许一次更新多个 Cookie 属性，通过 重置所有属性 并用新值覆盖该属性。

import { Elysia } from 'elysia'

new Elysia()
    .get('/', ({ cookie: { name } }) => {
        name.set({
            domain: 'millennium.sh',
            httpOnly: true
        })
    })

add

与 set 相似，add 允许我们一次更新多个 Cookie 属性，但只会覆盖已定义的属性，而不是重置。

remove

要移除 Cookie，您可以使用以下任一方法：

name.remove
delete cookie.name

import { Elysia } from 'elysia'

new Elysia()
    .get('/', ({ cookie, cookie: { name } }) => {
        name.remove()

        delete cookie.name
    })

您可以通过使用 t.Cookie 的 Cookie 模式严格验证 Cookie 类型，并提供 Cookie 的类型推断。

import { Elysia
, t
 } from 'elysia'

new Elysia
()
    .get
('/', ({ cookie
: { name
 } }) => {
        // 设置
        name
.value
 = {
            id
: 617,
            name
: '召唤 101'
        }
    }, {
        cookie
: t
.Cookie
({
            name
: t
.Object
({
                id
: t
.Numeric
(),
                name
: t
.String
()
            })
        })
    })

要处理可空 Cookie 值，您可以在您希望可空的 Cookie 名称上使用 t.Optional。

import { Elysia
, t
 } from 'elysia'

new Elysia
()
    .get
('/', ({ cookie
: { name
 } }) => {
        // 设置
        name
.value
 = {
            id
: 617,
            name
: '召唤 101'
        }
    }, {
        cookie
: t
.Cookie
({
            name
: t
.Optional
(
                t
.Object
({
                    id
: t
.Numeric
(),
                    name
: t
.String
()
                })
            )
        })
    })

通过引入 Cookie Schema，和 t.Cookie 类型，我们可以创建一个统一的类型来处理签名/验证 Cookie 签名。

Cookie 签名是附加到 Cookie 值的加密哈希，是使用秘密密钥和 Cookie 的内容生成的，以通过向 Cookie 添加签名来增强安全性。

这确保了 Cookie 值未被恶意行为者修改，有助于验证 Cookie 数据的真实性和完整性。

通过提供 Cookie 密钥，以及 sign 属性来指示哪些 Cookie 应具有签名验证。

import { Elysia
, t
 } from 'elysia'

new Elysia
()
    .get
('/', ({ cookie
: { profile
 } }) => {
        profile
.value
 = {
            id
: 617,
            name
: '召唤 101'
        }
    }, {
        cookie
: t
.Cookie
({
            profile
: t
.Object
({
                id
: t
.Numeric
(),
                name
: t
.String
()
            })
        }, {
            secrets
: 'Fischl von Luftschloss Narfidort',
            sign
: ['profile']
        })
    })

Elysia 然后会自动签名和验证 Cookie 值。

构造函数

您可以使用 Elysia 构造函数设置全局 Cookie secret 和 sign 值，以适用于所有路由，而不是在每个需要的路由中内联。

import { Elysia
, t
 } from 'elysia'

new Elysia
({
    cookie
: {
        secrets
: 'Fischl von Luftschloss Narfidort',
        sign
: ['profile']
    }
})
    .get
('/', ({ cookie
: { profile
 } }) => {
        profile
.value
 = {
            id
: 617,
            name
: '召唤 101'
        }
    }, {
        cookie
: t
.Cookie
({
            profile
: t
.Object
({
                id
: t
.Numeric
(),
                name
: t
.String
()
            })
        })
    })

Elysia 会自动处理 Cookie 的密钥轮换。

Cookie 轮换是一种迁移技术，用于使用较新的密钥对 Cookie 进行签名，同时也能够验证旧的 Cookie 签名。

import { Elysia } from 'elysia'

new Elysia({
    cookie: {
        secrets: ['复仇将属于我', 'Fischl von Luftschloss Narfidort']
    }
})

配置

以下是 Elysia 接受的 Cookie 配置。

secret

用于签名/取消签名 Cookie 的密钥。

如果传递了一个数组，则将使用密钥轮换。

密钥轮换是指将加密密钥退役并通过生成新的加密密钥进行替换。

以下是从 cookie 扩展的配置。

domain

指定 Domain Set-Cookie 属性的值。

默认情况下，没有设置域，大多数客户端将只考虑当前域的 Cookie。

encode

@default encodeURIComponent

指定将用于编码 Cookie 值的函数。

由于 Cookie 的值具有有限的字符集（并且必须是简单字符串），因此可以使用此函数将值编码为适合 Cookie 值的字符串。

默认函数是全局的 encodeURIComponent，它会将 JavaScript 字符串编码为 UTF-8 字节序列，然后对落在 Cookie 范围外的进行 URL 编码。

expires

指定作为 Expires Set-Cookie 属性值的日期对象。

默认情况下，没有设置过期时间，大多数客户端将视其为“非持久性 Cookie”，并将在退出 Web 浏览器应用程序等条件下删除它。

TIP

Cookie 存储模型规范规定，如果同时设置了 expires 和 maxAge，则 maxAge 优先，但并不是所有客户端都可能遵守，因此如果同时设置了它们，则应指向同一日期和时间。

httpOnly

@default false

指定布尔值作为 HttpOnly Set-Cookie 属性的值。

当为真时，会设置 HttpOnly 属性，否则不会设置。

默认情况下，不设置 HttpOnly 属性。

TIP

设置为 true 时要小心，因为符合规范的客户端将不允许客户端 JavaScript 在 document.cookie 中查看该 Cookie。

maxAge

@default undefined

指定作为 Max-Age Set-Cookie 属性的值的数字（以秒为单位）。

给定的数字将通过向下取整进行转换。默认情况下，不设置最大年龄。

TIP

path

指定作为 Path Set-Cookie 属性的值。

默认情况下，路径处理器被视为默认路径。

priority

指定字符串作为 Priority Set-Cookie 属性的值。 low 将把优先级属性设置为低。 medium 将把优先级属性设置为中，未设置时的默认优先级。 high 将把优先级属性设置为高。

有关不同优先级级别的更多信息，请参见规范。

TIP

这是一个尚未完全标准化的属性，未来可能会有所更改。这也意味着许多客户端可能会在理解之前忽略此属性。

sameSite

指定布尔值或字符串作为 SameSite Set-Cookie 属性的值。 true 将 SameSite 属性设置为严格的同站强制。 false 不会设置 SameSite 属性。 'lax' 将 SameSite 属性设置为宽松同站强制。 'none' 将 SameSite 属性设置为无以示明确的跨站 Cookie。 'strict' 将 SameSite 属性设置为严格的同站强制。有关不同强制级别的更多信息，请参见规范。

TIP

这是一个尚未完全标准化的属性，未来可能会有所更改。这也意味着许多客户端可能会在理解之前忽略此属性。

secure

指定布尔值作为 Secure Set-Cookie 属性的值。当为真时，设置 Secure 属性，否则不设置。默认情况下，不设置 Secure 属性。

TIP

设置为 true 时要小心，因为符合规范的客户端将在未来如果浏览器没有 HTTPS 连接时，不会将该 Cookie 发送回服务器。

Cookie Interactive Playground ​

响应性 ​

Cookie 属性 ​

分配属性 ​

set ​

add ​

remove ​

Cookie 模式 ​

可空 Cookie ​

Cookie 签名 ​

使用 Cookie 签名 ​

构造函数 ​

Cookie 轮换 ​

配置 ​

secret ​

domain ​

encode ​

expires ​

httpOnly ​

maxAge ​

path ​

priority ​

sameSite ​

secure ​

Cookie Interactive Playground

响应性

Cookie 属性