elysia

Elysia

当工作涉及 Elysia 或 ElysiaJS 时，使用此技能。

工作流

1. 在提出更改前检查应用：
   • 已安装的 elysia 和相关 @elysia/* 包的版本。稳定版 latest 为 1.4.x（仅包含安全修复）；2.0.0-beta.x 以 next dist-tag 发布，并更改了核心 API。切勿在同一个应用中混用 1.4 和 2.0 语法。
   • 对于 1.4.x，要求版本 >= 1.4.30（<= 1.4.29 中的 schema 默认值和属性名称存在严重 RCE 安全公告）。
   • 运行时和适配器：Bun、@elysia/node、Deno、Cloudflare Worker、Vercel、Netlify 或其他 Web Standard 宿主。
   • 根实例、导出/监听形式、路由插件、前缀、守卫、宏、schema、错误钩子和测试。
   • 每个横切钩子的注册顺序和插件作用域。
2. 如果任务依赖最新 API、适配器、包兼容性、实验性支持或特定版本的行为，请查阅最新的官方文档。从 source-map.md 开始。
3. 将工作分配给相应的参考资料：
   • 设置、路由、处理器、流式传输和项目布局：setup-routing.md。
   • Schema、生命周期顺序、状态响应和错误：validation-lifecycle-errors.md。
   • 插件、作用域、守卫、宏、依赖项和上下文：plugins-context.md。
   • 测试、Eden、OpenAPI、WebSocket 和 SSE：testing-clients-realtime.md。
   • 运行时、部署、安全、可观测性和生产环境检查：production-runtime-security.md。
   • Elysia 2 beta 迁移、codemod 和从 1.4 到 2.0 的 API 变更：elysia-2-migration.md。
4. 保留仓库现有的架构和命令，除非用户明确要求迁移。
5. 在最小且有用的边界验证行为，然后验证组装后的应用。

核心判断

• 将 schema 视为可执行的 HTTP 契约。在边界处定义请求和各状态码对应的响应 schema；不要再用手写接口重复定义。
• 保持路由处理器精简。HTTP 相关逻辑优先使用按功能划分的 Elysia 实例；不需要请求上下文的业务逻辑则使用普通函数或模块。
• 在每个路由／插件文件中导出一个 const Elysia 实例。不要将路由封装在 export function featureRoutes(db) / (runtime) / 类似的工厂中。
• 在使用应用单例（数据库客户端、Effect ManagedRuntime、env、mailer）的模块中导入它们。服务导入 DB；路由仅导入 runtime 并用于 runPromise。不要将这些值作为函数参数传递，也不要仅为在处理器间传递它们而调用 .decorate("db", db)（或 runtime）。
• 接受选项的插件工厂仅用于可复用／共享插件（如 prefix、version、CORS origins 等配置）。不要用它来将应用的数据库或 runtime 注入功能模块。
• 让 Elysia 推断处理器上下文。如果解构后的值或由 schema 推导出的类型已足够，就不要在控制器或服务中传递宽泛的手动类型 Context。
• 遵守链式顺序。拦截器钩子会应用于其后注册的路由和插件，但 onRequest 会作用于所有传入请求。
• 遵守插件封装边界。插件的生命周期钩子和 schema 不会自动保护父级路由。应有意选择 local、scoped 或 global，并测试边界。
• 在 1.4 中，如果某个值依赖经过验证的请求数据，优先使用 resolve 而非 derive。derive 在验证前运行；resolve 在验证后运行。在 2.0 中，resolve 已移除，derive 会在 before-handle 阶段运行（即旧版 resolve 的时机）。
• 绝不要根据不可信输入（表单构建器、由数据库驱动的 schema）构建 schema、属性名称或 default 值。Elysia 会将它们编译为生成代码。
• 当需要类型安全的响应收窄时，对于预期的 HTTP 结果，返回 status(code, value)。在 1.4 中，仅当结果应交由 onError 处理时才抛出错误；在 2.0 中，返回的错误和抛出的错误都会到达 error 钩子。
• 生命周期去重很重要时，使用命名插件；如果配置会改变插件身份，还应使用 seed。
• 将 OpenAPI 安全声明仅视为文档。应在 guards、macros、钩子或处理器中强制执行身份验证和授权。
• 不要假定其他适配器支持仅限 Bun 的 API。server 和 server.requestIP 是 Bun 专属 API；实现必须考虑适配器和平台的限制。
• 不要将基准测试数据当作通用的应用性能保证。应对实际应用和运行时进行性能分析。
• 使用 Eden Treaty（@elysia/eden 中的 treaty(app)）测试 HTTP 端点。禁止使用 app.handle(new Request(...))、plugin.handle(...)，以及 const handle = (path) => app.handle(new Request(\http://localhost${path}\`))` 之类的辅助函数。

验证

优先使用仓库自带的命令。对于有实质影响的 Elysia 变更，覆盖相关子集：

• 使用实际运行时/适配器进行类型检查和生产构建。
• 使用 Eden Treaty 测试（treaty(app)），覆盖成功、验证失败、身份验证失败、错误映射、标头以及特定状态的响应正文。断言 { data, error, status }。
• 更改钩子、守卫、宏或插件组合时，进行作用域/顺序回归测试（仍使用 Treaty）。
• 对延迟或惰性加载的插件进行 Treaty 调用前，先执行 await app.modules。
• 当架构、响应状态映射、标签、安全元数据或类型生成发生变化时，检查生成的 OpenAPI。
• 当 listen/export、代理标头、Cookie、CORS 预检、流式传输或运行时特定行为发生变化时，进行真实 HTTP 冒烟测试。
• 当实时行为发生变化时，检查 WebSocket 连接、无效消息、关闭、超时和背压。
• 当适配器、打包、二进制编译、无服务器导出、环境变量或平台绑定发生变化时，针对部署目标进行冒烟测试。

报告运行了哪些检查、未运行哪些检查，以及仍存在的任何依赖版本的假设。