第 2 章 整体架构设计入门

本章目标搞懂项目为什么要分层每一层是干什么的⭐⭐ 难度基础 | ⏱️ 预计时间40 分钟2.1 为什么需要「架构」先想一个问题如果让你写一个简单的 TodoList你会怎么写// 一个文件搞定 function App() { const [todos, setTodos] useState([]); function addTodo(text) { setTodos([...todos, { id: Date.now(), text, done: false }]); } // ... 一堆 JSX return div.../div; }很简单对吧一个组件就搞定了。但是如果我们要做的是AI Agent 工作台呢要同时处理多个 AI 助手的列表每个助手的多个对话每个对话的大量消息实时流式回复工具调用和执行日志审批流程定时任务…这时候如果还把所有东西塞在一个组件里会怎么样 一个文件几千行改一个 bug 牵一发动全身新人根本看不懂…这就是架构要解决的问题把复杂的系统拆成小部分每部分各司其职既清晰又好维护。2.2 五层架构从简单到复杂我们的项目采用五层架构从上到下像搭积木一样┌─────────────────────────────────┐ │ 第5层路由层(Router)│ ← URL 和页面对应起来 ├─────────────────────────────────┤ │ 第4层视图层(Components)│ ← 用户看到的界面 ├─────────────────────────────────┤ │ 第3层状态层(Store / MobX)│ ← 数据和业务逻辑 ├─────────────────────────────────┤ │ 第2层网关层(Gateway)│ ← 统一管后端通信 ├─────────────────────────────────┤ │ 第1层传输层(HTTP / WS)│ ← 发请求、收数据 └─────────────────────────────────┘核心原则每一层只能调用下面那层的东西不能越级调用也不能反过来。就像公司的层级员工 → 经理 → 总监 → CEO你不能直接跳过经理找 CEO 汇报。2.3 每一层是干什么的第 1 层传输层最底层干什么的负责真正的网络通信——发 HTTP 请求、建立 WebSocket 连接。用什么技术HTTP 请求axios库WebSocket浏览器原生的WebSocketAPI生活类比就像快递员负责把包裹送出去、把包裹拿回来。快递员不管包裹里是什么只管送。// 传输层只关心 // → 把数据发出去 // ← 把数据拿回来第 2 层网关层干什么的把传输层封装起来给上面的状态层提供统一的、好用的接口。为什么需要这一层想象一下有的接口是 HTTP 请求有的接口走 WebSocket有的接口是「发个消息然后等回复」请求-响应模式有的接口是「订阅了就一直推数据」发布-订阅模式如果让上层直接用传输层那上层代码会很乱到处都是 axios 和 WebSocket 的调用。网关层做的事就是把这些差异藏起来上面只管调方法就行。生活类比就像公司前台你只需要跟前台说「我要寄个快递」前台会帮你叫快递员、填单子你不用管是顺丰还是圆通。// 上层代码调用网关不用管底层是 HTTP 还是 WSconstagentsawaitgateway.getAgents();gateway.sendMessage(你好);第 3 层状态层Store干什么的管理所有数据和业务逻辑。包括什么现在选中了哪个 AI 助手对话列表有哪些当前对话的消息有哪些AI 正在回复吗执行面板显示什么有多少条未读消息…为什么不直接在组件里管数据因为很多数据是多个组件共享的。比如侧边栏要显示未读消息数聊天窗口要显示消息列表头部要显示当前对话标题这些数据如果每个组件自己管就会不一致。状态层就是「唯一数据源」大家都从这里拿数据。生活类比就像公司的数据库/档案室所有数据都存在这里各部门需要就来查保证大家看到的数据是一样的。状态层数据 操作数据的方法 ├── agents 列表 ├── 当前选中的对话 ├── 消息列表 └── 获取数据、修改数据的方法第 4 层视图层Components干什么的就是用户看到的界面——按钮、输入框、消息气泡、侧边栏…原则视图层尽量「傻」一点只管渲染和交互复杂的业务逻辑都放到状态层。好的视图组件是这样的function MessageList() { // 从 store 拿数据 const messages useStore(store store.messages); // 渲染就完事了 return ( div {messages.map(msg MessageBubble msg{msg} /)} /div ); }生活类比就像公司的前台展示屏只负责展示数据数据本身是从后台系统来的。第 5 层路由层最上层干什么的把 URL 和页面对应起来。比如访问/agent/123→ 显示 ID 为 123 的 AI 助手访问/agent/123/456→ 显示 ID 为 456 的对话访问/settings→ 显示设置页面用什么技术react-router-dom生活类比就像大楼的楼层导览牌告诉你几楼是什么部门。2.4 数据流是怎么走的整个应用的数据流动是单向的用户点击按钮 │ ▼ 组件调用 store 的方法 │ ▼ store 调用 gateway 的方法 │ ▼ gateway 发 HTTP/WS 请求给后端 │ ▼ 后端返回数据 / 推送事件 │ ▼ gateway 把数据变成统一格式 │ ▼ store 更新数据 │ ▼ MobX 自动通知组件 → 组件重新渲染 → 用户看到新界面记住这个方向从组件往下走到后端后再往上回来最后回到组件。永远是这个方向不会反过来。2.5 领域模型核心概念一览在深入代码之前先搞清楚几个核心概念。就像学做菜之前先认识食材一样。核心实体关系图用户(User)│ └── 拥有多个 → AgentAI 助手 │ ├── 有多个 → Conversation对话 │ │ │ └── 有多个 → Message消息 │ │ │ └── 可能触发 → Run一次运行 │ │ │ └── 产生 → ExecutionEvent执行事件 │ ├── 有多个 → Skill技能 ├── 有多个 → CronTask定时任务 └── 有多个 → Memory记忆每个概念是什么概念一句话解释生活类比AgentAI 助手能聊天也能做事你的私人助理Conversation一次对话包含多条消息一个聊天窗口Message对话里的一条消息聊天记录里的一条RunAgent 处理一次用户请求的全过程助理接了一个任务ExecutionEventAgent 执行过程中的事件助理做事的每一步记录SkillAgent 的技能助理会的本事写文档、查数据…Approval审批请求助理要做重要的事前先请示你2.6 路由结构设计我们的工作台有哪些页面呢/agent/# 首页Agent 列表 会话列表/agent/:agentId/# 选中了某个 Agent/agent/:agentId/:conversationId# 选中了某个对话聊天界面/cron/# 定时任务列表/cron/:taskId# 定时任务详情/settings/profile# 设置 - 个人资料/settings/agent# 设置 - Agent 配置/memory/# 记忆管理小贴士你会发现 URL 是有层次的/agent/→ 所有 Agent/agent/123/→ ID 为 123 的 Agent/agent/123/456→ Agent 123 下面的对话 456这种设计叫RESTful 风格读 URL 就知道在看什么。2.7 本章小结你学到了什么✅ 知道了为什么需要架构复杂项目不能全写在一个文件里✅ 了解了五层架构路由 → 视图 → 状态 → 网关 → 传输✅ 理解了每一层的职责✅ 知道了数据流的方向单向流动✅ 认识了核心领域概念Agent / Conversation / Message / Run…✅ 了解了路由结构设计核心原则再强调一遍原则说明分层解耦每一层只管自己的事不操心下一层怎么实现单向依赖上层调用下层下层不知道上层存在唯一数据源数据都在 Store 里组件从 Store 取视图要傻组件尽量只负责渲染逻辑放 Store✏️ 动手练习在一张纸上画出五层架构图试着不看教程自己标出每一层的名字和作用用你自己的话给身边的人解释一下「为什么需要网关层」想一想如果你要做一个「外卖 App」你会怎么分层每一层放什么下一章我们开始动手写代码把项目的工程化基础搭建好——样式配置、代码规范、路径别名等。