好友和群的管理操作有不少共性——都要按对象 ID 定位、都可能批量、都要控制频率。与其每个操作写一遍，不如做一个统一的管理客户端，把共性收口。这篇讲常见操作和这个收口怎么设计。
一、常见操作清单
好友侧：查列表、查详情、改备注、打标签。群侧：建群、拉人、踢人、查成员、改群名、发公告。
这些操作的共同点是"按对象 ID 定位"——好友是 wxid，群是群 ID。参数差异主要在操作类型和附加字段上。
二、统一收口：按操作类型路由
把操作做成"操作类型 + 目标 ID + 附加参数"的调用形式，客户端内部按操作类型路由到对应路径。
这样业务侧不用记一堆路径，调用形式统一，也方便在一处加日志和频率控制。后面加新操作，只往映射表里加一行。
三、批量操作：分批与结果确认
批量操作（批量拉人、批量打标签）要分批，每批之间留间隔。批量失败时不能只看到"整体失败"，要拿到逐条结果——哪几个成功、哪几个失败。
分批的意义在于失败可控：一批失败了只重试这一批，不用整体重来。
管理操作对照
操作类别 | 定位键 | 批量支持 | 注意点 |
|---|---|---|---|
好友查询 | wxid | 列表分页 | 游标要保存 |
好友更新 | wxid | 单条为主 | 长度限制 |
群成员管理 | 群 ID | 支持批量 | 分批留间隔 |
群信息维护 | 群 ID | 单条 | 长度限制 |
统一管理客户端实现
import time class ManageClient: API_PATH = { "friend.list": "/friend/list", "friend.remark": "/friend/update", "group.create": "/group/create", "group.add": "/group/add", "group.notice": "/group/notice", } def __init__(self, api, token): self.api = api self.token = token def operate(self, action, target_id, **params): # 统一入口：按操作类型路由到对应路径 path = self.API_PATH.get(action) if path is None: raise ValueError(f"未知操作: {action}") payload = {"target": target_id} payload.update(params) return self.api.post(path, payload, token=self.token) def batch_add(self, group_id, wxids, size=5): # 批量操作：分批执行，逐批确认结果 results = [] for i in range(0, len(wxids), size): chunk = wxids[i:i + size] resp = self.operate("group.add", group_id, members=chunk) results.append({ "chunk": chunk, "ok": resp.get("code") == 0, "detail": resp.get("data", {}), }) time.sleep(3) # 分批间隔，降低频率风险 return results落地建议
管理操作统一收口到一个客户端，业务侧按类型加目标 ID 调用，不用记路径。批量操作要分批并留间隔，把逐条结果返回，别只报整体成败。失败的批次单独重试，不整体重来。查询类注意游标持久化，更新类注意长度限制。微信侧的好友与群管理接口由Eyun这类个人微信API平台 提供，操作编排与批量控制策略在自建服务实现，具体字段以平台开发文档为准。
