一览

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，同时在运行时和编译时提供类型安全，从而实现最 ergonomics 的开发者体验。

看看这个示例：

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，这是一个 schema 构建器，用于在运行时和编译时验证类型和值，从而为您的數據类型创建一个单一真相来源。

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

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 的 schema 构建器，我们可以像强类型语言一样确保类型安全，并拥有单一真相来源。

标准 Schema

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

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 提供出色支持，其 schema 可用于数据验证、类型推断和从单一真相来源进行 OpenAPI 注解。

Elysia 还支持 直接从类型生成 OpenAPI schema，只需 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。