企业官网建设流程全解析

HermesGateway这个名字听起来有点唬人，但它其实是我最近重构一个老旧项目时随手起的内部代号——版本号是0.5，意思是核心链路已经跑通、能干活，但离生产级还有不少距离。整个设计从头到尾只围绕两个关键词：cmd 和 notify。用这两个最朴素的机制，我把前后端之间纠缠了大半年的耦合关系彻底拆开了，前端不再关心后端内部长什么样，后端也不用再为页面状态变化四处打补丁。这篇文章会把我踩过的坑、想清楚的道理、以及落地的代码逻辑完整写出来，给同样被前后端分离搞到头大的团队做个参考。

如果你现在正处在这种状态——接口越加越多、每次改需求前后端要联动改三处以上、实时数据全靠轮询硬撑，那这个思路大概率对你有用。我会先从耦合的根源讲起，再说cmd和notify分别是什么、为什么组合在一起能完成解耦，最后给出一份可以照着抄的实现方案和排坑记录。内容偏工程实践，代码量不多，重点在思路。

1. 为什么我会想到做HermesGateway：传统前后端耦合的痛

1.1 耦合的前端代码是怎么长出来的

先说一个真实的场景。我年初接手一个数据展示类项目，前端有十几个页面，后端有几十个接口。表面上看前后端是分离开的——前端部署在一台nginx上，后端是独立的Java服务，REST接口也画了Swagger文档。但真要改起需求来，处处都是绊脚石。

问题出在“分离”的颗粒度上。前端页面里到处是$.ajax({ url: '/api/data/xxx', ... })，每一个url背后都对应后端一个具体的Controller方法。页面加载时调一次接口拿初始数据，用户操作时又调几个接口，后端状态一旦发生变化，前端要么再主动刷接口，要么通过短轮询硬问。时间一长，前端代码里全是“拉数据”的逻辑，而不是“表达业务意图”的逻辑。一个按钮点击之后，前端要做的不是告诉后端“我想要完成某件事”，而是绞尽脑汁拼接口、对时间戳、处理返回结构。

这就在两边之间形成了一种隐性绑定：后端接口的入参、出参结构一旦变动，前端立刻跟着遭殃；前端页面结构调整，后端可能也要为同一个数据造出好几个不同粒度的接口。所谓的“分离部署”，到最后变成了“分开写代码、一起遭罪”。

1.2 我在真实项目里踩过的耦合坑

如果你觉得上面说的太抽象，我举几个具体踩过的坑。

第一个是状态同步问题。后端有个数据看板，每5秒刷新一次统计结果，前端需要实时展示。最初的做法是前端自己开一个定时器，每5秒调用一次统计接口。这个方案看着简单，但实际问题很大：前端定时器和后端数据生成节奏完全靠“约定”，一旦后端某个统计任务耗时超过5秒，前端就拿到重复数据；如果多个用户同时开看板，后端压力直接翻倍。说白了，前端在盲猜后端什么时候有新数据。

第二个是接口爆炸。同一个实体，列表页需要一个字段子集，详情页需要另一个字段子集，导出功能又要全量字段。后端为了迁就前端，一个对象拆出五六个查询接口，每个接口返回结构还略有差异。前端维护调用的时候，经常分不清该用哪个。

第三个是“联动通知”的实现方式。后端某个业务操作完成后，需要通知前端刷新两个页面、更新一个图表、弹一个提示。我当时最笨的做法是让前端在几个互不相干的位置反复调用接口去“对账”，后来实在受不了，才在项目里加了一套基于WebSocket的简陋推送。可一旦每个页面都自己连WebSocket，连接管理又变成新的麻烦。

1.3 解耦的边界到底是什么

这段经历让我反复想一个问题：前后端之间到底应该依赖什么才能算“解耦”？

解耦不等于把代码分成两个目录、两个仓库、两个部署单元。真正的解耦应该是：前端不依赖后端的内部实现细节，后端也不依赖前端的页面结构，两边只通过一个稳定的、契约化的协议进行沟通。REST接口当然也是一种契约，但它的粒度受“资源”的约束太强——你是围绕数据资源建模，而不是围绕业务意图建模。当你的功能需要跨多个资源、多个状态联动时，REST的接口设计就会变得非常别扭。

