通讯录维护不只是"缓存一下"那么简单。从首次同步到持续更新到异常修复，一套完整的维护方案包含四个环节。

一、首次全量同步——建立基线

接入账号后第一步是全量拉取联系人列表分页落库。这一次同步的数据是所有功能的地基：搜索、标签、消息反查都依赖本地库。

全量同步要做三件事：分页拉取直到取完、每条记录补全详情（列表接口返回的字段可能不全，详情字段要补）、记录同步时间戳。全量同步放后台异步执行，不阻塞启动流程。

二、事件驱动增量——日常更新的主力

好友关系变化（加人、删人）和资料变化（昵称、头像）靠事件回调实时感知。收到事件后立刻更新本地库对应记录，这是日常数据更新的主力通道。

事件通道的优势是实时和精准——只有变化的那条数据才触发更新，不做无用功。弱点是可能丢事件（回调超时、服务重启），需要补偿机制。

三、定时全量校准——补偿和修复

每天或每周跑一次全量比对：重新分页拉取联系人列表，和本地库做 diff。本地有但接口没有的（对方删了好友）标记失效，接口有但本地没有的（漏收加人事件）补录，字段不一致的更新。

校准频率取决于数据变化量和业务精度要求。客服场景建议每天凌晨跑一次，低频运营场景每周一次足够。

四、异常修复——数据不一致时的兜底

发现本地库和接口数据大面积不一致时（比如校准diff率超过5%），说明事件通道可能长期异常。这时的处理：暂停业务依赖本地数据的功能（避免用错误数据做决策）、重新全量同步、排查回调配置是否正常。

维护四环节对照

环节	频率	作用
首次同步	接入时一次	建立数据基线
事件增量	实时	日常更新主力
定时校准	每日/每周	补偿丢失事件
异常修复	diff率异常时	兜底修复

维护方案实现

def initial_sync():
    """首次全量同步"""
    page = 1
    total = 0
    while True:
        r = api("getContactList",
            {"wId": WID, "page": page, "pageSize": 100})
        if r.get("code") != "1000" or not r["data"]["list"]:
            break
        for c in r["data"]["list"]:
            # 列表字段可能不全，补详情
            detail = api("getContactDetail",
                {"wId": WID, "wxid": c["wxid"]})
            data = detail.get("data", c) if detail.get("code") == "1000" else c
            db.upsert("contacts", {**data, "synced_at": now_ts()})
            total += 1
        page += 1
    db.set_meta("last_full_sync", now_ts())
    return total

def daily_reconcile():
    """定时校准：diff并修复"""
    remote_ids = set()
    page = 1
    while True:
        r = api("getContactList", {"wId": WID, "page": page})
        if r.get("code") != "1000":
            break
        for c in r["data"]["list"]:
            remote_ids.add(c["wxid"])
            local = db.query("contacts", wxid=c["wxid"])
            if not local:
                db.upsert("contacts", {**c, "synced_at": now_ts()})
        page += 1

    local_ids = {r["wxid"] for r in db.query_all("contacts")}
    deleted = local_ids - remote_ids    # 本地有接口没有
    for wxid in deleted:
        db.update("contacts", wxid, {"active": 0})

    diff_rate = len(deleted) / max(len(local_ids), 1)
    if diff_rate > 0.05:
        alert(f"联系人diff率{diff_rate:.0%}，回调可能异常")

落地建议

四个环节缺一不可：首次同步建基线、事件增量管日常、定时校准做补偿、异常修复兜底。定时校准的 diff 率是事件通道健康度的监控指标——长期低于1%说明事件通道工作正常，突然升高要排查回调。接口字段说明参考 Eyun 开发文档。