Elysia 中文文档

Appearance

在 AI 工具中打开 Anthropic

TypeBox (Elysia.t) ​

以下是使用 Elysia.t 编写验证类型的常见模式。

基本类型 ​

TypeBox API 是围绕 TypeScript 类型设计的，并与之类似。

有许多熟悉的名称和行为与 TypeScript 对应项交叉，例如 String、Number、Boolean 和 Object，以及更高级的功能，如 Intersect、KeyOf 和 Tuple，以增强灵活性。

如果你熟悉 TypeScript，创建 TypeBox 模式的行为就像编写 TypeScript 类型一样，只是它在运行时提供实际的类型验证。

要创建第一个模式，从 Elysia 导入 Elysia.t，并从最基本的类型开始：

typescript
import { Elysia, t } from 'elysia'

new Elysia()
	.post('/', ({ body }) => `Hello ${body}`, {
		body: t.String()
	})
	.listen(3000)

这段代码告诉 Elysia 验证传入的 HTTP 主体，确保主体是一个字符串。如果它是字符串，则可以在请求管道和处理程序中流动。

如果形状不匹配，将抛出错误到 错误生命周期。

Elysia 生命周期

基本类型 ​

TypeBox 提供具有与 TypeScript 类型相同行为的基本原始类型。

以下表格列出了最常见的基本类型：

TypeBoxTypeScript
typescript
t.String()
typescript
string
typescript
t.Number()
typescript
number
typescript
t.Boolean()
typescript
boolean
typescript
t.Array(
    t.Number()
)
typescript
number[]
typescript
t.Object({
    x: t.Number()
})
typescript
{
    x: number
}
typescript
t.Null()
typescript
null
typescript
t.Literal(42)
typescript
42

Elysia 扩展了来自 TypeBox 的所有类型，允许你引用 TypeBox 中的大多数 API 以供在 Elysia 中使用。

有关 TypeBox 支持的其他类型，请参见 TypeBox 的类型。

属性 ​

TypeBox 可以接受基于 JSON Schema 7 规范的参数，以实现更全面的行为。

TypeBoxTypeScript
typescript
t.String({
    format: 'email'
})
typescript
[email protected]
typescript
t.Number({
    minimum: 10,
    maximum: 100
})
typescript
10
typescript
t.Array(
    t.Number(),
    {
        /**
         * 最小项数量
         */
        minItems: 1,
        /**
         * 最大项数量
         */
        maxItems: 5
    }
)
typescript
[1, 2, 3, 4, 5]
typescript
t.Object(
    {
        x: t.Number()
    },
    {
        /**
         * @default false
         * 接受未在模式中指定的其他属性
         * 但仍然匹配类型
         */
        additionalProperties: true
    }
)
typescript
x: 100
y: 200

有关每个属性的更多解释，请参见 JSON Schema 7 规范。

荣誉提及 ​

以下是创建模式时常见的有用模式。

联合类型 ​

允许 t.Object 中的字段具有多种类型。

TypeBoxTypeScript值
typescript
t.Union([
    t.String(),
    t.Number()
])
typescript
string | number
Hello
123

可选类型 ​

允许 t.Object 中的字段为未定义或可选。

TypeBoxTypeScript值
typescript
t.Object({
    x: t.Number(),
    y: t.Optional(t.Number())
})
typescript
{
    x: number,
    y?: number
}
typescript
{
    x: 123
}

部分类型 ​

允许 t.Object 中的所有字段为可选。

TypeBoxTypeScript值
typescript
t.Partial(
    t.Object({
        x: t.Number(),
        y: t.Number()
    })
)
typescript
{
    x?: number,
    y?: number
}
typescript
{
    y: 123
}

Elysia 类型 ​

Elysia.t 建立在 TypeBox 之上，进行了预配置以便于服务器使用，提供了在服务器端验证中常见的额外类型。

你可以在 elysia/type-system 中找到 Elysia 类型的所有源代码。

以下是 Elysia 提供的类型：

联合枚举 ​

UnionEnum 允许值是指定的值之一。

typescript
t.UnionEnum(['rapi', 'anis', 1, true, false])

文件 ​

单个文件，通常用于 文件上传 验证。

typescript
t.File()

文件扩展了基本模式的属性，并具有如下附加属性：

类型 ​

指定文件的格式，如图像、视频或音频。

如果提供了一个数组，它将尝试验证任何格式是否有效。

typescript
type?: MaybeArray<string>

最小大小 ​

文件的最小大小。

接受以字节为单位的数字或文件单位的后缀：

typescript
minSize?: number | `${number}${'k' | 'm'}`

最大大小 ​

文件的最大大小。

