概览

¥At a glance

Elysia 是一个符合人机工程学的 Web 框架，用于使用 Bun 构建后端服务器。

¥Elysia is an ergonomic web framework for building backend servers with Bun.

Elysia 的设计秉承简洁性和类型安全理念，提供用户熟悉的 API，广泛支持 TypeScript，并针对 Bun 进行了优化。

¥Designed with simplicity and type-safety in mind, Elysia offers a familiar API with extensive support for TypeScript and is optimized for Bun.

以下是 Elysia 中一个简单的 Hello World 示例。

¥Here's a simple hello world in Elysia.

typescript

import { Elysia
 } from 'elysia'

new Elysia
()
    .get
('/', 'Hello Elysia')
    .get
('/user/:id', ({ params
: { id
 }}) => id
)
    .post
('/form', ({ body
 }) => body
)
    .listen
(3000)

导航到 localhost:3000，你应该会看到结果 '你好，Elysia'。

¥Navigate to localhost:3000 and you should see 'Hello Elysia' as the result.

提示

将鼠标悬停在代码片段上即可查看类型定义。

¥Hover over the code snippet to see the type definition.

在模拟浏览器中，点击蓝色高亮显示的路径即可更改路径并预览响应。

¥In the mock browser, click on the path highlighted in blue to change paths and preview the response.

Elysia 可以在浏览器中运行，你看到的结果实际上是使用 Elysia 执行的。

¥Elysia can run in the browser, and the results you see are actually executed using Elysia.

性能

¥Performance

基于 Bun 构建，并进行静态代码分析等广泛的优化，使 Elysia 能够动态生成优化代码。

¥Building on Bun and extensive optimization like static code analysis allows Elysia to generate optimized code on the fly.

Elysia 的性能优于当今大多数 Web 框架 ^[1]，甚至可以与 Golang 和 Rust 框架 ^[2] 的性能相媲美。

¥Elysia can outperform most web frameworks available today^[1], and even match the performance of Golang and Rust frameworks^[2].

框架	运行时	平均值	纯文本	动态参数	JSON 主体
bun	bun	262,660.433	326,375.76	237,083.18	224,522.36
elysia	bun	255,574.717	313,073.64	241,891.57	211,758.94
hyper-express	node	234,395.837	311,775.43	249,675	141,737.08
hono	bun	203,937.883	239,229.82	201,663.43	170,920.4
h3	node	96,515.027	114,971.87	87,935.94	86,637.27
oak	deno	46,569.853	55,174.24	48,260.36	36,274.96
fastify	bun	65,897.043	92,856.71	81,604.66	23,229.76
fastify	node	60,322.413	71,150.57	62,060.26	47,756.41
koa	node	39,594.14	46,219.64	40,961.72	31,601.06
express	bun	29,715.537	39,455.46	34,700.85	14,990.3
express	node	15,913.153	17,736.92	17,128.7	12,873.84

TypeScript

Elysia 旨在帮助你减少 TypeScript 编写。

¥Elysia is designed to help you write less TypeScript.

Elysia 的类型系统经过微调，可以自动从代码中推断类型，无需编写显式的 TypeScript 代码，同时在运行时和编译时提供类型安全，从而实现最符合人机工程学的开发体验。

¥Elysia's Type System is fine-tuned to infer types from your code automatically, without needing to write explicit TypeScript, while providing type-safety at both runtime and compile time for the most ergonomic developer experience.

请看以下示例：

¥Take a look at this example:

typescript

import { Elysia
 } from 'elysia'

new Elysia
()
    .get
('/user/:id', ({ params
: { id
 } }) => id
)
    .listen
(3000)

上述代码创建了一个路径参数 "id"。替换 :id 的值将在运行时和类型中传递给 params.id，无需手动类型声明。

¥The above code creates a path parameter "id". The value that replaces :id will be passed to params.id both at runtime and in types, without manual type declaration.

123

Elysia 的目标是帮助你减少 TypeScript 代码编写，将更多精力放在业务逻辑上。让框架处理复杂类型。

