FastGPT API 开发规范

FastGPT 项目 API 路由开发的标准化指南,确保 API 的一致性、类型安全和文档完整性。

何时使用此技能

• 开发新的 Next.js API 路由
• 修改现有 API 的入参或出参
• 需要 API 类型定义和文档
• 审查 API 相关代码

核心原则

🔴 必须遵守的规则

1. API 中实际存在的业务入参和业务出参必须使用 zod schema 定义；无入参或空成功响应不创建空 Schema
2. 已定义的 schema 必须导出对应的 TypeScript 类型
3. 必须在 schema 文件头部声明 API 信息(路由、方法、描述、标签)，一次性管理员升级/清洗能力除外
4. 实际存在的入参必须使用 parseApiInput 验证；完全无入参时不做空 Query/Body Schema 校验
5. 实际存在业务数据的函数返回值必须使用 schema.parse() 验证；空成功响应直接返回 undefined，不做空 Schema 校验
6. 必须编写完整的 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';

/* ============================================================================
 * API: 获取应用对话日志列表
 * Route: POST /api/core/app/logs/list
 * Method: POST
 * Description: 获取指定应用的对话日志列表,支持分页和多种筛选条件
 * Tags: ['App', 'Log', 'Read']
 * ============================================================================ */