elysia

Elysia 开发指南

本技能为在此项目中使用 Elysia 框架提供指导原则、模式和最佳实践。

快速入门

有关详细的开发指南、导入和模式，请参阅此技能目录中的 references/patterns.md。

核心理念

• 建议采用不拘泥于模式、但以功能为基础的结构
• **“1 个 Elysia 实例 = 1 个控制器”**原则
• 使用 TypeBox 进行强类型运行时验证
• 集中处理错误并保持响应一致
• 适用于生产环境的部署策略

结构、路由与控制器

基本组织模式

• 将 App 作为控制器：将每个 new Elysia({ prefix }) 实例视为该功能的控制器。不要直接将整个类的方法作为处理程序传入，而应内联一个简短的处理程序来调用服务函数。
• 功能文件夹：采用以功能为基础的结构：
  • src/modules/<feature>/index.ts - Elysia 控制器（路由、守卫、Cookie）
  • src/modules/<feature>/service.ts - 业务逻辑（不包含 HTTP 上下文）
  • src/modules/<feature>/model.ts - 通过 t（TypeBox）定义的架构和类型
  • 将共享实用工具放在 src/utils/* 中。
• 方法链式调用：路由、守卫和插件优先使用 Elysia 实例的流式链式调用。
• 插件：通过 .use() 将横切关注点封装为插件（例如 OpenAPI、JWT、CORS）。
• 上下文规范：如果服务需要请求数据，请将其保留在控制器中，并仅将相关字段传递给服务函数。

功能脚手架模式

创建功能脚手架时，生成以下内容：

1. model.ts，包含 t.Object(...) 架构，以及通过 typeof schema.static 导出的 type 别名。
2. service.ts，包含纯函数（或在不需要实例状态时，包含一个仅有静态成员的 abstract class）。
3. index.ts，用于挂载 Elysia 路由、通过共享验证应用 guard()，并返回带类型的响应。

验证、架构与类型

运行时验证 + 静态类型

• 使用 import { t } from 'elysia' 定义 Body、Query、Params、Headers、Cookie 和 Response 架构。
• 从 typeof schema.static 派生 TS 类型并导出（例如 export type SignInBody = typeof signInBody.static）。
• 使用 .guard({ ... }) 应用共享验证。组合多个守卫时，可考虑使用 schema: 'standalone' 使其彼此独立。
• 根据内容验证文件：使用标准架构系统时，使用 fileType（魔数）。
• 确保为 2xx 响应和错误变体提供响应架构，以实现强端到端类型检查。

处理程序架构指南

生成处理程序时：

• 包含第 3 个参数架构对象，其中含有 body/query/params/headers/cookie/response。
• 对 GET/HEAD 请求不要解析正文（Elysia 遵循 HTTP 规范）。
• 提供使用 t.Object、t.Array、t.Union、t.Literal 和文件架构的示例，并展示如何通过 guard() 共享 Query/Headers。

错误处理与响应结构

集中式错误管理

• 在 app 上使用 .onError(({ code, error, path, request }) => { ... })，将框架错误和自定义错误映射为统一的 JSON 结构（例如 { ok: false, error: { code, message, details } }）。
• 错误控制流优先使用 throw status(code, messageOrPayload)，以便 onError 捕获。注意：return status(...) 不会被 onError 捕获。
• 验证错误：将其规范化为可预测的 JSON（问题数组），同时在生产环境中隐藏敏感内部信息。
• 包含关联 ID（例如 x-request-id），并在 onError 中记录日志。避免在生产环境中泄露堆栈跟踪。
• 成功响应可选择包装为 { ok: true, data }，以保持统一。

错误插件结构

生成代码时，创建：

• src/plugins/error.ts，用于安装 .onError(...)。
• 可选的 src/plugins/logging.ts，用于在 onResponse 和 onError 中记录日志。

OpenAPI、身份验证与横切关注点

OpenAPI

• 添加 @elysiajs/openapi 插件并公开文档路由（Scalar UI）。
• 确保 响应 架构准确——OpenAPI 会根据它们生成文档。
• 如果要构建 SDK，请确保路由具有完整类型定义并提供示例。

身份验证

• 使用 @elysiajs/jwt 进行 JWT 签名和验证，或集成你选择的身份验证方案。
• 将身份验证放在一个插件中，在验证后用 user 装饰上下文。
• 通过 .guard({ headers: t.Object({ authorization: t.String() }) }) 保护路由，并在处理程序运行前验证 bearer 令牌。

横切插件

• 在需要的地方安装 @elysiajs/cors。
• 可考虑使用 @elysiajs/server-timing 和 @elysiajs/opentelemetry 进行可观测性监控。

生成脚手架时，请创建 src/plugins/openapi.ts、src/plugins/auth.ts，并在 src/app.ts 中接入它们。

部署、性能与 Docker

生产环境部署

• 多核场景使用 集群模式：使用一个小型启动器（index.ts）派生工作进程，并让每个工作进程导入 server.ts。
• 生产环境部署优先使用 Vite 或 esbuild 等打包工具进行构建。
• 如果编译会影响追踪（OpenTelemetry），请避免使用 --minify，或将已插桩的模块标记为 --external。
• 接受 process.env.PORT（并设置回退值），且绑定到 0.0.0.0，以适配 PaaS。

Docker

• 构建阶段：使用带有 pnpm 的 Node.js 基础镜像。
• 运行阶段：使用 distroless 基础镜像，复制二进制文件，并设置 CMD ["./server"]。

部署脚手架

生成部署脚手架时，请包含：

• src/index.ts（集群启动器）、src/server.ts（应用）、Dockerfile（多阶段）和构建脚本。

测试

单元测试

• 使用 vitest。
• 导入应用，并使用 app.handle(new Request(url, options)) 断言状态码、正文和标头。
• 对于服务测试，直接调用纯函数。

要包含的测试示例

• 返回文本的简单 GET 测试。
• 带有 body 验证的 POST 测试（包含有效和无效路径）。
• 使用模拟 Authorization 标头的经过身份验证的路由示例。
• 每个路由和每个服务优先编写小型、聚焦的测试。

快捷工具

常见模式

• 应用上下文：使用 .state() 和 .decorate() 添加版本信息、辅助函数等，然后从 { store, getDate } 中读取。
• 简单的实时 API 可通过 .ws() 创建 WebSocket 端点。
• 对特殊内容类型使用 .onParse() 自定义正文解析器。

验证清单

完成涉及 Elysia 的任务前：

• 功能结构遵循 model.ts、service.ts、index.ts 模式。
• 所有处理程序都有适当的架构定义（body/query/params/response）。
• 错误处理使用集中式 .onError() 插件。
• 为 OpenAPI 生成定义响应架构。
• 测试使用 app.handle(new Request(...)) 模式。
• 运行类型检查（pnpm run typecheck）和测试（pnpm run test）。

详细模式和代码示例请参阅 references/patterns.md。