获取联系人只是个开始把联系人同步进业务系统才是目的。同步不是拉一次写一次要解决全量初始化、增量更新、冲突解决、质量校验四个问题。这四个环节没做好业务系统里的联系人数据迟早变得又旧又乱。一、全量初始化——第一次同步打底第一次同步要把所有联系人拉下来写进业务库。联系人多的账号有几千个要点是分批写入和数据完整性。分批写入——一次几百条批量插不要一条一条来几千条单条插入耗时太长还容易超时。数据完整性——拉完所有页才算全量中途失败要能从断点继续。全量只做一次。做完记下当前版本号或时间戳之后就走增量不再全量拉。全量反复做是浪费——接口慢、写库压力大还容易把已更新的数据覆盖回旧的。联系人拉取和分页游标的接口在 Eyun 开发文档 中有对应支撑。二、增量同步与冲突解决增量同步靠版本号或时间戳只拉变化部分。做增量要有一个可靠的比较基准——版本号变了才拉没变就跳过能省掉大量无效接口调用。冲突是增量同步里最麻烦的一环。两边都改了同一个联系人——微信侧改了备注业务系统那边改了标签。冲突必须有明确规则字段级合并还是以某一边为准。规则不明确的话同步逻辑就变成随机覆盖数据越同步越乱。常见做法是核心字段以微信为准业务字段以系统为准两边都不动对方的字段。联系人和标签查询的接口在 Eyun 开发文档 中有对应能力。三、同步质量校验同步完要跑校验。校验三个点——条数对不对同步前后数量差多少、关键字段有没有空备注、标签这些、有没有重复记录同一个联系人写了两条。校验不通过要告警而不是静默通过。静默通过的问题在于数据错了很久之后才被发现那时候已经影响到业务判断了。校验结果按次记录能看出同步质量的趋势——同时校验失败率上升说明接口或映射规则出了问题。联系人同步方案对照同步类型触发方式数据范围主要风险全量初始化首次/重建全部联系人写入超时增量同步版本号变化变化部分冲突覆盖质量校验同步后抽样计数静默失败联系人增量同步与冲突解决实现class ContactSynchronizer: def __init__(self): self.api WeChatAPI() self.db BusinessDB() def full_sync(self): # 全量初始化分批写入 cursor None while True: resp self.api.get_contacts(cursor, limit200) self.db.batch_upsert(resp[list]) # 分批写库 cursor resp.get(next_cursor) if not cursor: break self.db.save_version(resp[version]) # 记版本号 def incremental_sync(self): # 增量同步版本号变化才拉 local_ver self.db.get_version() remote_ver self.api.get_version() if local_ver remote_ver: return changes self.api.get_changes(local_ver) for contact in changes[updated]: merged self.merge(contact) # 冲突解决 self.db.upsert(merged) for wxid in changes[deleted]: self.db.soft_delete(wxid) # 软删除保历史 self.db.save_version(remote_ver) def merge(self, remote): # 冲突解决字段级各管各的 local self.db.get_contact(remote[wxid]) if not local: return remote result dict(local) # 微信侧字段以远端为准 for field in [nickname, remark, avatar]: result[field] remote.get(field) # 业务字段保留本地tags为系统侧维护 return result def verify(self): # 质量校验条数空值重复 remote_count self.api.count_contacts() local_count self.db.count_contacts() if abs(remote_count - local_count) 5: self.alert(联系人数量不一致) # 差异告警 nulls self.db.count_null_fields([nickname]) if nulls 0: self.alert(f昵称空值{nulls}条)落地建议全量只做一次——做完记版本号走增量反复全量既慢又容易覆盖新数据。冲突规则要明确——字段级划分边界核心字段以微信为准、业务字段保留本地。质量校验要告警——条数、空值、重复三个点跑完对不上就报警别静默通过。分批写入不能省——几千条单条插会超时。微信侧的联系人拉取和版本接口由Eyun这类个人微信API平台 提供同步、合并和校验逻辑在自建服务实现接口字段以平台开发文档为准。