FastGPT API 开发规范
FastGPT 项目 API 路由开发的标准化指南,确保 API 的一致性、类型安全和文档完整性。
何时使用此技能
- 开发新的 Next.js API 路由
- 修改现有 API 的入参或出参
- 需要 API 类型定义和文档
- 审查 API 相关代码
核心原则
🔴 必须遵守的规则
- API 中实际存在的业务入参和业务出参必须使用 zod schema 定义；无入参或空成功响应不创建空 Schema
- 已定义的 schema 必须导出对应的 TypeScript 类型
- 必须在 schema 文件头部声明 API 信息(路由、方法、描述、标签)，一次性管理员升级/清洗能力除外
- 实际存在的入参必须使用
parseApiInput验证；完全无入参时不做空 Query/Body Schema 校验 - 实际存在业务数据的函数返回值必须使用 schema.parse() 验证；空成功响应直接返回
undefined，不做空 Schema 校验 - 必须编写完整的 OpenAPI 文档，一次性管理员升级/清洗能力除外
管理员升级与清洗能力的文档豁免
仅供系统管理员执行、用于一次性升级、迁移、修复或数据清洗的内部接口和脚本，不属于产品 API，不要求：
- 在
packages/global/openapi/声明接口文档； - 注册 OpenAPI Path；
- 编写 API 头部路由、方法、描述和标签信息。
豁免只针对文档，不豁免安全和校验要求：
- 管理员接口必须使用
authSystemAdmin鉴权； - 实际存在的 API 入参必须使用 Zod Schema 和
parseApiInput，完全无入参时不创建空 Schema； - 实际存在业务数据的返回值必须使用 Zod Schema 校验，空成功响应直接返回
undefined； - 数据清洗默认使用 dry-run，显式确认后才能写入，并输出成功、跳过和失败统计；
- 清洗逻辑应可重复执行，无法安全修复的数据必须跳过并报告，不得静默填入猜测值。
常规管理员产品接口（例如模型配置 CRUD、用户管理和系统配置）不因仅管理员可用而获得豁免，仍需按标准 API 流程维护文档。
开发流程
步骤 1: 定义 Zod Schema 并声明 API
文件位置: packages/global/openapi/[module]/[api].ts
文件头部必须声明 API 信息:
import { z } from 'zod';
/* =========…