¥Elysia's goal is to help you write less TypeScript and focus more on business logic. Let the framework handle the complex types.

使用 Elysia 不需要 TypeScript，但建议使用。

¥TypeScript is not required to use Elysia, but it's recommended.

类型完整性

¥Type Integrity

更进一步，Elysia 提供了 Elysia.t，这是一个模式构建器，用于在运行时和编译时验证类型和值，从而为你的数据类型创建单一可信来源。

¥To take it a step further, Elysia provides Elysia.t, a schema builder to validate types and values at both runtime and compile time, creating a single source of truth for your data types.

让我们修改前面的代码，使其只接受数字值而不是字符串。

¥Let's modify the previous code to accept only a number value instead of a string.

typescript

import { Elysia
, t
 } from 'elysia'

new Elysia
()
    .get
('/user/:id', ({ params
: { id
 } }) => id
, {
        params
: t
.Object
({
            id
: t
.Number
()
        })
    })
    .listen
(3000)

此代码确保我们的路径参数 id 在运行时和编译时（类型级别）始终为数字。

¥This code ensures that our path parameter id will always be a number at both runtime and compile time (type-level).

提示

将鼠标悬停在上面代码片段中的 "id" 上，即可查看类型定义。

¥Hover over "id" in the above code snippet to see a type definition.

借助 Elysia 的模式构建器，我们可以像使用单一数据源的强类型语言一样确保类型安全。

¥With Elysia's schema builder, we can ensure type safety like a strongly typed language with a single source of truth.

标准 Schema

¥Standard Schema

Elysia 支持标准 Schema，允许你使用你喜欢的验证库：

¥Elysia supports Standard Schema, allowing you to use your favorite validation library:

Zod
Valibot
ArkType
效果模式
是的
Joi
以及更多

typescript

import { Elysia
 } from 'elysia'
import { z
 } from 'zod'
import * as v
 from 'valibot'

new Elysia
()
	.get
('/id/:id', ({ params
: { id
 }, query
: { name
 } }) => id
, {
		params
: z
.object
({
			id
: z
.coerce
.number
()
		}),
		query
: v
.object
({
			name
: v
.literal
('Lilith')
		})
	})
	.listen
(3000)

Elysia 将自动从模式推断类型，允许你使用你喜欢的验证库，同时仍然保持类型安全。

¥Elysia will infer the types from the schema automatically, allowing you to use your favorite validation library while still maintaining type safety.

OpenAPI

Elysia 默认采用许多标准，例如 OpenAPI、WinterTC 合规性和标准 Schema。允许你与大多数行业标准工具集成，或者至少可以轻松地与你熟悉的工具集成。

¥Elysia adopts many standards by default, like OpenAPI, WinterTC compliance, and Standard Schema. Allowing you to integrate with most of the industry standard tools or at least easily integrate with tools you are familiar with.

例如，由于 Elysia 默认采用 OpenAPI，因此生成 API 文档只需添加一行代码即可：

¥For instance, because Elysia adopts OpenAPI by default, generating API documentation is as easy as adding a one-liner:

typescript

import { Elysia, t } from 'elysia'
import { openapi } from '@elysiajs/openapi'

new Elysia()
    .use(openapi()) 
    .get('/user/:id', ({ params: { id } }) => id, {
        params: t.Object({
            id: t.Number()
        })
    })
    .listen(3000)

使用 OpenAPI 插件，你可以无缝生成 API 文档页面，无需额外代码或特定配置，并轻松地与你的团队共享。

¥With the OpenAPI plugin, you can seamlessly generate an API documentation page without additional code or specific configuration and share it with your team effortlessly.

从类型生成 OpenAPI

¥OpenAPI from types

Elysia 对 OpenAPI 提供了出色的支持，其架构可用于从单一数据源进行数据验证、类型推断和 OpenAPI 注释。

¥Elysia has excellent support for OpenAPI with schemas that can be used for data validation, type inference, and OpenAPI annotation from a single source of truth.

Elysia 还支持直接从类型生成 OpenAPI 模式，只需一行代码即可生成，让你无需任何手动注释即可获得完整准确的 API 文档。

