ElysiaJS 中文文档

Appearance

Our Sponsors
Open in Anthropic

title: TypeBox (Elysia.t) - ElysiaJS head: - - meta - property: 'og:title' content: TypeBox (Elysia.t) - ElysiaJS

- - meta
  - name: 'description'
    content: 模式是严格类型化的定义，用于推断传入请求和传出响应的 TypeScript 类型和数据验证。Elysia 的模式验证基于 Sinclair 的 TypeBox，这是一个用于数据验证的 TypeScript 库。

- - meta
  - property: 'og:description'
    content: 模式是严格类型化的定义，用于推断传入请求和传出响应的 TypeScript 类型和数据验证。Elysia 的模式验证基于 Sinclair 的 TypeBox，这是一个用于数据验证的 TypeScript 库。

TypeBox (Elysia.t) ​

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

Primitive Type ​

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 Life Cycle

Basic Type ​

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 支持的其他类型。

Attribute ​

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 规范了解每个属性的更多说明。

Honorable Mentions ​

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

Union ​

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

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

Optional ​

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

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

Partial ​

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

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

Elysia Type ​

Elysia.t 基于 TypeBox，为服务器使用进行了预配置，提供了服务器端验证中常见的额外类型。

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

以下是 Elysia 提供的类型：

UnionEnum ​

UnionEnum 允许值是指定值之一。

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

File ​

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

typescript
t.File()

File 扩展了基本模式的属性，具有以下附加属性：

type ​

指定文件的格式，如 image、video 或 audio。

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

typescript
type?: MaybeArray<string>

minSize ​

文件的最小大小。

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

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

maxSize ​

文件的最大大小。

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

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

File Unit Suffix: ​

以下是文件单位的规范： m: MegaByte (1048576 byte) k: KiloByte (1024 byte)

Files ​

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

typescript
t.Files()

Files 扩展了基本模式、数组和 File 的属性。

Cookie Jar 的类似对象表示，扩展自 Object 类型。

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

Cookie 扩展了 Object 和 Cookie 的属性，具有以下附加属性：

secrets ​

用于签名 cookies 的密钥。

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

typescript
secrets?: string | string[]

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

Nullable ​

允许值为 null 但不为 undefined。

typescript
t.Nullable(t.String())

MaybeEmpty ​

允许值为 null 和 undefined。

typescript
t.MaybeEmpty(t.String())

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

Form ​

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()

当您想要接受可以解析为对象的字符串但环境不允许明确执行时，这很有用，例如在查询字符串、header 或 FormData 主体中。

BooleanString ​

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

类似于 ObjectString，当您想要接受可以解析为布尔值的字符串但环境不允许明确执行时，这很有用。

typescript
t.BooleanString()

Numeric ​

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

typescript
t.Numeric()

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

Numeric 接受与 Numeric Instance 相同的属性。

Elysia behavior ​

Elysia 默认使用 TypeBox。

然而，为了帮助更轻松地处理 HTTP。Elysia 有一些专用类型，并且有一些与 TypeBox 不同的行为。

Optional ​

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

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

这与 TypeBox 不同，在 TypeBox 中 optional 是将对象的字段标记为可选。

typescript
import { 
Elysia
, 
t
 } from 'elysia'

new 
Elysia
()
	.
get
('/optional', ({ 
query
 }) => 
query
, {




		
query
: 
t
.
Optional
(
			
t
.
Object
({
				
name
: 
t
.
String
()
			})
		)
	})

Number to Numeric ​

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

因为解析的 HTTP header、查询、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()

Boolean to BooleanString ​

类似于 Number to Numeric

任何 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()