项目简介
在三个月的时间里,我们从零开始搭建了一个包含 20 万行代码的 AI 原型系统。这是一个非常庞大的项目,就像建造一座大楼一样,需要科学的规划和管理。为了让这个系统易于维护和扩展,我们采用了一种叫做 monorepo(单一代码仓库)的项目管理方式,并特别注重可复用工具包的设计。这篇文档将用通俗易懂的语言,为大家介绍这个项目是如何组织和管理的。
picture-2025-03-26-19-10-13
什么是 monorepo?
monorepo 就像是一个巨大的收纳箱,我们把项目中所有的代码都整整齐齐地放在这个箱子里。想象一下你有很多玩具,如果把它们随意放在房间的各个角落,找起来会很麻烦。但如果你有一个大收纳箱,给每个玩具都安排一个固定的位置,那么无论是找玩具还是收拾玩具都会变得很容易。
monorepo 的好处有:
- 代码共享更方便:就像全家人共用一个工具箱,需要用工具的时候直接去工具箱里拿就行了
- 版本管理更统一:就像统一采购文具,避免每个人买的东西不一样导致混乱
- 团队协作更顺畅:就像在同一个工作室工作,大家可以随时交流和互相帮助
项目是如何组织的?
我们的项目就像一个精心设计的大楼,每一层都有它特定的功能:
csharp
one-prototype/
├── apps/ # 各个独立应用的代码
│ ├── base/ # 独立的产品,包含服务部署、云实例等
│ ├── course/ # 高校场景相关的独立产品
│ ├── docs/ # UI 组件的文档
│ ├── idcloud/ # IDC 相关的独立产品
│ └── web/ # 独立的测试网页应用
├── packages/ # 可以共享的代码包
│ ├── eslint-config/ # 代码规范配置
│ ├── hooks/ # React 钩子函数
│ ├── request/ # 网络请求工具
│ ├── track/ # 用户行为跟踪工具
│ ├── typescript-config/# TypeScript 配置
│ ├── ui/ # 通用界面组件
│ └── zod/ # 数据验证工具
共享工具包详解
在 packages 目录下,我们精心打造了一系列可复用的工具包,它们就像是一个个专业的工具箱,每个工具箱都有其特定的用途。让我们深入了解这些工具包的特点和作用。
UI 组件库:标准化装修工具包
就像建筑工地的标准化部件,我们的 UI 组件库提供了一套完整的界面解决方案。它基于 Tailwind CSS 实现灵活的样式定制,采用 TypeScript 确保类型安全,并遵循 Radix UI 的无障碍设计原则。组件的高度可配置性使其能够支持多种场景的复用。
picture-2025-03-26-19-09-08
在开发效率方面,UI 组件库通过统一的设计语言和交互模式,为开发者提供了完善的组件文档和使用示例。快速的开发调试和主题预览功能,加上跨产品的复用能力,大大减少了重复开发的工作量。标准化的组件接口设计也让集成变得异常简单。
picture-2025-03-26-19-03-10
我们的文档系统基于 Storybook 构建,提供了交互式的组件展示和调试环境。开发者可以实时预览组件的外观和行为,动态修改组件属性,并在多种设备和主题下进行预览。规范的文档编写流程确保了组件用法、API 说明和最佳实践的完整记录。这种高效的开发工作流让组件的独立开发和测试变得轻松自如。
Zod 数据验证工具包:数据检验员
作为项目中的数据质检员,Zod 数据验证工具包严格把控着数据的格式和类型。它不仅能确保数据的正确性和安全性,还提供了强大的类型推导功能。特别是在与 React Hook Form 配合使用时,它能提供类型安全的表单验证,自动推导表单字段类型,在运行时确保数据安全,并提供友好的错误提示。
picture-2025-03-26-19-11-14
用户行为跟踪工具包:数据记录员
track 工具包就像是一个细心的记录员,它统一封装了多个主流的数据统计服务,包括 Umami、百度统计和 Microsoft Clarity 等。通过标准化的事件跟踪方法和自动的页面访问统计,它为产品提供了全面的数据分析能力。
picture-2025-03-26-19-03-47
这个工具包的一大特色是其多平台数据统计集成能力。它不仅支持开源的 Umami 统计,还能无缝对接百度统计服务和 Microsoft Clarity。开发者可以根据具体场景灵活切换不同的统计服务。在使用体验上,完善的 TypeScript 类型支持、自动的错误处理机制和丰富的调试信息,都让数据追踪变得轻松而可靠。
代码质量保障工具包:ESLint 和 TypeScript 的完美配合
就像建筑工地需要全方位的质量保障体系,我们的代码质量保障工具包通过 ESLint 和 TypeScript 的完美配合,为项目提供了全面的代码质量和类型安全保障。ESLint 负责统一团队代码风格,自动发现并修复代码中的潜在问题,同时实施最佳实践确保代码质量始终保持高水平。它与编辑器的紧密集成让开发者能实时获得代码改进建议。
TypeScript 则通过其强大的类型系统,在编译时就能捕获潜在错误。智能的代码提示和优秀的重构支持大大提升了开发效率,自动生成的类型声明确保了 API 使用的准确性。这两个工具的协同工作创造了一个完整的开发工具链,让团队协作更加顺畅,代码质量更有保障。
网络请求工具包:通信专家
request 工具包就像是一个专业的快递公司:
- 处理所有与服务器的数据交互
- 统一管理 API 请求
- 提供错误处理和重试机制
工具包的协同工作
这些工具包并不是独立运作的,它们之间相互配合,形成了一个完整的开发生态系统。UI 组件库借助 TypeScript 配置确保类型安全,网络请求工具与数据验证工具密切配合确保数据正确性,而用户行为跟踪则与 React Hooks 结合提供更好的用户体验。这种协同工作方式让整个系统更加稳定可靠。
项目管理工具
为了更好地管理这个大型项目,我们使用了两个主要工具:
- pnpm:一个高效的包管理工具,它帮我们管理项目中用到的各种工具和库
- Turborepo:专门用来管理大型项目的工具,让整个项目运行得更流畅
通过这样科学的项目组织和管理方式,我们成功地在三个月内构建了这个包含 20 万行代码的 AI 原型系统。这种管理方式不仅让开发过程更加高效,也让后期的维护和升级变得更加容易。特别是通过精心设计的工具包体系,我们大大提高了代码的复用率,减少了重复开发的工作量。对于想要了解大型项目管理的朋友来说,这个项目的组织方式提供了一个很好的参考。