HermesGateway就是在这个思考下冒出来的。我想换一种交互方式：前端发送一个“命令”，后端执行这个命令，执行的结果通过“通知”推回前端。不纠结资源路径、不搞一堆HTTP状态码，让前后端在一个更抽象、语义更完整的层面协同。cmd负责表达“我要干什么”，notify负责表达“事情办完了/有新数据了”。分清楚这两件事，解耦的边界自然就出来了。

2. cmd + notify 架构的核心设计思路

2.1 cmd（命令）到底是什么

我这边的cmd不是指操作系统命令行，而是指一种消息模式：前端把一次交互动作抽象成一条结构化指令，发给网关。指令里包含“要做什么”和“做这件事需要的参数”，但完全不包含“这件事后端应该怎么实现”。

一条命令消息大概是这个格式：

{ "ver": 1, "id": "09f3c1a2-7d8b-4e6f-9a1b-2c3d4e5f6a7b", "cmd": "order.create", "params": { "customerId": "u_1024", "items": [ {"sku": "sku_01", "count": 2} ] }, "token": "auth_token_xxx", "ts": 1735206400000 }

核心字段就四个：id是请求的唯一标识，cmd是命令名，params是业务参数，token是调用方身份。网关收到之后，既不关心消息是从浏览器来还是从客户端来，也不关心前端接下来要刷新哪个页面，它只负责找到对应的命令处理器，把params扔进去，然后等结果。

这里最容易误解的一点是：cmd不是把REST接口换了个名字。REST的语义是“对资源的操作”，比如POST /api/orders意思是“在订单集合里创建一个对象”，而order.create的语义是“完成一次下单业务”。前者更强调数据操作，后者更强调业务动作。下单这个业务里可能涉及创建订单、扣库存、发通知、更新用户积分，如果把这些都拆成REST调用，前端就要自己编排多个请求，状态一致性极难保证。而用cmd，后端网关可以把这个命令路由到一个编排服务里，由服务端统一完成整个业务。

2.2 notify（通知）到底是什么

notify负责解决“后端什么时候有结果、什么时候有新状态”的问题。后端执行完命令，或者某个内部事件发生之后，网关会主动向相关的前端推送一条通知消息。通知的内容不是大段大段的业务数据堆砌，而是一个事件描述，附带必要的载荷。

一个通知的简单示例：

{ "event": "order.created", "correlationId": "09f3c1a2-7d8b-4e6f-9a1b-2c3d4e5f6a7b", "payload": { "orderId": "ord_20250101_0001", "status": "CREATED" }, "ts": 1735206405120 }

我用event字段替代cmd来区分两类消息的方向性，correlationId用来把通知和之前发出的某条命令关联起来，方便前端对账。这样前端收到通知时，既知道“发生了什么事”，也知道“这跟我哪条请求相关”。

为什么要用notify而不是让前端继续轮询？因为轮询本质上是“盲猜”，效率低不说，体验还差。notify能做到两件事：第一，状态变化由后端主动发起，前端收到的永远是增量事件，不需要假装自己什么都知道；第二，前端可以按需订阅，只处理和自己页面相关的事件。一个管理后台里，订单模块的页面只关心和订单相关的事件，用户模块的页面只关心用户相关的事件，订阅关系清晰，推送压力也小。

2.3 为什么用cmd + notify而不是继续堆REST接口

很多人会问：REST接口用了这么多年，大家不都习惯了？为什么非要多设计一层网关？

我的判断依据是：你做的是业务系统，不是在给资源做管理界面。业务系统里充满了跨实体的动作、需要事务保障的流程、依赖时序的联动。用REST表达这些动作，一定会出现“接口往业务流程上硬靠”的情况。订单创建、退款、审核、通过，这些动作勉强还能找出资源路径，但像“导出三个月内的销售报表并发邮件给老板”这种复杂动作，REST的url都不好编，更别提参数校验和状态跟踪。cmd+notify是面向动作和事件建模的，天然适合表达这类业务。

