SuperAPI AI 工具集

server-gateway-refactor

编程与开发

查看项目

更新于 10-16 01:17

技能介绍

用途:当 apps/server 的某个路由文件已膨胀为传输、业务与基础设施混杂的模块,且用户希望做工程化重构而非单纯按行数拆分时使用本技能。

主要能力:先阅读用户指定的路由文件及其附近测试与领域服务,用 rg 查调用点,未核对测试、文档与环境变量引用前不删除旧路由。识别四类职责:HTTP/WebSocket 传输形态(Hono 路由、鉴权、请求解析、响应挂载、升级设置);网关操作形态(已认证用户、解析后的 body/query、operation id、模型/提供商路由、外部调用);基础设施行为(计费、限流、遥测/追踪、请求日志、PostHog、重试、缓存);领域服务(持久化、Stripe 记录、角色/提供商归属、聊天消息、flux 交易)。

边界规则:仅当能从原始 Context 运行时,Hono 中间件才保持为 Hono 中间件(鉴权、配置可用性、静态文件、IP 级限流);需要解析后的网关上下文(用户 id、operation id、请求体、请求模型、解析模型、流式生命周期、用量或计费状态)时使用网关中间件。端点专属行为优先用路由组作用域中间件,例如 gateway.route('openai').use('chat.completions', rateLimit).post(...),避免对仅对某端点组有意义的中间件使用全局 gateway.use。不要创建只做 parse + operation 透传的 handler 文件,除非它隐藏了有意义的协议决策;不要仅按执行顺序拆分,模块边界应拥有策略、操作、中间件或外部边界。

命名:文件名用 kebab-case;传输文件用 HTTP 名称,业务文件用操作名称;中间件优先放 middlewares/;可复用操作编排优先放 operations/<operation>/index.ts;除非模块确实拥有路由/运行时组合,避免用 gateway 作领域名。

适用信号:单路由文件超过约 200-300 行且混有外部提供商编排;存在无法用 Hono 中间件表达的端点专属中间件需求;测试更多描述操作行为而非路由匹配;一个传输面下有多个业务操作。不适用:CRUD 路由已很薄并委托领域服务;路由主要挂载框架自带 handler、静态资源或元数据端点;逻辑应放入已有领域服务。

验证:改动后先做定向校验,再跑更广检查:pnpm exec vitest run apps/server/src/routes/<route>/route.test.ts、pnpm -F @proj-airi/server typecheck、pnpm exec eslint <changed files>。若全量 pnpm lint 因无关的仓库级问题失败,单独报告并保留定向 lint 证据。