20 万行代码:我们如何构建和维护大规模 AI 原型系统

项目简介

在三个月的时间里,我们从零开始搭建了一个包含 20 万行代码的 AI 原型系统。这是一个非常庞大的项目,就像建造一座大楼一样,需要科学的规划和管理。为了让这个系统易于维护和扩展,我们采用了一种叫做 monorepo(单一代码仓库)的项目管理方式,并特别注重可复用工具包的设计。这篇文档将用通俗易懂的语言,为大家介绍这个项目是如何组织和管理的。

picture-2025-03-26-19-10-13

什么是 monorepo?

monorepo 就像是一个巨大的收纳箱,我们把项目中所有的代码都整整齐齐地放在这个箱子里。想象一下你有很多玩具,如果把它们随意放在房间的各个角落,找起来会很麻烦。但如果你有一个大收纳箱,给每个玩具都安排一个固定的位置,那么无论是找玩具还是收拾玩具都会变得很容易。

monorepo 的好处有:

  1. 代码共享更方便:就像全家人共用一个工具箱,需要用工具的时候直接去工具箱里拿就行了
  2. 版本管理更统一:就像统一采购文具,避免每个人买的东西不一样导致混乱
  3. 团队协作更顺畅:就像在同一个工作室工作,大家可以随时交流和互相帮助

项目是如何组织的?

我们的项目就像一个精心设计的大楼,每一层都有它特定的功能:

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 原型系统。这种管理方式不仅让开发过程更加高效,也让后期的维护和升级变得更加容易。特别是通过精心设计的工具包体系,我们大大提高了代码的复用率,减少了重复开发的工作量。对于想要了解大型项目管理的朋友来说,这个项目的组织方式提供了一个很好的参考。

相关推荐
zhougl9961 小时前
html处理Base文件流
linux·前端·html
花花鱼1 小时前
node-modules-inspector 可视化node_modules
前端·javascript·vue.js
HBR666_1 小时前
marked库(高效将 Markdown 转换为 HTML 的利器)
前端·markdown
careybobo3 小时前
海康摄像头通过Web插件进行预览播放和控制
前端
杉之4 小时前
常见前端GET请求以及对应的Spring后端接收接口写法
java·前端·后端·spring·vue
喝拿铁写前端4 小时前
字段聚类,到底有什么用?——从系统混乱到结构认知的第一步
前端
再学一点就睡4 小时前
大文件上传之切片上传以及开发全流程之前端篇
前端·javascript
木木黄木木6 小时前
html5炫酷图片悬停效果实现详解
前端·html·html5
请来次降维打击!!!6 小时前
优选算法系列(5.位运算)
java·前端·c++·算法
難釋懷7 小时前
JavaScript基础-移动端常见特效
开发语言·前端·javascript