再加上我当时的痛点是解耦。用REST，前端和REST接口之间仍然存在“调用依赖”：前端得知道url、知道方法、知道返回结构。而用cmd+notify，前端和网关之间只有一条协议，前端不知道也不关心后端函数叫什么名字、数据库表怎么设计。两边各自演进，只要命令名字和事件名字不随便改，谁也影响不到谁。这个理解就是“解耦”最落地的地方。

3. HermesGateway的核心实现：从协议到机制

3.1 网关层的整体结构

HermesGateway的定位是前后端之间的一个轻量中间层。整体结构分四块：接入层、命令路由层、命令执行层、通知广播层。

接入层负责维持与前端的长连接。0.5版本我用了WebSocket做传输通道，主要因为它在浏览器环境里支持好、双向通信方便。命令路由层维护一张命令注册表，cmd名字和处理器函数一一对应；它收到一条前端消息后，先做消息解析、基础校验（协议版本、token），然后根据cmd找到处理器，把控制权交给执行层。执行层跑完业务逻辑，产出结果。结果不会直接以“HTTP响应”的形式返回前端，而是被转成事件，由通知广播层推送给订阅者。

画成结构就是这么一条链：

• 前端 → WebSocket → 接入层 → 命令路由层 → 命令执行层 → 业务方法
• 业务方法产出结果 → 通知广播层 → WebSocket → 前端

这个链路最关键的设计是：命令执行的返回不是响应，而是事件。前端发一条order.create命令之后，并不阻塞等待一个同步返回，而是订阅一个order.created事件。这个转变让人一下子从“请求-响应”思维跳到了“命令-事件”思维。

3.2 命令注册表和处理链路

命令注册表是HermesGateway的核心数据结构。本质上就是一个映射表：命令名 → 处理器函数。我用Python的FastAPI搭后端，定义了一个装饰器来注册命令：

# gateway/registry.py from typing import Callable, Dict CommandHandler = Callable[[dict], dict] class CommandRegistry: def __init__(self): self._handlers: Dict[str, CommandHandler] = {} def register(self, cmd: str): def decorator(func: CommandHandler): if cmd in self._handlers: raise RuntimeError(f"cmd {cmd} already registered") self._handlers[cmd] = func return func return decorator def get_handler(self, cmd: str) -> CommandHandler: handler = self._handlers.get(cmd) if handler is None: raise KeyError(f"unknown cmd: {cmd}") return handler registry = CommandRegistry()

然后在具体的service文件里注册命令：

# services/order_service.py from gateway.registry import registry @registry.register("order.create") def create_order(params: dict) -> dict: # 这里做真正的业务处理：创建订单、扣库存、落库 order_id = create_order_record(params) return { "orderId": order_id, "status": "CREATED" }

网关的核心处理逻辑是这样一个异步循环：

# gateway/ws_gateway.py async def handle_client_message(ws, raw_message: str): try: message = json.loads(raw_message) ver = message.get("ver") if ver != 1: await ws.send_text(build_error_notify(message.get("id"), "UNSUPPORTED_PROTOCOL")) return cmd = message.get("cmd") req_id = message.get("id") handler = registry.get_handler(cmd) # 在这里可以统一做鉴权、参数校验、链路追踪 await check_auth(message.get("token"), cmd) payload = await handler(message.get("params") or {}) notify_event = { "event": cmd_to_event_name(cmd), # order.create -> order.created "correlationId": req_id, "payload": payload, "ts": current_millis() } await ws.send_text(json.dumps(notify_event)) except KeyError: await ws.send_text(build_error_notify(message.get("id"), "UNKNOWN_CMD")) except Exception as e: # 统一异常处理，避免业务错误直接暴露给前端 await ws.send_text(build_error_notify(message.get("id"), "INTERNAL_ERROR", str(e)))

这段代码虽然短，但已经能看清cmd+notify的核心循环了：收到命令、校验、路由、执行、转事件、推送。前端的id字段在回调里变成了correlationId，两条消息因此完成了关联。

