企业官网建设流程全解析

接口层解决"怎么调接口"，功能模块解决"接口怎么组织成业务能力"。模块设计的好坏决定了项目从10个功能扩展到100个功能时会不会失控。

一、四层架构——从接口到业务

接口层：统一的 HTTP 调用封装（鉴权、错误、日志、频控），不含任何业务逻辑。能力层：把单个接口封装成业务可理解的能力——消息能力（收发消息、查历史）、联系人能力（查详情、改备注）、群能力（查群信息、管成员）。

服务层：编排多个能力完成业务流程——欢迎服务（改备注+建档+发欢迎语）、客服路由服务（识别意图+转对应客服）。接入层：对外暴露的入口——Webhook 回调入口、定时任务入口、管理后台 API。四层从上到下依赖，不跨层调用。

二、模块划分原则——按业务能力不按接口分类

错误的模块划分是"发送模块、接收模块、查询模块"——这是按 HTTP 方法分类，业务找功能时要跨多个模块。正确的划分是"消息模块、联系人模块、群模块"——业务场景涉及的能力在同一个模块里。

每个模块内部再分：接口调用（调 Eyun 的具体接口）、数据模型（本地表和缓存）、业务逻辑（能力封装）。模块对外只暴露业务方法，不暴露底层接口调用。

三、模块间通信——事件总线解耦

好友通过后要触发三个动作：建档、改备注、发欢迎语。如果直接在好友模块里调三个模块，模块间就是硬编码依赖。用事件总线解耦：好友模块发出"好友通过"事件，联系人模块监听后建档，消息模块监听后发欢迎语。

事件驱动的好处：加新动作（比如"同步到CRM"）只需要新模块监听事件，不改好友模块代码。

四层架构对照

模块化实现结构

project/ ├── api/ # 接口层 │ └── client.py # 统一HTTP封装 ├── capabilities/ # 能力层 │ ├── message.py # 消息能力：收发/历史 │ ├── contact.py # 联系人能力：查询/备注 │ └── group.py # 群能力：群信息/成员 ├── services/ # 服务层 │ ├── welcome.py # 欢迎流程 │ ├── support_router.py # 客服路由 │ └── tag_pipeline.py # 标签流水线 ├── entrypoints/ # 接入层 │ ├── webhook.py # 回调入口 │ ├── scheduler.py # 定时任务 │ └── admin_api.py # 管理后台 └── core/ ├── event_bus.py # 事件总线 └── cache.py # 缓存

# 事件总线解耦示例 class EventBus: def __init__(self): self.listeners = {} def on(self, event, handler): self.listeners.setdefault(event, []).append(handler) def emit(self, event, data): for h in self.listeners.get(event, []): h(data) bus = EventBus() # 各模块注册监听 bus.on("friend_passed", contact_service.build_profile) bus.on("friend_passed", contact_service.set_remark) bus.on("friend_passed", message_service.send_welcome) bus.on("friend_passed", crm_service.sync_customer) # 新增不改旧码 # 接入层只发事件 @app.post("/webhook") def webhook(): d = request.json if d.get("eventType") == "friend_add": bus.emit("friend_passed", d) return {"code": "1000"}

落地建议

架构在项目启动时就按四层搭好，哪怕初期每层只有一两个文件。模块划分按业务能力（消息/联系人/群），模块间用事件解耦。这套架构的回报在功能增加时才体现——加功能不改旧代码，是可维护性的核心。接口能力清单参考 Eyun 开发文档。