一览

Elysia 是一个用于使用 Bun 构建后端服务器的人体工学 Web 框架。

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

这是一个简单的 Elysia Hello World 示例。

import { Elysia } from 'elysia'

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

导航到 localhost:3000，您应该会看到 'Hello Elysia' 作为结果。

localhost//user/1/form

GET

TIP

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

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

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

性能

基于 Bun 和广泛的优化（如静态代码分析），Elysia 能够在运行时生成优化的代码。

Elysia 可以超越当今大多数可用的 Web 框架^[1]，甚至匹配 Golang 和 Rust 框架的性能^[2]。

Framework	Runtime	Average	Plain Text	Dynamic Parameters	JSON Body
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 的类型系统经过仔细调整，能够从您的代码中自动推断类型，而无需编写显式的 TypeScript，从而在运行时和编译时提供类型安全，实现最出色的人体工学开发体验。

看看这个示例：

import { Elysia } from 'elysia'

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

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

localhost/user/123/user/abc

GET

123

Elysia 的目标是帮助您编写更少的 TypeScript 代码，并更多地关注业务逻辑。让框架处理复杂的类型。

使用 Elysia 不需要 TypeScript，但推荐使用。

类型完整性

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

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

import { Elysia, t } from 'elysia'

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

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

TIP

将鼠标悬停在上述代码片段中的 "id" 上以查看类型定义。

使用 Elysia 的模式构建器，我们可以像强类型语言一样确保类型安全，并拥有单一真相来源。

标准模式

Elysia 支持 Standard Schema，允许您使用您喜欢的验证库：

• Zod
• Valibot
• ArkType
• Effect Schema
• Yup
• Joi
• 以及更多

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 将自动从模式中推断类型，允许您使用您喜欢的验证库，同时保持类型安全。

OpenAPI

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

例如，因为 Elysia 默认采用 OpenAPI，生成 API 文档就像添加一行代码一样简单：

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 文档页面，而无需额外代码或特定配置，并轻松与您的团队分享。

从类型生成 OpenAPI

Elysia 对 OpenAPI 的支持出色，使用模式进行数据验证、类型推断和从单一真相来源的 OpenAPI 注解。

Elysia 还支持直接从类型生成 OpenAPI 模式，仅需 1 行代码，允许您拥有完整且准确的 API 文档，而无需任何手动注解。

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

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

端到端类型安全

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

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

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

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

export type App = typeof app

而在客户端：

// 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 服务器无需代码生成，并自动同步前端和后端的类型。

Elysia 不仅仅是帮助您创建自信的后端，而是为了这个世界上所有美好的事物。

平台无关

Elysia 是为 Bun 设计的，但不限于 Bun。由于 WinterTC 合规，您可以将 Elysia 服务器部署到 Cloudflare Workers、Vercel Edge Functions 和大多数支持 Web 标准请求的其他运行时。

我们的社区

如果您有问题或在使用 Elysia 时遇到困难，请随时在 GitHub Discussions、Discord 或 Twitter 上向我们的社区提问。

Discord

官方 ElysiaJS Discord 社区服务器

Twitter

跟踪 Elysia 的更新和状态

GitHub

源代码和开发

---

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

2. 基于 TechEmpower Benchmark round 22。