ElysiaJS 中文文档

Appearance

我们的赞助商

类型 ​

以下是使用 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
saltyaom@elysiajs.com
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 中的字段为 undefined 或可选。

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 ​

UnionEnum 允许值是指定值之一。

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

文件 ​

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

typescript
t.File()

文件扩展了基础模式的属性，附加属性如下：

type ​

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

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

typescript
type?: MaybeArray<string>

minSize ​

文件的最小大小。

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

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

maxSize ​

文件的最大大小。

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

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

文件单位后缀： ​

以下是文件单位的规范： m: 兆字节 (1048576 字节) k: 千字节 (1024 字节)

文件集 ​

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

typescript
t.Files()

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

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

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

Cookie 扩展了 Object 和 Cookie 的属性，附加属性如下：

secrets ​

用于签名 cookie 的密钥。

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

typescript
secrets?: string | string[]

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

Nullable ​

允许值为 null 但不能是 undefined。

typescript
t.Nullable(t.String())

可能为空 ​

允许值为 null 和 undefined。

typescript
t.MaybeEmpty(t.String())

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

表单 ​

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

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

UInt8Array ​

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

typescript
t.UInt8Array()

当您想要接受可以解析为 Uint8Array 的缓冲区时，这非常有用，例如在二进制文件上传中。它设计用于通过 arrayBuffer 解析器验证正文以强制执行正文类型。

ArrayBuffer ​

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

typescript
t.ArrayBuffer()

当您想要接受可以解析为 Uint8Array 的缓冲区时，这非常有用，例如在二进制文件上传中。它设计用于通过 arrayBuffer 解析器验证正文以强制执行正文类型。

对象字符串 ​

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

typescript
t.ObjectString()

当您想要接受可以解析为对象的字符串但环境不允许显式这样做时，这非常有用，例如在查询字符串、标头或 FormData 正文中。

布尔字符串 ​

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

与 对象字符串 类似，当您想要接受可以解析为布尔值的字符串但环境不允许显式这样做时，这非常有用。

typescript
t.BooleanString()

数值 ​

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

typescript
t.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
()
			})
		)
	})

数字到数值 ​

默认情况下，当作为路由模式提供时，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()

布尔到布尔字符串 ​

类似于 数字到数值

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

ts
import { Elysia, t } from 'elysia'

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

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