第 5 章网关层与通信基础-北京尧图网络

本章目标理解网关层的作用学会设计统一的通信抽象层⭐⭐⭐ 难度进阶基础 | ⏱️ 预计时间1.5 小时5.1 为什么需要网关层先想一个问题如果让你直接在组件里调用接口你可能会这么写function AgentList() { const [agents, setAgents] useState([]); useEffect(() { // 直接用 axios 发请求 axios.get(/api/agents).then(res { setAgents(res.data); }); }, []); // ... }看起来没问题对吧但是项目变大之后你会遇到这些问题问题说明接口满天飞每个组件自己发请求到处都是 axios 调用数据格式不统一这个接口返回{ code, data }那个返回{ status, result }通信方式多样有的接口走 HTTP有的走 WebSocket还有的要轮询难测试组件直接依赖 axios写测试要 mock 半天换接口费劲后端改了接口路径要到处找哪里调用了网关层就是来解决这些问题的。它就像一个「翻译官」把各种乱七八糟的通信方式翻译成统一的、好用的接口给上层用。5.2 网关层设计思想门面模式Facade Pattern网关层用的是门面模式——对外提供一个统一的大接口内部封装了复杂的子系统。上层代码Store / 组件 │ ▼ ┌───────────────────┐ │ Gateway 门面 │ ← 统一的、干净的接口 │ getAgents()│ │ sendMessage()│ │... │ └─────────┬─────────┘ │ ┌─────┴─────┐ ▼ ▼ HTTP WebSocket(axios)(原生WS)上层代码只知道「我可以调用这些方法」不用管底层是 HTTP 还是 WS不用管请求地址是什么不用管返回格式是什么。接口先行先定义契约好的做法是先定义接口interface再写实现。// 先定义网关应该提供哪些能力interfaceWorkbenchGateway{// 获取 Agent 列表getAgents():PromiseAgent[];// 获取会话列表getConversations(agentId:number):PromiseConversation[];// 发送消息sendMessage(params:SendMessageParams):PromiseSendMessageResult;// 订阅实时事件subscribeEvents(callback:(event:RealtimeEvent)void):()void;// ...更多方法}核心概念接口interface是契约。上层只依赖契约不依赖具体实现。这样以后换实现比如从 HTTP 换成 mock从 WS 换成 SSE上层代码一行都不用改。5.3 动手实现第一个网关安装 axiosnpminstallaxios# 或者yarnaddaxios创建 HTTP 客户端创建src/services/http.tsimportaxiosfromaxios;// 创建 axios 实例统一配置consthttpaxios.create({baseURL:/api,// 接口前缀timeout:30000,// 超时时间 30 秒});// 请求拦截器统一加 token 等http.interceptors.request.use(config{consttokenlocalStorage.getItem(token);if(token){config.headers.AuthorizationBearer${token};}returnconfig;});// 响应拦截器统一处理错误http.interceptors.response.use(response{// 统一返回 data 部分returnresponse.data;},error{console.error(请求出错,error);returnPromise.reject(error);});exportdefaulthttp;小贴士axios 拦截器是个好东西。所有请求统一加 token、所有响应统一处理错误不用每个请求都写一遍。定义类型和接口创建src/services/gateway/types.ts// 领域类型 exportinterfaceAgent{id:number;name:string;description:string;online:boolean;avatar?:string;}exportinterfaceConversation{id:string;title:string;agentId:number;lastMessage?:string;lastMessageAt?:string;unreadCount:number;pinned:boolean;createdAt:string;updatedAt:string;}exportinterfaceMessage{id:string;role:user|assistant;content:string;createdAt:string;status?:pending|sending|sent|error;}// 网关接口 exportinterfaceSendMessageParams{agentId:number;conversationId:string|null;// null 表示新建对话content:string;}exportinterfaceSendMessageResult{messageId:string;conversationId:string;accepted:boolean;}exportinterfaceWorkbenchGateway{// Agent 相关getAgents():PromiseAgent[];// 会话相关getConversations(agentId:number):PromiseConversation[];getHistory(conversationId:string):PromiseMessage[];// 消息相关sendMessage(params:SendMessageParams):PromiseSendMessageResult;}划重点类型定义是网关层的灵魂。所有进出网关的数据都有明确的类型。上层不用猜接口返回什么。实现 HTTP 网关创建src/services/gateway/HttpGateway.tsimporthttpfrom../http;importtype{Agent,Conversation,Message,WorkbenchGateway,SendMessageParams,SendMessageResult,}from./types;exportclassHttpGatewayimplementsWorkbenchGateway{// Agent 相关 asyncgetAgents():PromiseAgent[]{// 后端返回格式可能是 { code: 0, data: [...] }// 我们在这里统一解析返回干净的领域类型constresawaithttp.get(/agents);returnres.data;}// 会话相关 asyncgetConversations(agentId:number):PromiseConversation[]{constresawaithttp.get(/agents/${agentId}/conversations);returnres.data;}asyncgetHistory(conversationId:string):PromiseMessage[]{constresawaithttp.get(/conversations/${conversationId}/messages);returnres.data;}// 消息相关 asyncsendMessage(params:SendMessageParams):PromiseSendMessageResult{constresawaithttp.post(/messages/send,params);returnres.data;}}创建工厂函数创建src/services/gateway/index.tsimport{HttpGateway}from./HttpGateway;importtype{WorkbenchGateway}from./types;// 工厂函数创建网关实例exportfunctioncreateGateway():WorkbenchGateway{// 以后可以根据环境切换// if (import.meta.env.MODE mock) {// return new MockGateway();// }returnnewHttpGateway();}在 Store 中使用修改src/store/RootStore.tsimport{makeAutoObservable,runInAction}frommobx;import{createGateway}from/services/gateway;importtype{WorkbenchGateway}from/services/gateway/types;import{AgentStore}from./AgentStore;import{ConversationStore}from./ConversationStore;// 我们下面会写exportclassRootStore{readonlyagentStorenewAgentStore();readonlyconversationStorenewConversationStore();privategateway:WorkbenchGateway;constructor(){this.gatewaycreateGateway();makeAutoObservable(this,{gateway:false},{autoBind:true});}// 初始化asyncbootstrap(){this.agentStore.setLoading(true);try{// 通过网关获取数据constagentsawaitthis.gateway.getAgents();runInAction((){this.agentStore.setAgents(agents);});}finally{runInAction((){this.agentStore.setLoading(false);});}}}小贴士runInAction是 MobX 的工具函数。异步操作之后修改状态要用它包裹一下这样 MobX 才能正确追踪。简单理解同步代码里改状态MobX 自动识别是 action异步回调里改状态需要手动用runInAction告诉 MobX。5.4 网关层的好处我们来总结一下加了网关层之后带来了什么好处好处具体体现统一数据格式不管后端返回什么格式网关层都解析成统一的类型屏蔽传输差异HTTP / WS / 轮询上层不用关心便于测试可以写 MockGateway前端开发不依赖后端便于切换以后换后端、换接口协议只改网关层集中管理错误处理、loading 状态、重试逻辑都可以在网关层统一做代码清晰Store 层只关注业务逻辑不操心接口细节5.5 会话列表 Store 实战让我们用刚学的知识写一个会话列表的 Store。创建 ConversationStore创建src/store/ConversationStore.tsimport{makeAutoObservable}frommobx;importtype{Conversation}from/services/gateway/types;classConversationStore{// 按 agentId 分组存储会话privateconversationsByAgentnewMapnumber,Conversation[]();// 每个 Agent 当前选中的会话privateselectedByAgentnewMapnumber,string|null();// 加载状态loadingAgentId:number|nullnull;constructor(){makeAutoObservable(this);}// 查询方法 getConversations(agentId:number):Conversation[]{returnthis.conversationsByAgent.get(agentId)??[];}getSelectedConversationId(agentId:number):string|null{returnthis.selectedByAgent.get(agentId)??null;}getSelectedConversation(agentId:number):Conversation|null{constselectedIdthis.getSelectedConversationId(agentId);if(!selectedId)returnnull;returnthis.getConversations(agentId).find(cc.idselectedId)??null;}// 修改方法 setConversations(agentId:number,conversations:Conversation[]){this.conversationsByAgent.set(agentId,conversations);// 如果还没有选中的默认选第一个if(!this.selectedByAgent.has(agentId)conversations.length0){this.selectedByAgent.set(agentId,conversations[0].id);}}selectConversation(agentId:number,conversationId:string|null){this.selectedByAgent.set(agentId,conversationId);}setLoadingAgent(agentId:number|null){this.loadingAgentIdagentId;}// 局部更新某个会话patchConversation(agentId:number,conversationId:string,patch:PartialConversation){constconversationsthis.conversationsByAgent.get(agentId);if(!conversations)return;constconversationconversations.find(cc.idconversationId);if(conversation){Object.assign(conversation,patch);}}}exportconstconversationStorenewConversationStore();在 RootStore 中加加载方法修改src/store/RootStore.ts加上切换 Agent 时加载会话列表的逻辑exportclassRootStore{// ...// 选择 AgentasyncselectAgent(agentId:number){this.agentStore.selectAgent(agentId);this.conversationStore.setLoadingAgent(agentId);try{constconversationsawaitthis.gateway.getConversations(agentId);runInAction((){this.conversationStore.setConversations(agentId,conversations);});}finally{runInAction((){this.conversationStore.setLoadingAgent(null);});}}}看到了吗业务逻辑选 Agent → 加载会话写在根 Store 里数据操作分散在子 Store 里网络请求通过网关走。每一层都只关心自己的事代码结构非常清晰。5.6 Mock 网关前端独立开发网关层还有一个超大好处可以写一个 Mock 版本前端不依赖后端就能开发和测试。创建src/services/gateway/MockGateway.tsimporttype{WorkbenchGateway,Agent,Conversation,Message}from./types;// Mock 数据constmockAgents:Agent[][{id:1,name:小运,description:运维助手帮你查服务器状态,online:true},{id:2,name:小办,description:办公助手帮你写文档排日程,online:true},{id:3,name:小审,description:审核助手帮你做内容审核,online:false},];constmockConversations:Recordnumber,Conversation[]{1:[{id:conv-1,title:CPU 使用率高的问题,agentId:1,lastMessage:CPU 使用率是 35%一切正常,lastMessageAt:2024-01-15T10:30:00Z,unreadCount:0,pinned:true,createdAt:2024-01-10T09:00:00Z,updatedAt:2024-01-15T10:30:00Z,},{id:conv-2,title:磁盘空间清理,agentId:1,lastMessage:已经清理了 2.5GB 空间,lastMessageAt:2024-01-14T16:00:00Z,unreadCount:2,pinned:false,createdAt:2024-01-12T14:00:00Z,updatedAt:2024-01-14T16:00:00Z,},],};exportclassMockGatewayimplementsWorkbenchGateway{asyncgetAgents():PromiseAgent[]{// 模拟网络延迟awaitdelay(300);returnmockAgents;}asyncgetConversations(agentId:number):PromiseConversation[]{awaitdelay(200);returnmockConversations[agentId]??[];}asyncgetHistory(conversationId:string):PromiseMessage[]{awaitdelay(200);return[{id:msg-1,role:user,content:帮我看看 CPU 使用率,createdAt:2024-01-15T10:00:00Z,},{id:msg-2,role:assistant,content:好的我来查一下... CPU 使用率是 35%一切正常。,createdAt:2024-01-15T10:00:05Z,},];}asyncsendMessage(params:any):Promiseany{awaitdelay(100);return{messageId:msg-Date.now(),conversationId:params.conversationId||conv-new,accepted:true,};}}// 辅助函数模拟延迟functiondelay(ms:number){returnnewPromise(resolvesetTimeout(resolve,ms));}然后在工厂函数里切换exportfunctioncreateGateway():WorkbenchGateway{if(import.meta.env.VITE_USE_MOCKtrue){returnnewMockGateway();}returnnewHttpGateway();}太方便了后端接口还没写好没关系用 Mock 网关先把前端做起来。等后端好了一行代码切换过去。5.7 本章小结你学到了什么✅ 理解了为什么需要网关层统一接口、屏蔽差异、便于测试✅ 学会了门面模式的设计思想✅ 学会了先定义接口契约再写实现✅ 实现了 HTTP 网关和 axios 封装✅ 写了 ConversationStore 并和网关层配合✅ 学会了用 Mock 网关实现前端独立开发核心概念回顾概念一句话解释网关层前后端之间的翻译官统一通信接口门面模式对外一个大接口内部封装复杂子系统接口契约interface 定义了能力上层只依赖接口不依赖实现Mock 网关假的网关实现用于前端独立开发和测试runInActionMobX 中异步修改状态时需要用的工具函数✏️ 动手练习跟着本章步骤把 HTTP 网关和 Mock 网关都实现一下新增一个SessionStore管理当前会话的消息列表有loadHistory()方法从网关加载历史消息在页面上展示 Agent 列表点击某个 Agent 能切换并显示它的会话列表思考一下如果有的接口走 WebSocket网关层应该怎么设计才能让上层不用管是 HTTP 还是 WS下一章是重点中的重点我们会学习 WebSocket 实时通信实现 AI 流式回复的效果——这是 AI 产品最核心的体验。

第 5 章网关层与通信基础

相关推荐

多谐振荡器从仿真到实物：Multivibrator.zip 设计避坑指南

HotSpot JVM核心机制：内存布局、垃圾回收与JIT编译调优

堆排序算法实验报告：Java实现、复杂度分析与避坑指南

更多资讯

K8s部署Redis生产级实战：持久化、高可用与Helm一站式避坑

QCustomPlot瀑布图绘制详解：从QCPColorMap到实时滚动实现

公共文化场馆携程评论爬取实战：反爬应对与文旅数据应用

用Go实现GitLab pre-receive钩子：强制规范commit message

PySOT评估必装pysot-toolkit：Ubuntu 16.04编译安装与评测原理详解

福克斯刷机避坑：ELM327改AS-Built配置与备份恢复全攻略

今日更新

Cephadm实战指南：Linux系统工程师的生产级Ceph集群部署与排障

不想再被 Token 额度卡脖子？把免费 API 接入 WorkBuddy 的完整教程

ITK中SpatialObject几何体系解析：坐标系、变换与管道集成

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？