接受以字节为单位的数字或文件单位的后缀：

typescript
maxSize?: number | `${number}${'k' | 'm'}`

文件单位后缀： ​

以下是文件单位的规格： m: 兆字节（1048576 字节） k: 千字节（1024 字节）

文件数组 ​

从 文件 扩展，但增加了对单个字段中的文件数组的支持。

typescript
t.Files()

文件数组扩展了基本模式、数组和文件的属性。

从对象类型扩展的 Cookie Jar 的类对象表示。

typescript
t.Cookie({
    name: t.String()
})

Cookie 扩展 Object 和 Cookie 的属性，并具有如下附加属性：

secrets ​

用于签名 Cookie 的秘密密钥。

接受字符串或字符串数组。

typescript
secrets?: string | string[]

如果提供了一个数组，将使用 密钥轮换。新签名的值将使用第一个秘密作为密钥。

可为空 ​

允许值为 null 但不为 undefined。

typescript
t.Nullable(t.String())

允许空值 ​

允许值为 null 和 undefined。

typescript
t.MaybeEmpty(t.String())

有关其他信息，你可以在 elysia/type-system 中找到完整的类型系统源代码。

表单 ​

我们的 t.Object 的语法糖，支持验证 form (FormData) 的返回值。

typescript
t.Form({
	someValue: t.File()
})

UInt8Array ​

接受可以被解析为 Uint8Array 的缓冲区。

typescript
t.UInt8Array()

当你想接受可以被解析为 Uint8Array 的缓冲区时非常有用，例如二进制文件上传。它设计用于配合 arrayBuffer 解析器验证请求体，以强制请求体类型。

ArrayBuffer ​

接受可以被解析为 ArrayBuffer 的缓冲区。

typescript
t.ArrayBuffer()

当你想接受可以被解析为 Uint8Array 的缓冲区时非常有用，例如二进制文件上传。它设计用于配合 arrayBuffer 解析器验证请求体，以强制请求体类型。

ObjectString ​

接受可以被解析为对象的字符串。

typescript
t.ObjectString()

当你想接受可以被解析为对象的字符串但环境不支持显式传递时非常有用，比如查询字符串、请求头或 FormData 请求体。

BooleanString ​

接受可以被解析为布尔值的字符串。

类似于 ObjectString，当你想接受可以被解析为布尔值的字符串但环境不支持显式传递时非常有用。

typescript
t.BooleanString()

Numeric ​

Numeric 接受数字字符串或数字，然后将值转换为数字。

typescript
t.Numeric()

当传入值是数字字符串时非常有用，例如路径参数或查询字符串。

Numeric 支持与 Numeric 实例 相同的属性。

Elysia 行为 ​

Elysia 默认使用 TypeBox。

然而，为了帮助简化 HTTP 处理。Elysia 有一些专用类型，并且行为上与 TypeBox 有一些不同。

可选类型 ​

要使字段可选，请使用 t.Optional。

这将允许客户端可选地提供查询参数。此行为也适用于 body、headers。

这与 TypeBox 中的行为不同，TypeBox 中可选是用来标记对象字段为可选。

typescript
import { Elysia, t } from 'elysia'

new Elysia()
	.get('/optional', ({ query }) => query, {
		query: t.Optional(
			t.Object({
				name: t.String()
			})
		)
	})

数字到 Numeric ​

默认情况下，当作为路由模式提供时，Elysia 会将 t.Number 转换为 t.Numeric。

因为解析过的 HTTP 头、查询和 URL 参数总是字符串。这意味着即使值是数字，也会被当作字符串处理。

Elysia 通过检查字符串值是否看起来像数字，然后适当地转换来覆盖此行为。

这只在作为路由模式使用时应用，而不会作用于嵌套的 t.Object 中。

ts
import { Elysia, t } from 'elysia'

new Elysia()
	.get('/:id', ({ id }) => id, {
		params: t.Object({
			// 转换为 t.Numeric()
			id: t.Number()
		}),
		body: t.Object({
			// 不转换为 t.Numeric()
			id: t.Number()
		})
	})

// 不转换为 t.Numeric()
t.Number()

布尔值到布尔字符串 ​

类似于 数字到 Numeric

任何 t.Boolean 都将被转换为 t.BooleanString。

ts
import { Elysia, t } from 'elysia'

new Elysia()
	.get('/:id', ({ id }) => id, {
		params: t.Object({
			// 转换为 t.BooleanString()
			id: t.Boolean()
		}),
		body: t.Object({
			// 不转换为 t.BooleanString()
			id: t.Boolean()
		})
	})

// 不转换为 t.BooleanString()
t.Boolean()