SuperAPI AI 工具集

elysia-architecture

通用与其它

查看项目

更新于 10-15 21:11

技能介绍

用途:为 Elysia HTTP 应用提供可移植的“内部风格”,规定代码放在哪里、文件夹与文件如何命名、以及各层职责边界。该技能可单独使用,不依赖其他技能。它不涉及 Elysia API 细节、插件生命周期、Eden、适配器或最新框架文档,这些应查阅当前 Elysia 官方文档。若目标仓库已有架构文档(如 AGENTS.md)且冲突,以仓库为准,除非用户要求迁移。

主要能力与规则:按领域分组,功能模块位于 src/modules/<feature>/,含 routes/、schema/ 与领域逻辑目录;一个路由文件导出一个命名稳定的 Elysia 插件,通常对应一个 HTTP 动词或紧密相关的一组,禁止把无关动词塞进同一文件,也不导出 makeXRoutes 之类的工厂函数;routes/index.ts 仅作挂载表,用 .use(child) 加前缀,不含处理器、领域逻辑或共享映射器;schema 放在 schema/ 下,不在路由文件里堆 DTO;路由保持薄,HTTP 关注点(鉴权守卫、状态映射、请求响应)留在路由文件,业务规则放服务或纯领域模块;禁止路由工厂与共享 HTTP 包装器;数据库、Effect 运行时、环境、队列等进程资源用 import 导入而非注入,禁止 .decorate 或通过挂载表参数传递;失败只在 HTTP 边界映射,公开响应体保持精简;命名上文件夹用名词/领域,文件用动作或方面,叶子名不重复父文件夹;导入方向为 routes → schema + services,服务不得导入路由,跨功能依赖走服务或共享包;从应用入口或父功能挂载表挂载功能树。

使用方式:提供三种模式——Scaffold(按 checklist.md 与 tree.md 新建功能模块)、Apply(把新端点、schema、服务放到规范位置)、Review(对照 rules.md 比较目录树并提出移动建议,不另造并行布局)。渐进披露:目录树与命名读 references/tree.md,规则与反模式读 references/rules.md,脚手架与审查清单读 references/checklist.md,好坏布局对比读 references/examples.md。

可选扩展:仅当对应技术栈存在或用户要求时加载,扩展只增加规则、不替换核心目录树,包括 Effect、T3 Env、会话鉴权、能力授权、API Key 鉴权、Drizzle、OpenAPI、可观测性、HTTP 错误、领域包、共享插件、cron、webhooks、服务鉴权、Vitest 等。

限制:默认运行时为 Bun,HTTP 用 src/modules/<feature>/ 下的 Elysia 功能插件,版本为 Elysia 1.4 且不低于 1.4.30(安全下限,绝不用不可信输入构建路由 schema),Elysia 2 为 beta,稳定发布前保持 1.4;测试在仓库使用 Vitest 时放 tests/ 下。资料未提供具体安装命令、收费与价格信息。