SuperAPI AI 工具集

api-endpoints

编程与开发

查看项目

更新于 10-16 06:22

技能介绍

用途:在 apps/api 中新增或修改 API 端点,并排查 mcp.json、openapi.json 与 SDK 不同步的问题。核心思路是单一来源:每个端点用 defineApiEndpoint 加 Zod schema 声明一次,自动派生四种形态——Hono HTTP 路由、OpenAPI 操作(经 Fern 生成 TS SDK)、MCP 工具、SDK 方法,无需分别写三份配置。

主要能力与用法:先检查 Web UI 是否已有同一动作,优先复用 @domain/* 用例;若逻辑内联在 server fn 中,先抽成 domain 用例再让 Web 与 API 共用;若依赖第三方进程内实例,则编写等价用例并加一致性测试。新增路由文件时导出挂载路径常量,用 defineApiEndpoint 绑定 Env 与路径,为每个字段写 .describe(),用 .openapi("Name") 注册命名 schema 组件,再在 routes/index.ts 挂载。运行 pnpm openapi:emit 与 pnpm mcp:emit 重生成清单并提交,SDK 由 pnpm generate:sdk 生成。

限流:每个端点通过 mountHttp(app, createTierRateLimiter("low")) 单独指定层级,按组织 id 计费;low 为 100 次/分/组织,medium 60,high 15,critical 3,默认选 low。不要用 app.use(path, mw) 设置层级。

限制与规范:描述面向 SDK 用户与 AI 智能体,须写契约而非实现细节,避免软删除、缓存、内部表名等机制;不要用 .openapi({ description }),因其不会传播到 MCP。可用 tool: false 让某路由不注册为 MCP 工具。提交前运行 typecheck、test 并确认两个清单无漂移。具体实现细节以仓库资料为准,其余未提供。