¥Elysia also supports OpenAPI schema generation with 1 line directly from types, allowing you to have complete and accurate API documentation without any manual annotation.

typescript

import { Elysia, t } from 'elysia'
import { openapi } from '@elysiajs/oepnapi'
import { fromTypes } from '@elysiajs/openapi/gen'

export const app = new Elysia()
    .use(openapi({
    	references: fromTypes('src/index.ts') 
    }))
    .get('/user/:id', ({ params: { id } }) => id, {
        params: t.Object({
            id: t.Number()
        })
    })
    .listen(3000)

端到端类型安全

¥End-to-end Type Safety

使用 Elysia，类型安全不仅限于服务器端。

¥With Elysia, type safety is not limited to server-side.

使用 Elysia，你可以使用 Elysia 的客户端库 "Eden" 自动与前端团队同步你的类型，类似于 tRPC。

¥With Elysia, you can synchronize your types with your frontend team automatically, similar to tRPC, using Elysia's client library, "Eden".

typescript

import { Elysia
, t
 } from 'elysia'
import { openapi
 } from '@elysiajs/openapi'
import { fromTypes
 } from '@elysiajs/openapi/gen'

export const app
 = new Elysia
()
    .use
(openapi
({
    	references
: fromTypes
('src/index.ts')
    }))
    .get
('/user/:id', ({ params
: { id
 } }) => id
, {
        params
: t
.Object
({
            id
: t
.Number
()
        })
    })
    .listen
(3000)

export type App
 = typeof app

客户端：

¥And on your client-side:

typescript

// client.ts
import { treaty
 } from '@elysiajs/eden'
import type { App
 } from './server'

const app
 = treaty
<App
>('localhost:3000')

// Get data from /user/617
const { data
 } = await app
.user
({ id
: 617 }).get
()

console
.log
(data
)

借助 Eden，你可以使用现有的 Elysia 类型查询 Elysia 服务器，而无需生成代码，并自动同步前端和后端的类型。

¥With Eden, you can use the existing Elysia types to query an Elysia server without code generation and synchronize types for both frontend and backend automatically.

Elysia 不仅能帮助你创建可靠的后端，更能造福于世间一切美好事物。

¥Elysia is not only about helping you create a confident backend but for all that is beautiful in this world.

平台无关

¥Platform Agnostic

Elysia 是为 Bun 设计的，但并不局限于 Bun。符合 WinterTC 标准允许你在 Cloudflare Workers、Vercel Edge Functions 以及大多数其他支持 Web 标准请求的运行时上部署 Elysia 服务器。

¥Elysia was designed for Bun, but is not limited to Bun. Being WinterTC compliant allows you to deploy Elysia servers on Cloudflare Workers, Vercel Edge Functions, and most other runtimes that support Web Standard Requests.

我们的社区

¥Our Community

如果你在使用 Elysia 时遇到任何问题或遇到困难，欢迎在 GitHub 讨论区、Discord 或 Twitter 上向我们的社区提问。

¥If you have questions or get stuck with Elysia, feel free to ask our community on GitHub Discussions, Discord, or Twitter.

1.以请求/秒为单位。在 Debian 11、Intel i7-13700K 处理器上，于 2023 年 8 月 6 日在 Bun 0.7.2 上测试了解析查询、路径参数和设置响应头的基准测试。请参阅基准测试条件此处。

¥1. Measured in requests/second. The benchmark for parsing query, path parameter and set response header on Debian 11, Intel i7-13700K tested on Bun 0.7.2 on 6 Aug 2023. See the benchmark condition here.

2.基于 TechEmpower 基准测试第 22 轮。

¥2. Based on TechEmpower Benchmark round 22.

概览 ​

性能 ​

TypeScript ​

类型完整性 ​

标准 Schema ​

OpenAPI ​

从类型生成 OpenAPI ​

端到端类型安全 ​

平台无关 ​

我们的社区 ​

概览

性能

TypeScript

类型完整性

标准 Schema

OpenAPI

从类型生成 OpenAPI

端到端类型安全

平台无关

我们的社区