3.3 通知广播的订阅模型

如果只是“命令执行完把结果返回给发送方”，那本质上还是一个一问一答的过程，跟前端调接口没有本质区别。cmd+notify的另一个关键优势在“广播”。HermesGateway里有一个轻量的事件中心，维护“事件名 → 订阅者集合”的关系：

# gateway/event_bus.py import asyncio from typing import Dict, Set, List class EventBus: def __init__(self): self._subscribers: Dict[str, Set[str]] = {} self._connections: Dict[str, List] = {} def subscribe(self, session_id: str, events: List[str]): for event in events: self._subscribers.setdefault(event, set()).add(session_id) def unsubscribe(self, session_id: str, events: List[str]): for event in events: if session_id in self._subscribers.get(event, set()): self._subscribers[event].remove(session_id) async def publish(self, event: str, payload: dict): for session_id in self._subscribers.get(event, []): ws = self._connections.get(session_id) if ws and not ws.closed: await ws.send_text(json.dumps({ "event": event, "payload": payload, "ts": current_millis() }))

前端在连接网关之后，除了发命令，还会先发一条订阅消息，告诉网关“我这个页面关心哪些事件”。比如订单页面订阅order.created、order.refunded，用户页面订阅user.login_failed、user.updated。这样网关在内部状态变化时，就能精准地把通知推给真正需要它的前端，而不是全量广播给所有连接。

我用一个生活化类比来解释这层设计：cmd是客人对服务员喊“点菜”，notify是后厨做完菜之后服务员端着菜喊“XX号的菜好了”。客人不用反复跑去后厨问“好了没有”，后厨也不用知道每一桌客人分别是谁，只需要通过服务员把菜端到对应编号的桌子。网关就是这个服务员。前端通过订阅告诉服务员“我是哪一桌、我关心哪些菜”，后端做完菜之后只管往事件中心放，路由和投递由网关完成。

4. 实操过程：从0到0.5版本的搭建记录

4.1 最小闭环先行：一个命令一个通知

做架构最忌讳上来就铺开。HermesGateway的0.5版本，我是从一条最小链路开始的：前端发一条ping命令，后端收到后回一个pong事件。这个闭环看似无聊，但把协议格式、连接管理、事件订阅、错误处理都验证了一遍。

具体步骤：

1. 搭一个FastAPI应用，挂两个路由：一个HTTP GET/health用于健康检查，一个WebSocket/ws用于接入前端。
2. 初始化CommandRegistry，注册ping处理器。
3. 初始化EventBus，维护连接集合。
4. 前端创建一个WebSocket连接，先发订阅请求，再发ping命令。
5. 后端收到ping后，生成pong事件推回前端。
6. 前端收到pong事件，确认全链路可用。

这一步最大的价值在联调。我说句实在话，很多时候架构讨论得再完美，真正动手一联调就会发现各种边界问题：字段名对不上、时间格式不统一、消息体里偶尔混进个BOM头导致JSON解析失败。最小闭环能让这些问题提前暴露。

4.2 前端消费模型的实现

前端的改造比后端复杂，因为要处理异步消息驱动的逻辑。原来的代码风格是“点击按钮，然后等response回来再操作”，现在变成了“点击按钮，发命令，等到事件回调再操作”。我在前端封装了一个统一的连接层：

