接口层解决"怎么调接口"，功能模块解决"接口怎么组织成业务能力"。模块设计的好坏决定了项目从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 开发文档。