用途:这是 labring/fastgpt 项目的 API 路由开发规范,用于开发新的 Next.js API 路由、修改现有 API 的入参或出参、生成 API 类型定义与文档,以及审查 API 相关代码。
主要能力与核心规则:所有 API 必须用 zod schema 定义入参和出参,导出对应的 TypeScript 类型;schema 文件头部必须声明 API 信息(Route、Method、Description、Tags),入参用 schema.parse() 验证,函数返回值也必须用 schema.parse() 验证,并编写完整的 OpenAPI 文档。
使用方式:schema 文件放在 packages/global/openapi/[module]/[api].ts,文件头用注释块声明 API 名称、路由、HTTP 方法、详细描述与标签数组;字段需带 meta 的 example 和 description,嵌套对象与公共结构抽为独立 schema,列表接口继承 PaginationSchema。API 路由文件放在 projects/app/src/pages/api/[path]/[route].ts,标准模板为:导入 schema 与类型,handler 中先用 schema.parse(req.body) 或 parse(req.query) 验证入参,按需用 authApp 做权限验证,执行业务逻辑,再用 schema.parse() 验证出参并返回,最后 export default NextAPI(handler)。错误处理可用 APIError 配合 CommonErrEnum。
适用场景与限制:适用于 FastGPT 项目的 API 开发与审查。审查时须检查 API 声明、schema 定义、类型导出、meta 信息、入参出参验证、返回类型声明与权限检查。资料涉及具体标签归属规则、错误处理与若干常见问题示例;其他项目是否适用、依赖版本与许可等细节暂未提供。