// frontend/gateway-client.js class HermesClient { constructor(url) { this.ws = new WebSocket(url); this.requestMap = new Map(); // requestId -> {resolve, reject, timer} this.eventHandlers = new Map(); // eventName -> [handler,...] this.pendingSubscribe = []; this.ws.onmessage = (evt) => this._onMessage(evt.data); this.ws.onopen = () => this._flushSubscribe(); } subscribe(events, handler) { for (const event of events) { if (!this.eventHandlers.has(event)) { this.eventHandlers.set(event, []); } this.eventHandlers.get(event).push(handler); } if (this.ws.readyState === WebSocket.OPEN) { this.ws.send(JSON.stringify({ ver: 1, type: 'subscribe', events: events })); } else { this.pendingSubscribe.push(events); } } sendCommand(cmd, params, timeout = 10000) { return new Promise((resolve, reject) => { const requestId = this._uuid(); const timer = setTimeout(() => { this.requestMap.delete(requestId); reject(new Error('cmd timeout: ' + cmd)); }, timeout); this.requestMap.set(requestId, { resolve, reject, timer }); this.ws.send(JSON.stringify({ ver: 1, id: requestId, cmd: cmd, params: params || {} })); }); } _onMessage(raw) { const msg = JSON.parse(raw); if (msg.correlationId && this.requestMap.has(msg.correlationId)) { // 这是某条命令的结果通知，走Promise回调 const entry = this.requestMap.get(msg.correlationId); clearTimeout(entry.timer); this.requestMap.delete(msg.correlationId); if (msg.status === 'OK') { entry.resolve(msg.payload); } else { entry.reject(new Error(msg.payload?.message || 'cmd failed')); } return; } // 这是后端主动推送的事件，走订阅分发 const handlers = this.eventHandlers.get(msg.event) || []; handlers.forEach((handle) => handle(msg.payload, msg.event)); } }

这样一个客户端封装同时解决了两件事：命令的结果通过Promise回传给调用方，符合前端写异步逻辑的习惯；后端主动推送的事件则通过订阅分发到对应的处理函数。前端业务代码里，操作和状态更新被分到了两条路径上，彼此不干扰。

4.3 逐步补全生产可用能力

最小闭环跑通后，我逐步往HermesGateway里补了四块能力：

第一块是错误处理。原先命令执行器里直接抛Python异常，前端收到的是一串裸异常信息。后来我定义了统一的错误码体系：UNKNOWN_CMD、PARAM_INVALID、UNAUTHORIZED、BIZ_ERROR、INTERNAL_ERROR，每条通知里都有status字段表示成功或失败。前端拿状态码做提示，不会因为后端的异常信息变化而产生错乱。

第二块是超时机制。cmd+notify是异步的，理论上后端可能永远不会回消息。我在前端加了一层超时控制，默认10秒没收到对应通知就reject，并且把requestMap里挂起的条目清理掉，防止内存泄漏。后端这边也做了兜底：命令执行如果超过15秒，主动返回一个超时的错误通知。

第三块是幂等控制。网络环境没那么理想，WebSocket重连后，前端可能会自动重发未确认的命令。如果不做幂等，一条“扣库存”的命令就被执行了两次。我的做法是在网关层加了一张请求去重表，用id字段作为幂等键，同一个id的命令在5分钟内只允许执行一次，重复到达直接返回第一次的结果。

第四块是断线重连和状态恢复。WebSocket断线之后，前端的订阅关系会丢失。我让HermesClient在检测到断线时，自动重连，并且在onopen之后重新发送最后一次确认成功的订阅列表。对于“断线期间后端产生的事件”，我加了一个轻量的事件补偿机制：服务端按会话保留最近1分钟的事件游标，前端重连时可以带上次收到的最后事件时间戳，网关把漏掉的事件补发一遍。

表格整理这四块能力：

4.4 实际落地效果与性能观察

我把HermesGateway接到项目里跑了两周，前后端对比还是很明显的。原来前端为了获取后端状态变化，全局有七八个定时器在轮询，改造之后定时器全部取消，数据更新完全依赖事件推送。网关单机扛了800多个WebSocket连接，命令的平均处理耗时在30毫秒以内（主要是业务逻辑耗时），事件广播的推送延迟小于10毫秒。

我也测过一些异常场景，比如后端服务重启时，正在处理中的命令会失败，网关通过错误通知把失败原因推给前端，前端的全局loading态能正确消失，不会出现“一直转圈”的卡死现象。再比如前端页面切换时，订阅关系会动态调整，旧页面的订阅退订及时，网关不会给不存在的页面继续推数据。

5. 踩坑记录与排查经验

5.1 常见问题速查表

实现过程中我遇到不少问题，按排查价值整理成一张速查表，你在自己的项目里遇到类似现象可以直接对照。

