接口层解决怎么调接口功能模块解决接口怎么组织成业务能力。模块设计的好坏决定了项目从10个功能扩展到100个功能时会不会失控。一、四层架构——从接口到业务接口层统一的 HTTP 调用封装鉴权、错误、日志、频控不含任何业务逻辑。能力层把单个接口封装成业务可理解的能力——消息能力收发消息、查历史、联系人能力查详情、改备注、群能力查群信息、管成员。服务层编排多个能力完成业务流程——欢迎服务改备注建档发欢迎语、客服路由服务识别意图转对应客服。接入层对外暴露的入口——Webhook 回调入口、定时任务入口、管理后台 API。四层从上到下依赖不跨层调用。二、模块划分原则——按业务能力不按接口分类错误的模块划分是发送模块、接收模块、查询模块——这是按 HTTP 方法分类业务找功能时要跨多个模块。正确的划分是消息模块、联系人模块、群模块——业务场景涉及的能力在同一个模块里。每个模块内部再分接口调用调 Eyun 的具体接口、数据模型本地表和缓存、业务逻辑能力封装。模块对外只暴露业务方法不暴露底层接口调用。三、模块间通信——事件总线解耦好友通过后要触发三个动作建档、改备注、发欢迎语。如果直接在好友模块里调三个模块模块间就是硬编码依赖。用事件总线解耦好友模块发出好友通过事件联系人模块监听后建档消息模块监听后发欢迎语。事件驱动的好处加新动作比如同步到CRM只需要新模块监听事件不改好友模块代码。四层架构对照层级职责依赖方向接入层Webhook/定时任务/后台API→服务层服务层业务流程编排→能力层能力层业务能力封装→接口层接口层HTTP调用封装无模块化实现结构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 开发文档。