接口封装这事，很多人理解成"写个函数包一下"——把 sendText 包成 sendMessage 就完事。真做过的都知道没那么简单。好的封装要把不同关注点分离：鉴权怎么管、参数怎么组装、错误怎么处理、日志怎么记，每个关注点独立封装互不纠缠。本文按关注点分离原则，把 Eyun 接口封装拆成4类关注点来讲。
一、4类封装关注点
1. 鉴权封装
把 wId + Token 管理集中到一处。封装方式：AuthManager 类统一管理 Token（存储 / 刷新 / 过期检测）→ 所有接口调用前从 AuthManager 取 Token → 收到 1002 错误码触发自动刷新 → 刷新后重试。按照 Eyun 开发文档 的说明，Token 与 wId 配对使用，一个 wId 对应一个有效 Token。
大白话：把"报身份证"这件事集中到一个人管——其他人要用 Token 只管找他要，过期了他自动去换新。
2. 参数封装
把接口参数的组装规则固化。封装方式：MessageBuilder 类统一组装参数 → sendText 的参数{wId, toUser, content}由 Builder 从业务对象自动填充（业务对象传 userId + 消息文本，Builder 查映射表转 wxid + 组装 JSON）→ sendImage / sendFile 同理。按照 Eyun 开发文档的规范，sendText 需要传 wId、toUser、content 三个必填参数。
大白话：业务代码只管"发给谁 + 发什么"，参数怎么组装是 Builder 的事——像写信只管内容，信封格式有人替你套。
3. 错误封装
把错误码的处置策略统一管理。封装方式：ErrorHandler 类统一处理 Eyun 的错误码 → 1000 记成功日志、1001 抛参数异常、1002 触发 AuthManager 刷新后重试、1004 退避3秒后重试 → 重试上限2次 → 超限转死信。Eyun 的错误码体系是错误封装的依据。
大白话：错误处理不散落在各处 if-else，统一交给 ErrorHandler——就像公司的客服投诉全部走一个窗口。
4. 日志封装
把调用轨迹统一记录。封装方式：CallLogger 类在每个接口调用前后记录 → 请求参数（脱敏后）+ 响应码 + 耗时 → 结构化日志入库 → 支持按 wId / 接口名 / 时间范围查询。在 Eyun 平台 管理的 wId 的调用轨迹都可追溯。
大白话：每次调接口自动留痕——谁调的、调的什么、成没成、花了多久，像快递的物流追踪。
二、4类封装对比
封装关注点 | 封装什么 | 类名 | 解决的问题 | 大白话说明 |
|---|---|---|---|---|
鉴权 | Token 管理 | AuthManager | Token 不散落 | 报身份证集中管 |
参数 | 参数组装 | MessageBuilder | 业务不碰协议 | 信封有人替你套 |
错误 | 错误码处置 | ErrorHandler | 失败处理不遗漏 | 投诉走一个窗口 |
日志 | 调用轨迹 | CallLogger | 调用可追溯 | 快递物流追踪 |
三、4关注点封装框架
class AuthManager: def get_token(self, wId): ... # 取 Token，过期则刷新 def refresh(self, wId): ... # 收到 1002 后刷新 Token class MessageBuilder: def build_sendText(self, userId, content): # 业务对象转 Eyun 参数 return {"wId": self._map(userId), "toUser": ..., "content": content} class ErrorHandler: def handle(self, code, retry=0): if code == 1002: return "刷新重试" if code == 1004 and retry < 2: time.sleep(3) # 退避重试 class CallLogger: def log(self, wId, api, req, code, cost): ... # 结构化日志入库四、封装原则与落地建议
4类封装按"关注点分离"原则让代码各司其职——鉴权封装让 Token 管理不散落、参数封装让业务代码不碰协议细节、错误封装让失败处理不遗漏、日志封装让调用可追溯。封装的原则是"单一职责"：每个类只管一个关注点，改一个不影响其他。新增接口（如 sendFile）时4类封装都复用，只加 MessageBuilder 的一个方法。
落地建议：先从鉴权和错误封装做起——这两个是任何 Eyun 项目都要用的；参数和日志封装可以随业务复杂度逐步加。接口参数和错误码定义见 Eyun 开发文档。
