elysia-architecture

Elysia 架构

适用于 Elysia HTTP 应用的通用项目规范。单独使用此技能即可，不依赖其他技能。

**职责：**规定代码存放位置、文件夹和文件的命名方式，以及所有权边界。

**不属于此技能：**Elysia API 的特殊行为、插件生命周期细节、Eden、适配器或最新的框架文档。相关内容请优先参考当前的 Elysia 文档。

如果目标仓库已有架构文档（例如 AGENTS.md），且与此处冲突，除非用户要求迁移以符合此技能，否则以仓库规范为准。

技术栈默认设置（核心）

部分	默认设置
运行时	Bun（如果应用已使用 Node/适配器，也可以继续使用）
HTTP	将 Elysia 功能插件放在 src/modules/<feature>/ 下
版本	Elysia 1.4，且 ≥ 1.4.30（安全底线；绝不基于不可信输入构建路由 schema）。Elysia 2 仍处于 beta 阶段——稳定发布前，项目规范代码继续使用 1.4
模块布局	routes/ + schema/ + 领域逻辑文件夹
测试	仓库使用 Vitest 时，在 tests/ 下使用 Vitest（单元 / 集成项目）

领域逻辑可以使用纯 TypeScript 模块。存在相应技术栈时，加载匹配的 with-* 扩展（见下文）。

模式

1. 脚手架搭建——根据 checklist.md + tree.md 创建新的功能模块。
2. 应用规范——将新端点 / schema / 服务放在规范位置。
3. 审查——对照 rules.md 检查目录结构；提出移动建议；不要另创一套并行布局。

硬性规则（核心）

1. **功能模块 = src/modules/<feature>/。**按领域（billing、users）分组，而不是在应用根目录按技术层分组。
2. 每个路由文件 = 一个导出的 const Elysia 插件，带有稳定的 name，通常只处理一个 HTTP 动词（或紧密相关的一组动词）。不要将无关的动词塞进同一个文件。不要 export function makeXRoutes(...)。
3. routes/index.ts 仅作为挂载表——使用 .use(child)（+ prefix）。不要放处理器、领域逻辑或共享映射器。
4. schema 放在 schema/ 下（按需使用 body、response、query、params）。不要把 DTO 堆进路由文件；如果 schema 已定义契约，也不要另行创建手写的响应接口。
5. **路由保持精简。**HTTP 相关内容（认证守卫、状态映射、请求 / 响应）放在路由文件中；业务规则放在服务（或纯领域模块）中。
6. **不要创建路由工厂 / 共享 HTTP 封装。**不要另造封装处理器的 makeSyncGet、mapXToHttp 或 utils/*-http.ts。在各自的路由文件中直接处理边界逻辑。
7. 导入进程资源，不要注入。数据库、Effect 运行时、环境变量、队列等：使用 import { db } from "…"、import { runtime } from "…"。禁止使用 export function cmsRoutes(db: Db)、在功能路由上调用 .decorate("db", db) / .decorate("runtime", runtime)，或通过挂载表参数传递这些值。共享包插件可以接收选项（来源、前缀）；应用仍需导入各自的单例。
8. **仅在 HTTP 边界映射失败。**公开响应体保持精简（例如 { error: string } + 状态码）。不要泄露内部原因。
9. **不要为 HTTP 扩充 utils/。**优先使用 schema/、服务 / 领域逻辑，或直接在路由中处理边界逻辑。
10. **命名：**文件夹使用名词 / 领域名称；文件使用动作或方面名称（create.ts、status.ts）。叶子名称不要重复父文件夹名称（billing/billing-status.ts → billing/routes/status.ts）。
11. **导入方向：**routes → schema + services；services 不得导入 routes。跨功能依赖应通过 services / 共享包，而不是 route→route 导入。
12. 挂载：从应用入口（或父功能的挂载表）挂载功能目录树。

详细说明、反模式和示例：rules.md、tree.md、examples.md。

渐进式披露

需求	阅读
规范目录树和命名	references/tree.md
强制执行规则并规避反模式	references/rules.md
脚手架 / 审查清单	references/checklist.md
优劣布局示例	references/examples.md
可选的技术栈扩展	下方的 扩展

扩展

仅当存在匹配的技术栈（或用户提出要求）时，才加载扩展。 扩展会添加规则，不会替代核心目录树。

适用情况	扩展
Effect 服务 / Layers / 标记错误	with-effect.md
T3 Env / 包不得读取 process.env	with-env.md
会话身份验证挂载 + { auth: true } 宏	with-session-auth.md
能力 / 授权 / 身份权限	with-capability-authz.md
jobs / 公共 API 上的 Bearer API 密钥	with-api-key-auth.md
Drizzle 架构包 + 服务中的 DB	with-drizzle.md
从路由架构派生 OpenAPI	with-openapi.md
请求日志 + OTEL + Effect 追踪器	with-observability.md
稳定的公共错误正文 + 边缘映射	with-http-errors.md
packages/* 中的领域逻辑、应用模块中的 HTTP	with-domain-packages.md
共享与应用本地 Elysia 插件	with-shared-plugins.md
进程内 cron 触发	with-cron.md
Provider Webhook	with-webhooks.md
内部共享密钥路由	with-service-auth.md
Vitest — Eden treaty(app) / 测试内容	with-vitest.md