FastGPT | 07 - OpenAPI 与 Zod 契约设计

开篇问题第六篇我们分析了 FastGPT 的 API 入口机制：请求进入NextAPI，由NextEntry统一处理 requestId、日志、CORS、Tracing、错误响应和parseApiInput。但 API 入口只解决“请求如何进入系统”的问题。真正让大型项目可维护的，是另一层能力：接口契约。FastGPT 的接口契约主要沉淀在：packages/global/openapi这里既定义 API 请求体、查询参数和响应结构，也定义 OpenAPI 文档路径、标签分组和不同文档入口。它和 Zod 深度结合，让同一份 schema 同时服务三件事：运行时入参校验。TypeScript 类型推导。OpenAPI 文档生成。这篇文章重点拆解：packages/global/openapi的目录约定。api.ts和index.ts如何分工。Zod schema 如何同时服务校验、类型和文档。Dev API、System OpenAPI、Admin API 三类文档如何生成。API 路由为什么不应该重复定义类型。