接口封装这事很多人理解成写个函数包一下——把 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 管理AuthManagerToken 不散落报身份证集中管参数参数组装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, retry0): 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 开发文档。