FastGPT Monorepo 包结构与依赖规范从 pnpm workspaces 到跨包类型导入的工程实践【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPTFastGPT 是一个基于 pnpm workspaces 的 monorepo 多包工程本文以仓库内 PR 审查规范.agents/skills/system/pr-review/style/package.md为骨架系统讲解其packages/与projects/两级目录的职责边界、包间依赖规则、fastgpt/*别名导入约定与公共类型导出要求并结合 pnpm-workspace.yaml、各包 package.json 与 tsconfig.json 给出可落地、可自检的工程实践。一、整体结构两级目录的职责划分FastGPT 的 monorepo 采用共享包packages 独立应用projects的两级结构其设计目标是让类型、工具函数、后端服务与前端组件各归其位同时让业务应用可以自由组合这些能力。packages/ ├── global/ # 类型、常量、工具函数 (无运行时依赖) ├── service/ # 后端服务、数据库模型 (依赖 global) └── web/ # 前端组件、样式、i18n (依赖 global) projects/ ├── app/ # NextJS 应用 (依赖所有 packages) ├── sandbox/ # NestJS 沙箱服务 (独立应用) └── mcp_server/ # MCP 服务器 (独立应用)对照仓库实际目录可以进一步细化这张图packages/global/以fastgpt/global为包名承载类型定义、常量与跨包共享的工具函数例如用户类型定义位于 packages/global/support/user/type.ts另含common/、core/、openapi/、support/、migration/、sdk/等子模块。packages/service/以fastgpt/service为包名是后端服务与数据库模型所在包含common/、core/、support/、worker/、thirdProvider/等目录并在 package.json 中声明了 mongoose、minio、mysql2、pg、milvus SDK 等数据与基础设施依赖。packages/web/以fastgpt/web为包名沉淀前端组件、样式与 i18n 能力依赖 Chakra UI、Lexical、Monaco Editor、react-query 等前端生态库。projects/app/主应用Next.js 项目同时依赖fastgpt/global、fastgpt/service、fastgpt/web三个包见 projects/app/package.json并额外消费fastgpt-sdk/*系列 SDK。值得说明的是规范文档中的projects/sandbox在仓库中的实际命名是projects/code-sandbox代码沙箱运行服务而projects/mcp_server、projects/marketplace、projects/volume-manager都属于独立部署的应用或服务。此外仓库还通过 pnpm-workspace.yaml 将pro/*、sdk/*、document/、scripts/icon一并纳入 workspace共享版本目录catalog:。二、依赖规则单向依赖杜绝循环规范给出的依赖审查要点是一套单向无环的约束包允许依赖不允许依赖packages/global/无任何运行时依赖不可依赖 service / webpackages/service/仅packages/global/不可依赖 webpackages/web/仅packages/global/不可依赖 serviceprojects/app/所有 packages—独立项目sandbox、mcp_server最小化依赖不应无节制引入 packages从实际 package.json 看packages/global/package.json 的dependencies仅包含 zod、axios、ajv、openai、lodash-es、nanoid、dayjs 等通用基础库没有依赖任何fastgpt/*内部包满足无内部运行时依赖的要求packages/service/package.json 以fastgpt/global: workspace:*引用 global并引用fastgpt/dal与fastgpt-sdk/otel、fastgpt-sdk/sandbox-adapter、fastgpt-sdk/storage等 SDK 包但不引用fastgpt/webpackages/web/package.json 同样仅以fastgpt/global: workspace:*依赖内部包满足前端只依赖 global的约定projects/app、projects/marketplace可以同时依赖三个 packages而projects/code-sandbox、projects/mcp_server、projects/volume-manager只依赖fastgpt/global一个包恰好印证了独立项目最小化依赖的原则。这种单向依赖的价值在于底层包global的变更不会向其他包传播复杂联动任何一层被替换或单独测试时不会拖入整棵依赖树同时配合workspace:*协议见各 package.jsonmonorepo 内无需发布 npm 包即可完成本地链接。三、导入规范用别名代替跨包相对路径规范明确要求跨包引用必须使用项目别名fastgpt/global、fastgpt/service、fastgpt/web禁止使用穿越多个目录的相对路径并推荐通过各包的 index 入口简化导入。反面与正面示例摘自规范文档// ❌ 不好的导入穿越多个目录的相对路径且直接指向 .d.ts 实现文件 import { UserType } from ../../../../../packages/global/core/user/type.d.ts; // ✅ 好的导入使用包别名路径短、稳定、语义清晰 import { UserType } from fastgpt/global/core/user/type;在仓库中可以找到该规范的落地证据用户类型确实定义在 packages/global/support/user/type.ts以export type导出UserType等公共类型而应用侧通过 tsconfig 的paths将别名解析到源码。以 projects/app/tsconfig.json 为例除了fastgpt-sdk/*系列被显式映射到sdk/*/src/index.ts外/*映射到应用自身src/*fastgpt/global、fastgpt/service、fastgpt/web则通过 packages 各包 tsconfig.json 的paths配置完成别名解析。别名导入的具体收益重构友好包内文件移动时外部引用无需逐个修改相对路径边界清晰一眼即可看出依赖方向违反依赖规则的导入在代码评审时无处遁形编辑器与编译链一致tsconfigpaths与 pnpmworkspace:*协议双保险保证 IDE 跳转与构建产物一致。四、类型导出公共类型的规范化出口规范对类型文件提出四点审查要求公共类型必须导出不导出即视为内部实现细节类型文件使用.d.ts扩展名复杂类型放在独立的类型文件不与其他实现代码混写使用export type显式导出类型。结合仓库实现来看类型定义普遍遵循独立文件 显式导出的组织方式。例如 packages/global/support/user/type.ts 独立承载用户相关类型并通过export type导出projects/app/tsconfig.json 中include显式覆盖了../../packages/**/*.ts、*.tsx与*.d.ts保证类型文件被正确纳入编译范围。对评审与开发者的实操建议类型集中一个领域user、dataset、app 等一个 type 文件命名形如xxx/type.ts避免在业务组件或路由文件里散落内联类型显式导出统一使用export type与值导出区分便于 tree-shaking 与类型检查公开 API 面只有被export的类型才构成该包的公共 API未导出的类型视为内部细节其他包不应以相对路径直接引用否则会破坏包的封装边界。五、工程配套workspace 协议与构建编排包结构规范并非孤立存在仓库通过以下配套设施保证其在工程中可执行pnpm workspaces 声明pnpm-workspace.yaml 用packages:通配符收纳packages/*、projects/*及sdk/*等目录并用catalog:统一锁定关键依赖版本如 next、react、zod、typescript 等避免各包版本漂移turbo 任务编排turbo.json 定义了dev、builddependsOn: [^build]按依赖拓扑顺序构建、lint、test、typecheck等任务其中build的^build依赖声明正是依赖规则在构建链上的直接体现——先构建被依赖的 packages再构建应用运行环境要求各包 package.json 统一声明node 22.23.2、pnpm 10.x保证 workspace 解析与catalog:协议行为一致。六、评审自检清单将规范落地为可执行的 review 检查项可按以下顺序快速核对一个 PR 是否符合包结构与依赖规范目录归属改动文件是否落在职责匹配的包/应用内类型常量 → global后端逻辑 → service前端组件 → web应用编排 → projects/app依赖方向新增 import 是否引入跨包依赖service 是否引用了 webglobal 是否新增了内部包依赖可 grepfrom fastgpt/快速核对导入写法跨包引用是否统一使用fastgpt/*别名是否还存在../../packages/...式穿越路径类型出口公共类型是否独立成文件、以export type导出是否存在应归入 global 却被应用侧内联定义的类型最小化独立项目code-sandbox、mcp_server、volume-manager是否保持了最小依赖面未引入无关 packages。七、小结FastGPT 的包结构与依赖规范以单向依赖、别名导入、显式类型导出三条主线把 monorepo 的复杂度约束在可预期的范围内packages/global作为零内部依赖的底层地基service与web各自向上一层且只依赖 globalprojects/app作为唯一的自由组合层。配合 pnpmworkspace:*协议与 turbo 的^build拓扑构建这套约定既保证了类型与工具的单点复用也让代码评审对依赖边界的审查变得可枚举、可执行。对于任何正在治理大型 TypeScript monorepo 的团队上述规范与自检清单都可直接借鉴。【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考