5.2 我在调试中发现的几个容易忽略的细节

第一个细节是心跳的时机。WebSocket看起来简单，但很多代理服务器（特别是nginx）默认对空闲连接有超时断开策略。如果前端和后端之间长时间没有消息，连接会被默默掐断，而两边的程序都不会收到报错，表现出来就是“过了一阵子，推送突然不来了”。解决方式很直接：设置一个30秒的定时器，网关主动发ws.ping，前端收到后自动回pong。这事情其实简单，但不做的话排查起来非常难受，因为问题不是每次都复现，而是随机发生。

第二个细节是事件名与命令名的命名规范。我一开始把命令名设计成动词开头，事件名直接替换时态，比如order.create对应order.created。这个思路在简单场景下没问题，但业务复杂之后，一个命令可能会触发多个事件。比如下单这个命令，可能会触发order.created、inventory.deducted、customer.points_added三个事件。前端如果只订阅order.created，另外两个事件对它没有意义，但网关还是会推给所有订阅了相关事件名的连接。后来我调整了订阅粒度，要求前端的每个订阅都明确写清楚关心的事件名，不做隐式“全量通知”。

第三个细节是命令结果的封装。0.5版本早期，我让后端处理器直接返回业务对象，然后网关把整个对象作为payload推给前端。后来发现这样容易泄露后端内部结构，比如一个订单对象里带了数据库自增id、内部状态码、甚至冗余关联字段。现在我的做法是：每个命令处理器在返回之前，都会经过一个to_view的映射方法，只暴露前端真正需要的字段。这层防护的意义在于，后端再怎么重构数据库，只要to_view的输出结构稳定，前端就稳定。

5.3 和旧REST接口的兼容过渡

一个现实问题是，让现有项目一天之内完全切换到cmd+notify不现实。我在改造过程中采用的策略是“双轨并行、逐步迁移”。

具体做法是：

• 网关直接复用旧系统的鉴权体系，前端登录后拿到的token同时适用于REST接口和WebSocket连接。
• 新功能一律走cmd+notify协议，不要为临时需求再新增REST接口。
• 旧接口仍然保留，前端逐步把高频使用的接口迁移到命令模式。
• 网关里做好日志记录，每条命令和每条通知都带requestId，方便出问题时在日志系统里把全链路串起来。

这样过渡的好处是：团队不需要做一次“大爆炸式”的重写，每个迭代都可以搬运一小块功能，验证没问题再继续下一块。0.5版本只覆盖了核心链路，剩下的适配器、鉴权细粒度、SDK封装都在后续版本里补齐。

5.4 这套方案的边界在哪里

最后说点冷静的。cmd+notify不是万能的，它适合、也不适合的场景我都摸了一遍。

适合的场景是：中大型前端应用，状态联动多、需要实时推送、业务逻辑复杂。比如数据大屏、管理后台、运维平台、工单系统，这些场景对解耦和实时性的要求都很高。

不太适合的场景也有。比如一个纯粹的读多写少的展示型页面，数据很少变化，直接REST接口可能更简单，没必要为了用模式而用模式。再比如团队规模很小、前后端互相耦合程度不高，引入网关多了一层维护成本，性价比也低。另外，如果你需要强一致性的同步调用语义，比如跨服务调用要求立刻拿到结果并提交事务，cmd+notify这种异步模式会让事务边界变得更复杂，这时候还是要谨慎。

我个人在实际操作中的体会是：解耦这件事，工具只是辅助，真正起作用的是想清楚“前端和后端各自该承担什么职责”。cmd+notify只是把这种职责划分变成了可执行的协议。0.5版本虽然简陋，但它证明了“面向命令和事件做交互”这条路是走得通的。下一步我准备把协议定义抽成独立的SDK，让前端和后端都通过SDK生成消息，减少手写JSON导致的低级错误；再往后就是补链路追踪和消息审计，让每一次命令的执行链路都可以回溯。如果你也在评估类似的重构，建议先花一天把最小闭环跑通，再决定要不要全面拥抱。